When you create a library in TypeScript, you will often be able to just publish it with your current toolset; however, once your library grows and grows, you might want to make it possible for people of your library to use TypeScript Module Augmentation to merge additional types into the types that you provide.
Unfortunately, this introduces a big issue in TypeScript. Even when
re-exporting all your interfaces/types/classes in a root index.d.ts
that you
are referencing in "types"
in your package.json
, TypeScript still won't
properly apply folder-nested module augmentation (i.e. a type that's in
your-package/dist/lib/structures/SomeClass.d.ts
) when augmenting like this:
declare module 'your-package' {}
Without this package, your users would have to augment the type like this:
declare module 'your-package/dist/lib/structures/SomeClass' {}
As you might guess, this is extremely bad developer experience because you cannot apply all module augmentations in 1 block. That's where this rollup module comes in - now, you can bundle types in a developer-friendly way and make life easier for everyone involved.
The library uses rollup with rollup-plugin-dts under the hood. It will execute a few steps:
- It cleans the configured distribution directory (
--dist
flag ordist
in config). - It calls the
--build-script
(orbuildScript
in config) to build your code with your compiler. This defaults tobuild
. - It executes rollup to bundle your types into 1
index.d.ts
file, output to the configureddist
directory. - It removes all other
.d.ts
and.d.ts.map
files from your configureddist
directory as they are now superfluous.
You can use the following command to install this package, or replace
npm install -D
with your package manager of choice.
npm install -D @favware/rollup-type-bundler
Or install it globally:
npm install -g @favware/rollup-type-bundler
Then call the script with rollup-type-bundler
or rtb
:
rollup-type-bundler --dist ./dist # Add any other flags or use --help
rtb --dist ./dist # Add any other flags or use --help
Alternatively you can call the CLI directly with npx
:
npx @favware/rollup-type-bundler --dist ./dist # Add any other flags or use --help
You can provide all options through CLI flags:
Usage: rollup-type-bundler [options]
Options:
-V, --version output the version number
-d, --dist <dist> The dist directory to target
-b, --build-script [buildScript] The build script to call after cleaning your dist directory (default: "build")
-v, --verbose Print verbose information (default: false)
-e, --external [external...] Repeatable, each will be treated as a new entry. Library or libraries to treat as external in Rollup (see:
https://rollupjs.org/guide/en/#warning-treating-module-as-external-dependency) (default: [])
-h, --help display help for command
Or, you can set most of these options through a configuration file. This
file should be located at your current working directory (where you're
calling this package). It should be named .rollup-type-bundlerrc
, optionally
suffixed with .json
, .yaml
, or .yml
.
--dist
maps todist
--build-script
maps tobuildScript
--verbose
maps toverbose
--external
maps toexternal
When using .rollup-type-bundlerrc
or .rollup-type-bundlerrc.json
as
your config file you can also use the JSON schema to get schema
validation. To do so, add the following to your config file:
{
"$schema": "https://raw.githubusercontent.com/favware/rollup-type-bundler/main/assets/rollup-type-bundler.schema.json"
}
Example JSON file:
{
"$schema": "https://raw.githubusercontent.com/favware/rollup-type-bundler/main/assets/rollup-type-bundler.schema.json",
"dist": "./dist",
"buildScript": "build",
"verbose": true,
"external": ["stream", "url"]
}
Example YAML file:
dist: './dist'
buildScript: build
verbose: true
external:
- stream
- url
Favware projects are and always will be open source, even if we don't get donations. That being said, we know there are amazing people who may still want to donate just to show their appreciation. Thank you very much in advance!
We accept donations through Ko-fi, Paypal, Patreon, GitHub Sponsorships, and various cryptocurrencies. You can use the buttons below to donate through your method of choice.
Donate With | Address |
---|---|
Ko-fi | Click Here |
Patreon | Click Here |
PayPal | Click Here |
GitHub Sponsors | Click Here |
Bitcoin | 1E643TNif2MTh75rugepmXuq35Tck4TnE5 |
Ethereum | 0xF653F666903cd8739030D2721bF01095896F5D6E |
LiteCoin | LZHvBkaJqKJRa8N7Dyu41Jd1PDBAofCik6 |
Thanks goes to these wonderful people (emoji key):
Jeroen Claassens 💻 🎨 🤔 🚇 🚧 📦 📆 |
This project follows the all-contributors specification. Contributions of any kind welcome!