Frequently Asked Questions

Why tsdown Does Not Support Stub Mode

tsdown does not support stub mode due to several limitations and design considerations:

• Stub mode requires manual intervention: Whenever you change named exports, you must re-run the stub command to update the stubs. This disrupts the development workflow and can lead to inconsistencies.
• Stub mode is incompatible with plugins: Stub mode cannot support plugin functionality, which is essential for many advanced use cases and custom build logic.

Recommended Alternatives

Instead of stub mode, we recommend more reliable and flexible approaches:

1. Use Watch Mode: The simplest solution is to run tsdown in watch mode. This keeps your build up-to-date automatically as you make changes, though it requires you to keep the process running in the background.

2. Use exports.devExports for Dev/Prod Separation: For a more advanced and robust setup, use the exports.devExports option to specify different export paths for development and production. This allows you to point to source files during development and built files for production.

   • If you use plugins: Consider using vite-node to run your code directly with plugin support.
   • If you do not use plugins: You can use lightweight TypeScript runners such as tsx, jiti, or unrun.
   • If you do not use plugins and your code is compatible with Node.js's built-in TypeScript support: With Node.js v22.18.0 and above, you can run TypeScript files directly without any additional runners.

These alternatives provide a smoother and more reliable development experience compared to stub mode, especially as your project grows or requires plugin support. For a more detailed explanation of this decision, please see this GitHub comment.

How does tsdown differ from tsup?

tsdown is the spiritual successor to tsup, powered by Rolldown instead of esbuild. Key differences:

• Faster builds: Rolldown provides significantly better performance, especially for large projects.
• Richer plugin ecosystem: tsdown supports Rolldown, Rollup, and unplugin plugins.
• More features: CSS support, executable bundling, workspace mode, and package validation are built in.

For a detailed comparison and migration guide, see Migrate from tsup.

Can I use tsdown in a monorepo?

Yes. tsdown has built-in workspace support. Use --workspace (or -W) to enable workspace mode, which auto-detects packages in your monorepo. You can filter specific packages with --filter (or -F):

tsdown -W -F my-package

Root-level configuration is automatically inherited by workspace packages.

Why are my dependencies being bundled?

By default, tsdown bundles all imported modules. To exclude dependencies (e.g., those listed in package.json), use the deps configuration:

export default defineConfig({
  deps: {
    skipNodeModulesBundle: true,
  },
})

See Dependencies for more options.

How do I generate type declarations?

Use the dts option:

export default defineConfig({
  dts: true,
})

tsdown auto-enables DTS generation when your package.json includes types or typings fields, or when exports entries contain type conditions. See Declaration Files for advanced options.