Tsup TypeScript Bundler

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES Module ...

  cause Attempting to use an ES Module (ESM) output file from tsup in a CommonJS-only context or an older Node.js version that does not fully support ESM.
  fix Ensure your consuming environment fully supports ESM, or configure tsup to output CommonJS by specifying `--format cjs` in your build command or configuration.

• tsup: Missing peer dependency "typescript".

  cause A required peer dependency, such as `typescript` or `@swc/core`, is not installed in your project's dependencies.
  fix Install the missing peer dependency in your project's development dependencies, for example: `npm install typescript -D` or `yarn add typescript --dev`.

• [ERROR] Could not resolve "module-name" from "source-file.ts"

  cause esbuild, the core bundler within tsup, failed to locate or resolve an imported module, often due to an incorrect path, missing dependency, or invalid `tsconfig.json` configuration.
  fix Verify the imported path for typos, ensure the module is correctly installed in `node_modules`, or check your `tsconfig.json` for correct `paths` aliases and `rootDir` configuration.

• Cannot find module 'tsup.config.ts'

  cause Attempting to use a TypeScript configuration file (`tsup.config.ts`) directly without proper setup or with an older tsup version that didn't support it.
  fix Ensure you are using `tsup` version `8.3.0` or newer for `.cts` and `.mts` config file support. For `.ts` files, you might need a `ts-node` setup or transpile the config to JavaScript (`tsup.config.js`).

• SyntaxError: Cannot use import statement outside a module

  cause This error can occur if your tsup configuration file is using ESM syntax (`import`/`export`) but is being interpreted as CommonJS, or vice-versa, without proper module configuration in `package.json`.
  fix Ensure your `tsup.config.js` file uses the appropriate module syntax for its context, or rename it to `tsup.config.mjs` for ESM or `tsup.config.cjs` for CommonJS if explicitly using module styles.

Warnings

• breaking This project is no longer actively maintained. Consider migrating to tsdown for continued support and updates.
  Fix: Migrate your bundling configuration to use tsdown. Refer to the official migration guide: https://tsdown.dev/guide/migrate-from-tsup.
• gotcha Tsup requires Node.js version 18 or higher to run correctly.
  Fix: Upgrade your Node.js environment to version 18 or newer. You can use a tool like nvm or fnm to manage Node.js versions.
• gotcha A TypeScript version of 4.5.0 or higher is required as a peer dependency for tsup to function correctly.
  Fix: Ensure you have `typescript` version `^4.5.0` or higher installed in your project's dev dependencies (e.g., `npm i typescript -D`).
• gotcha CSS support in tsup is experimental and may not be stable or fully featured. It might introduce unexpected behavior or breaking changes.
  Fix: Carefully test CSS bundling in your specific project setup. Consider externalizing CSS or using dedicated CSS tooling if stability is critical.
• gotcha The underlying esbuild dependency is updated frequently within tsup, which may lead to subtle changes in bundling behavior or require updates to esbuild-specific configuration options across minor tsup versions.
  Fix: Always review tsup's release notes when upgrading for potential changes related to esbuild's behavior or specific configuration requirements.

Install

• npm install tsup npm
• yarn add tsup yarn
• pnpm add tsup pnpm

Quickstart

Demonstrates bundling a single TypeScript file (src/index.ts) into CommonJS and ES Module formats, generating TypeScript declaration files. Assumes `tsup` is installed as a dev dependency in your project.

npx tsup src/index.ts --format esm,cjs --dts