Tsdown

tsdown is a community skill for bundling TypeScript libraries, covering zero-config builds, declaration file generation, multiple output formats, tree shaking, and optimized package publishing for TypeScript library authors.

What Is This?

Overview

tsdown provides guidance on building and bundling TypeScript libraries for distribution using the tsdown bundler. It covers zero-config builds that compile TypeScript source into production-ready bundles with sensible defaults for common library patterns, declaration file generation that produces accurate type definitions alongside compiled JavaScript for consumer type safety, multiple output formats that generate ESM, CommonJS, and IIFE bundles from single source for broad compatibility, tree shaking that eliminates unused code paths to produce minimal bundle sizes for consumers, and package publishing workflows that configure package.json exports and entry points for correct module resolution. The skill helps TypeScript library authors create well-structured, properly typed distributable packages with minimal configuration overhead and correct module resolution for all consumer environments.

Who Should Use This

This skill serves TypeScript library authors publishing to npm, open-source maintainers building reusable packages, and teams creating internal shared libraries with proper type declarations.

Why Use It?

Problems It Solves

Configuring TypeScript compilation with declaration generation requires complex tsconfig settings. Supporting both ESM and CommonJS consumers simultaneously needs dual-format builds with correct conditional exports configuration in package.json. Tree shaking across module boundaries requires careful code organization and build tool settings. Package.json exports fields and conditional exports are notoriously difficult to configure correctly for all consumer environments including Node.js, bundlers, and TypeScript.

Core Highlights

Zero-config bundler compiles TypeScript with production-ready sensible defaults. Declaration emitter generates accurate and complete type definition files. Format generator produces both ESM and CJS outputs from single source. Export configurator sets up package.json exports for correct module resolution.

How to Use It?

Basic Usage

// package.json
{
  "name": "my-lib",
  "version": "1.0.0",
  "type": "module",
  "exports": {
    ".": {
      "import": {
        "types":
          "./dist/index.d.mts",
        "default":
          "./dist/index.mjs"
      },
      "require": {
        "types":
          "./dist/index.d.cts",
        "default":
          "./dist/index.cjs"
      }
    }
  },
  "scripts": {
    "build":
      "tsdown src/index.ts"
        + " --format esm,cjs"
        + " --dts"
  }
}

Real-World Examples

// tsdown.config.ts
import {
  defineConfig
} from 'tsdown';

export default defineConfig({
  entry: [
    'src/index.ts',
    'src/utils.ts'
  ],
  format: ['esm', 'cjs'],
  dts: true,
  clean: true,
  splitting: true,
  treeshake: true,
  minify: false,
  external: [
    'react',
    'react-dom'
  ],
  outDir: 'dist',
  target: 'es2020'
});

// Build command:
// npx tsdown

Advanced Tips

Use entry splitting to share common code efficiently between multiple entry points without duplication. Mark peer dependencies as external to avoid bundling framework code that consumers already provide. Set the target to match your minimum supported runtime version to avoid unnecessary syntax downleveling.

When to Use It?

Use Cases

Build a utility library with ESM and CJS outputs plus type declarations for npm publishing. Bundle a React component library with external peer dependencies and tree-shakable exports. Create an internal shared package with multiple entry points for modular consumption.

Related Topics

TypeScript, bundling, npm publishing, ESM, CommonJS, declaration files, and package exports.

Important Notes

Requirements

Node.js with tsdown installed as a development dependency for building TypeScript library bundles. TypeScript source files with proper module imports, export declarations, and type annotations for correct bundle generation and accurate declaration output. Package.json configured with exports field pointing to the generated output files for proper consumer module resolution.

Usage Recommendations

Do: include declaration files with every published package to ensure TypeScript consumers get full type safety. Test your package with both ESM and CommonJS import styles before publishing. Use the external option for peer dependencies to avoid bundling shared framework code.

Don't: bundle dependencies that consumers should install separately since this bloats package size and causes version conflicts. Skip testing the built output by only testing source since build transforms can introduce issues. Publish without verifying that exports field paths match actual generated output files.

Limitations

Complex TypeScript type transformations involving conditional types and mapped types may produce declaration files that differ from manually written type definitions. Some advanced TypeScript features like const enums require specific configuration to bundle correctly across formats. Circular dependencies between entry points can produce unexpected output ordering and duplicated code in split-chunk scenarios that require manual resolution.