tsup

Powered by esbuild, tsup can bundle any file type supported natively by Node.js, as well as TypeScript files. Supported extensions include:

• .js (JavaScript)
• .json (JSON)
• .mjs (ES Modules)
• .ts (TypeScript)
• .tsx (TypeScript React)
• .css (Experimental support)

Use the --sourcemap flag to emit .map files. You can also inline the sourcemap using --sourcemap inline (recommended for development only). Note that sourcemaps are not supported during --dts builds.

tsup index.ts --sourcemap
# Or inline
tsup index.ts --sourcemap inline

If using VS Code or an editor with a JSON Language Server, you can add the tsup schema to your settings to get completions and validation for tsup.config.json or the tsup property in package.json.

{
  "json.schemas": [
    {
      "url": "https://cdn.jsdelivr.net/npm/tsup/schema.json",
      "fileMatch": ["package.json", "tsup.config.json"]
    }
  ]
}

You can define your build configuration using several file types. tsup supports:

• tsup.config.ts (recommended for type-safety)
• tsup.config.js
• tsup.config.cjs
• tsup.config.json
• A tsup property inside your package.json

In these files, you can export your options as tsup, default, or via module.exports =. You can also use the --config flag to specify a custom filename or --no-config to disable config files.

import { defineConfig } from 'tsup'

export default defineConfig({
  entry: ['src/index.ts'],
  splitting: false,
  sourcemap: true,
  clean: true,
})

Use the --target flag or target option to set the target environment (e.g., node, chrome, safari, es2020).

To compile down to ES5, use --target es5. This uses esbuild to transpile to es2020 first, and then uses SWC to transpile to es5.

tsup src/index.ts --target es5

Use the tsup command to bundle files. By default, output files are written into the ./dist directory.

tsup supports files natively supported by Node.js (.js, .json, .mjs) and TypeScript files (.ts, .tsx). CSS support is currently experimental.

To bundle a single file:

tsup src/index.ts

To bundle multiple files in one command (each will receive its own output file in ./dist):

tsup src/index.ts src/cli.ts

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

Install tsup as a development dependency in your project using your preferred package manager. It is recommended to install it locally rather than globally.

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

To generate declaration files for type checking, use the --dts flag.

• tsup index.ts --dts: Generates ./dist/index.d.ts.
• tsup index.ts --dts <entry>: Generates a declaration file for a specific entry only.
• --dts-only: Emits only the declaration files without JavaScript files.
• --experimental-dts: Uses @microsoft/api-extractor for more reliable generation (requires installing @microsoft/api-extractor as a dev dependency).
• --dts-resolve: (Experimental) Attempts to resolve external types used in the .d.ts file.

You can specify multiple entrypoints via positional arguments or the --entry flag. To assign specific output filenames to entrypoints, use the --entry.<name> syntax.

# Outputs dist/a.js and dist/b.js
tsup --entry src/a.ts --entry src/b.ts

# Outputs dist/foo.js and dist/bar.js
tsup --entry.foo src/a.ts --entry.bar src/b.ts

When building for Node.js, bundling dependencies is often unnecessary and can cause issues (especially with ESM). While tsup automatically excludes dependencies and peerDependencies, you can use the tsup-node executable to automatically skip bundling any Node.js package.

tsup-node src/index.ts

By default, tsup bundles all imported modules except for those listed in dependencies and peerDependencies of your package.json.

To manually mark additional packages or specific package.json dependencies as external, use the --external flag.

tsup src/index.ts --external <module|pkgJson>

Define compile-time environment variables using the --env flag. This works for process.env.VAR_NAME and import.meta.env.VAR_NAME.

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