@favware/rollup-type-bundler v4.0.0

rollup-type-bundler

A small CLI tool to bundle types with rollup

Description

When creating a library with TypeScript you will often be able to just publish it with your current toolset, however once your library grows and grows then 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.

This however 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 (i.e. a type that's in your-package/dist/lib/structures/SomeClass.d.ts) module augmentation when augmenting with:

declare module 'your-package' {}

Without this package your users would have to augment the type with:

declare module 'your-package/dist/lib/structures/SomeClass' {}

this is extremely bad developer experience because you cannot apply all module augmentations in 1 block. To solve this issue, there is this library.

How this works

The library uses rollup with rollup-plugin-dts under the hood. It will execute a few steps:

1. It cleans the configured dist directory (--dist flag or dist in config).
2. It calls the --build-script (or buildScript in config) to build your code with your compiler. This defaults to build.
3. It executes rollup to bundle your types into 1 index.d.ts file, output to the configured dist directory.
4. It removes all other .d.ts and .d.ts.map files from your configured dist directory as they are now superfluous.

Installation

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

Usage

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 provide most of these options through a configuration file. The following files are supported:

• .rollup-type-bundlerrc
• .rollup-type-bundlerrc.json
• .rollup-type-bundlerrc.yaml
• .rollup-type-bundlerrc.yml

The file should either be located at the current working directory from where this rollup-type-bundler is called, or provided as a custom path with --config.

Fields in config file

• --dist maps to dist
• --build-script maps to buildScript
• --verbose maps to verbose
• --external maps to external

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. Add 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

Buy us some doughnuts

Favware projects is 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 crypto currencies. You can use the buttons below to donate through your method of choice.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!