tsup/docs/README.md

Bundle your TypeScript library with no config, powered by esbuild.

What can it bundle?

Anything that's supported by Node.js natively, namely .js, .json, .mjs. And TypeScript .ts, .tsx. CSS support is experimental.

This project is designed for bundling Node.js libraries.

Install

Install it locally in your project folder:

npm i tsup -D
# Or Yarn
yarn add tsup --dev

You can also install it globally but it's not recommended.

Usage

Bundle files

tsup [...files]

Files are written into ./dist.

You can bundle multiple files in one go:

tsup src/index.ts src/cli.ts

This will output dist/index.js and dist/cli.js.

Code splitting is enabled by default and supported in cjs and esm format.

Excluding packages

By default tsup bundles all import-ed modules but dependencies and peerDependencies in your packages.json are always excluded, you can also use --external <module> flag to mark other packages as external.

Generate declaration file

tsup index.ts --dts

This will emit ./dist/index.js and ./dist/index.d.ts.

If you have multiple entry files, each entry will get a corresponding .d.ts file. So when you only want to generate declaration file for a single entry, use --dts <entry> format, e.g. --dts src/index.ts.

Note that --dts does not resolve external (aka in node_modules) types used in the .d.ts file, if that's somehow a requirement, try the experimental --dts-resolve flag instead.

Generate sourcemap file

tsup index.ts --sourcemap

This will emit ./dist/index.js and ./dist/index.js.map.

If you set multiple entry files, each entry will get a corresponding .map file.

Bundle formats

Supported format: esm, cjs, (default) and iife.

You can bundle in multiple formats in one go:

tsup src/index.ts --format esm,cjs,iife

That will output files in following folder structure:

dist
├── index.mjs         # esm
├── index.global.js   # iife
└── index.js          # cjs

If the type field in your package.json is set to module, the filenames will be slightly different:

dist
├── index.js          # esm
├── index.global.js   # iife
└── index.cjs         # cjs

Read more about esm support in Node.js.

If you don't want extensions like .mjs or .cjs, e.g. you want your library to be used in a bundler (or environment) that doesn't support those, you can enable --legacy-output flag:

tsup src/index.ts --format esm,cjs,iife --legacy-output

..which outputs to:

dist
├── esm
│   └── index.js
├── iife
│   └── index.js
└── index.js

ES5 support

You can use --target es5 or "target": "es5" in tsconfig.json to compile the code down to es5, it's processed by buble. Some features are NOT supported by this target, namely: for .. of.

Compile-time environment variables

You can use --env flag to define compile-time environment variables:

tsup src/index.ts --env.NODE_ENV production

Building CLI app

When an entry file like src/cli.ts contains hashbang like #!/bin/env node tsup will automatically make the outout file executable, so you don't have to run chmod +x dist/cli.js.

Watch mode

tsup src/index.ts --watch

Minify output

You can also minify the output, resulting into lower bundle sizes by using the --minify flag.

tsup src/index.ts --minify

What about type checking?

esbuild is fast because it doesn't perform any type checking, you already get type checking from your IDE like VS Code or WebStorm.

Additionally, if you want type checking at build time, you can enable --dts, which will run a real TypeScript compiler to generate declaration file so you get type checking as well.

CSS support

esbuild has experimental CSS support, and tsup allows you to use PostCSS plugins on top of native CSS support.

To use PostCSS, you need to install PostCSS:

yarn add postcss --dev

..and populate a postcss.config.js in your project

module.exports = {
  plugins: [require('tailwindcss')(), require('autoprefixer')()],
}

---

For more details:

tsup --help

License

MIT © EGOIST (Kevin Titor)