tsup

https://tsup.egoist.dev
Admin
tsup is a zero-config TypeScript bundler powered by esbuild that bundles TypeScript and JavaScript...
Tokens:5,248
Snippets:86
Trust Score:7.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install PostCSS

Source: https://tsup.egoist.dev/

Install PostCSS as a development dependency to enable PostCSS plugin support.

```bash
npm i postcss -D
# Or Yarn
yarn add postcss --dev
```

--------------------------------

### Install API Extractor for Experimental DTS

Source: https://tsup.egoist.dev/

To use the experimental --experimental-dts flag, install @microsoft/api-extractor as a peer dependency.

```bash
npm i @microsoft/api-extractor -D
```

```bash
yarn add @microsoft/api-extractor --dev
```

--------------------------------

### Install Tsup Locally

Source: https://tsup.egoist.dev/

Install Tsup as a development dependency in your project using npm, Yarn, or pnpm.

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

--------------------------------

### Configure PostCSS Plugins

Source: https://tsup.egoist.dev/

Configure PostCSS plugins in `postcss.config.js`. This example includes Tailwind CSS and Autoprefixer.

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

--------------------------------

### Multiple Entrypoints with CLI Flags

Source: https://tsup.egoist.dev/

Specify multiple entry points for Tsup using the `--entry` flag. This example outputs `dist/a.js` and `dist/b.js`.

```bash
tsup --entry src/a.ts --entry src/b.ts
```

--------------------------------

### Named Multiple Entrypoints with CLI Flags

Source: https://tsup.egoist.dev/

Specify multiple entry points with custom output filenames using the `--entry.<name>` flag. This example outputs `dist/foo.js` and `dist/bar.js`.

```bash
tsup --entry.foo src/a.ts --entry.bar src/b.ts
```

--------------------------------

### Tsup Configuration with defineConfig (TypeScript)

Source: https://tsup.egoist.dev/

Configure Tsup using `defineConfig` in a `tsup.config.ts` file for type-safe configuration. This example sets entry points, disables splitting, enables sourcemaps, and enables cleaning.

```typescript
import { defineConfig } from 'tsup'

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

--------------------------------

### Define onSuccess Function in tsup.config.ts

Source: https://tsup.egoist.dev/

Configure the onSuccess callback as an async function in tsup.config.ts to perform tasks like starting a server after a successful build.

```typescript
import { defineConfig } from 'tsup'

export default defineConfig({
  async onSuccess() {
    // Start some long running task
    // Like a server
  },
})
```

--------------------------------

### Generate Declaration File

Source: https://tsup.egoist.dev/

Use the --dts flag to generate a declaration file. For multiple entry files, each will get a corresponding .d.ts file. Use --dts <entry> to specify a single entry.

```bash
tsup index.ts --dts
```

```bash
tsup --dts src/index.ts
```

--------------------------------

### Custom SWC Configuration for Decorators

Source: https://tsup.egoist.dev/

Configure SWC options in `tsup.config.ts` when using legacy TypeScript decorators. This example sets `useDefineForClassFields`.

```typescript
import { defineConfig } from 'tsup'

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

--------------------------------

### Return Cleanup Function from onSuccess in tsup.config.ts

Source: https://tsup.egoist.dev/

The onSuccess function can return a cleanup function to stop processes like servers started during the build.

```typescript
import { defineConfig } from 'tsup'

export default defineConfig({
  onSuccess() {
    const server = http.createServer((req, res) => {
      res.end('Hello World!')
    })
    server.listen(3000)
    return () => {
      server.close()
    }
  },
})
```

--------------------------------

### Use Terser for Minification with tsup

Source: https://tsup.egoist.dev/

Specify 'terser' as the argument for the --minify flag to use Terser for minification instead of esbuild's built-in minifier. Ensure terser is installed.

```bash
tsup src/index.ts --minify terser
```

--------------------------------

### Conditional Tsup Configuration

Source: https://tsup.egoist.dev/

Export a function from your Tsup configuration file to conditionally set options based on CLI flags. This example enables minification only when not in watch mode.

```typescript
import { defineConfig } from 'tsup'

export default defineConfig((options) => {
  return {
    minify: !options.watch,
  }
})
```

--------------------------------

### Tsup Help Command

Source: https://tsup.egoist.dev/

View all available tsup command-line options and their descriptions.

```bash
tsup --help
```

--------------------------------

### Basic File Bundling

Source: https://tsup.egoist.dev/

Bundle TypeScript files into the default './dist' directory. Multiple files can be bundled in one command.

```bash
tsup [...files]
```

```bash
tsup src/index.ts src/cli.ts
```

--------------------------------

### Legacy Output for Bundled Formats

Source: https://tsup.egoist.dev/

Use the --legacy-output flag to avoid extensions like .mjs or .cjs, useful for environments that do not support them.

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

--------------------------------

### Multiple Entrypoints Configuration (TypeScript)

Source: https://tsup.egoist.dev/

Configure multiple entry points in `tsup.config.ts`. The `entry` option can be an array for default naming or an object for custom names.

```typescript
export default defineConfig({
  // Outputs `dist/a.js` and `dist/b.js`.
  entry: ['src/a.ts', 'src/b.ts'],
  // Outputs `dist/foo.js` and `dist/bar.js`
  entry: {
    foo: 'src/a.ts',
    bar: 'src/b.ts',
  },
})
```

--------------------------------

### Generate Sourcemap File

Source: https://tsup.egoist.dev/

Use the --sourcemap flag to generate a sourcemap file. For inline sourcemaps, use --sourcemap inline. Inline sourcemaps are not recommended for production.

```bash
tsup index.ts --sourcemap
```

```bash
tsup index.ts --sourcemap inline
```

--------------------------------

### Custom Output Extension

Source: https://tsup.egoist.dev/

Configure custom output file extensions using the outExtension option in the defineConfig function. The signature includes context like options, format, and package.json type.

```javascript
export default defineConfig({
  outExtension({ format }) {
    return {
      js: `.${format}.js`,
    }
  },
})
```

--------------------------------

### Enable SWC to Discover .swcrc

Source: https://tsup.egoist.dev/

Set `swc.swcrc` to `true` in `tsup.config.ts` to allow SWC to automatically discover and use a custom `.swcrc` configuration file.

```typescript
import { defineConfig } from 'tsup'

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

--------------------------------

### Tsup Configuration in package.json

Source: https://tsup.egoist.dev/

Configure Tsup by adding a `tsup` property to your `package.json` file. This includes entry points, splitting, sourcemaps, and cleaning options, along with a build script.

```json
{
  "tsup": {
    "entry": ["src/index.ts"],
    "splitting": false,
    "sourcemap": true,
    "clean": true
  },
  "scripts": {
    "build": "tsup"
  }
}
```

--------------------------------

### Minify Output with tsup

Source: https://tsup.egoist.dev/

Enable code minification to reduce bundle sizes by using the --minify flag.

```bash
tsup src/index.ts --minify
```

--------------------------------

### Custom esbuild Plugin and Options

Source: https://tsup.egoist.dev/

Configure custom esbuild plugins and options in `tsup.config.ts`. The `esbuildOptions` function receives context including the build format.

```typescript
import { defineConfig } from 'tsup'

export default defineConfig({
  esbuildPlugins: [YourPlugin],
  esbuildOptions(options, context) {
    options.define.foo = '"bar"'
  },
})
```

--------------------------------

### Execute Command on Successful Build with tsup

Source: https://tsup.egoist.dev/

Use the --onSuccess flag to run a command after a successful build, which is particularly useful in watch mode. This can also be a function in tsup.config.ts.

```bash
tsup src/index.ts --watch --onSuccess "node dist/index.js"
```

--------------------------------

### Bundle in Multiple Formats

Source: https://tsup.egoist.dev/

Bundle in multiple formats (esm, cjs, iife) by separating them with commas. The output structure varies based on the 'type' field in package.json.

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

--------------------------------

### Enable Watch Mode in tsup

Source: https://tsup.egoist.dev/

Turn on watch mode with the --watch flag to continuously monitor files for changes after the initial build. It ignores dist, node_modules, and .git by default.

```bash
tsup src/index.ts --watch
```

--------------------------------

### ES5 Support in tsup

Source: https://tsup.egoist.dev/

Compile code down to ES5 using --target es5. This involves a two-step transpilation: esbuild to es2020, then SWC to es5.

```bash
tsup --target es5
```

--------------------------------

### VS Code JSON Schema Configuration for Tsup

Source: https://tsup.egoist.dev/

Configure VS Code's `settings.json` to enable Intellisense for Tsup configurations in `package.json` and `tsup.config.json` files.

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

--------------------------------

### Specify Custom tsconfig.json

Source: https://tsup.egoist.dev/

Use the `--tsconfig` flag to specify a custom tsconfig.json file for the build. If not found, tsup defaults to `tsconfig.json`.

```bash
tsup --tsconfig tsconfig.prod.json
```

--------------------------------

### Code Splitting Configuration

Source: https://tsup.egoist.dev/

Code splitting is enabled by default for 'esm' output. Use --splitting for experimental CJS code splitting or --no-splitting to disable it.

```bash
tsup src/index.ts --splitting
```

```bash
tsup src/index.ts --no-splitting
```

--------------------------------

### Configure Watch Mode with Ignored Folders in tsup

Source: https://tsup.egoist.dev/

Specify additional folders to ignore during watch mode by repeating the --ignore-watch flag.

```bash
tsup src/index.ts --watch --ignore-watch ignore-this-folder-too
```

--------------------------------

### Watch Mode Configuration in tsup.config.ts

Source: https://tsup.egoist.dev/

Enable watch mode by setting the watch option to true in tsup.config.ts.

```typescript
import { defineConfig } from 'tsup'

export default defineConfig({
  watch: true,
})
```

--------------------------------

### Tsup JavaScript API Build Configuration

Source: https://tsup.egoist.dev/

Use the `build` function from the tsup JavaScript API to configure your build process programmatically. Supports options like `sourcemap` and `dts`.

```typescript
import { build } from 'tsup'

await build({
  entry: ['src/index.ts'],
  sourcemap: true,
  dts: true,
})
```

--------------------------------

### ES5 Target Configuration in tsup.config.ts

Source: https://tsup.egoist.dev/

Configure the build to target ES5 by setting the target option to 'es5' in tsup.config.ts. This utilizes SWC for transpilation after esbuild.

```typescript
import { defineConfig } from 'tsup'

export default defineConfig({
  target: 'es5',
})
```

--------------------------------

### Configure Tree Shaking in tsup.config.ts

Source: https://tsup.egoist.dev/

Enable tree shaking by setting the treeshake option to true in tsup.config.ts.

```typescript
import { defineConfig } from 'tsup'

export default defineConfig({
  treeshake: true,
})
```

--------------------------------

### Enable Rollup for Tree Shaking with tsup

Source: https://tsup.egoist.dev/

Use the --treeshake flag to enable Rollup for tree shaking, which can sometimes be more effective than esbuild's default tree shaking.

```bash
tsup src/index.ts --treeshake
```

--------------------------------

### Configure Custom Loaders via CLI in tsup

Source: https://tsup.egoist.dev/

Use the --loader flag on the CLI to specify custom loaders for file types, mapping extensions to loader types like 'base64' or 'file'.

```bash
tsup --loader ".jpg=base64" --loader ".webp=file"
```

--------------------------------

### DTS Generation Configuration in tsup.config.ts

Source: https://tsup.egoist.dev/

Enable declaration file generation by setting the dts option to true in tsup.config.ts.

```typescript
import { defineConfig } from 'tsup'

export default defineConfig({
  dts: true,
})
```

--------------------------------

### Inject CJS and ESM Shims

Source: https://tsup.egoist.dev/

Enable shims to ensure compatibility for `__dirname` (CJS) and `import.meta.url` (ESM) when building different module formats.

```typescript
import { defineConfig } from 'tsup'

export default defineConfig({
  shims: true,
})
```

--------------------------------

### Define Compile-Time Environment Variables with tsup

Source: https://tsup.egoist.dev/

Use the --env flag to define environment variables during compilation. This recognizes process.env.VAR_NAME and import.meta.env.VAR_NAME.

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

--------------------------------

### Minify Configuration in tsup.config.ts

Source: https://tsup.egoist.dev/

Enable minification by setting the minify option to true in tsup.config.ts. You can also specify terserOptions for Terser.

```typescript
import { defineConfig } from 'tsup'

export default defineConfig({
  minify: true,
  terserOptions: {
    compress: {
      // Terser options
    },
  },
})
```

--------------------------------

### Configure Custom Loaders in tsup.config.ts

Source: https://tsup.egoist.dev/

Define custom file loaders within the loader object in tsup.config.ts for a more declarative configuration.

```typescript
import { defineConfig } from 'tsup'

export default defineConfig({
  loader: {
    '.jpg': 'base64',
    '.webp': 'file',
  },
})
```

--------------------------------

### Troubleshooting Decorator Imports

Source: https://tsup.egoist.dev/

When `emitDecoratorMetadata` is enabled, exported types may be eliminated by SWC. Fix this by using `import type` or `import { type ... }`.

```typescript
import { type SomeType } from 'module'
// or
import type { SomeType } from 'module'
```

--------------------------------

### Enable DTS Generation and Type Checking with tsup

Source: https://tsup.egoist.dev/

Use the --dts flag to enable the generation of declaration files (.d.ts), which also runs a TypeScript compiler for type checking at build time.

```bash
tsup --dts
```

--------------------------------

### Exclude Packages with tsup-node

Source: https://tsup.egoist.dev/

Use `tsup-node` to skip bundling Node.js packages, which is often necessary for Node.js applications or APIs, especially when outputting to ESM. Packages in `dependencies` and `peerDependencies` are excluded by default.

```bash
tsup-node src/index.ts
```

--------------------------------

### Enable CommonJS Interoperability with tsup

Source: https://tsup.egoist.dev/

Use the --cjsInterop flag to change how default exports are transformed in CommonJS modules. If only default exports exist, it transforms to module.exports = x.

```bash
tsup src/index.ts --cjsInterop
```

--------------------------------

### CommonJS Interop Configuration in tsup.config.ts

Source: https://tsup.egoist.dev/

Configure CommonJS interop behavior directly in tsup.config.ts using the cjsInterop option.

```typescript
import { defineConfig } from 'tsup'

export default defineConfig({
  cjsInterop: true,
})
```

--------------------------------

### Target Environment Configuration in tsup.config.ts

Source: https://tsup.egoist.dev/

Set the target environment for generated code using the target option in tsup.config.ts. This can be a specific environment name and version or a JavaScript language version.

```typescript
import { defineConfig } from 'tsup'

export default defineConfig({
  target: 'node14',
})
```

--------------------------------

### Ignore Watch Folders Configuration in tsup.config.ts

Source: https://tsup.egoist.dev/

Specify folders to ignore during watch mode using the ignoreWatch option in tsup.config.ts.

```typescript
import { defineConfig } from 'tsup'

export default defineConfig({
  watch: true,
  ignoreWatch: ['dist', 'node_modules', '.git', '**/my-ignored-folder/**'],
})
```

--------------------------------

### Emit Declaration File Only

Source: https://tsup.egoist.dev/

The --dts-only flag emits only the declaration file, similar to tsc's emitDeclarationOnly option.

```bash
tsup index.ts --dts-only
```
Tokens:
Raw