moeka-project/.agents/skills/tsdown/references/option-package-exports.md

Auto-Generate Package Exports

Automatically generate package.json exports from build output.

Overview

tsdown can automatically infer and generate the exports field in your package.json based on your build outputs.

Top-level main, module, and types fields are not generated by default. Enable exports.legacy if you need those fields for older tools.

Review the generated exports before publishing, or enable publint for validation.

Basic Usage

CLI

tsdown --exports

Config File

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  exports: true,
})

What Gets Generated

Single Entry

Config:

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  exports: true,
})

Generated in package.json:

{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    }
  }
}

Multiple Entries

Config:

export default defineConfig({
  entry: {
    index: 'src/index.ts',
    utils: 'src/utils.ts',
  },
  format: ['esm', 'cjs'],
  dts: true,
  exports: true,
})

Generated in package.json:

{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    },
    "./utils": {
      "types": "./dist/utils.d.ts",
      "import": "./dist/utils.mjs",
      "require": "./dist/utils.cjs"
    }
  }
}

Export All Files

Include all output files, not just entry points:

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  exports: {
    all: true,
  },
})

Result: All .mjs, .cjs, and .d.ts files will be added to exports.

Legacy Package Fields

Generate top-level main, module, and types fields for older tools:

export default defineConfig({
  exports: {
    legacy: true,
  },
})

These fields are not generated by default.

Dev-Time Source Linking

Dev Exports

Link to source files during development:

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  exports: {
    devExports: true,
  },
})

Generated:

{
  "exports": {
    ".": "./src/index.ts"  // Points to source
  },
  "publishConfig": {
    "exports": {
      ".": {
        "import": "./dist/index.mjs",
        "require": "./dist/index.cjs"
      }
    }
  }
}

Note: Supported by pnpm/yarn, not npm.

Conditional Dev Exports

Use specific condition for dev exports:

export default defineConfig({
  exports: {
    devExports: '@my-org/source',
  },
})

Generated:

{
  "exports": {
    ".": {
      "@my-org/source": "./src/index.ts",
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    }
  }
}

Use with TypeScript customConditions:

// tsconfig.json
{
  "compilerOptions": {
    "customConditions": ["@my-org/source"]
  }
}

Custom Exports

Add custom export mappings:

export default defineConfig({
  entry: ['src/index.ts'],
  exports: {
    customExports(pkg, context) {
      // Add custom export
      pkg['./foo'] = './dist/foo.js'

      // Add package.json export
      pkg['./package.json'] = './package.json'

      return pkg
    },
  },
})

Common Patterns

Complete Library Setup

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  exports: true,
  clean: true,
})

Multiple Exports with Dev Mode

export default defineConfig({
  entry: {
    index: 'src/index.ts',
    client: 'src/client.ts',
    server: 'src/server.ts',
  },
  format: ['esm', 'cjs'],
  dts: true,
  exports: {
    all: false,  // Only entries
    devExports: '@my-org/source',
  },
})

Monorepo Package

export default defineConfig({
  workspace: 'packages/*',
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  exports: true,  // Generate for each package
})

Validation

Enable Publint

Validate generated exports:

tsdown --exports --publint

Or in config:

export default defineConfig({
  exports: true,
  publint: true,  // Validate exports
})

Tips

1. Review before publishing - Check generated fields
2. Use with publint - Validate exports field
3. Enable for libraries - Especially with multiple exports
4. Use devExports - Better DX during development
5. Test exports - Verify imports work correctly

Troubleshooting

Exports Not Generated

• Ensure exports: true is set
• Check build completed successfully
• Verify output files exist

Wrong Export Paths

• Check outDir configuration
• Verify entry names match expectations
• Review format settings

Dev Exports Not Working

• Only supported by pnpm/yarn
• Check package manager
• Use publishConfig for publishing

Types Not Exported

• Enable dts: true
• Ensure TypeScript is installed
• Check .d.ts files are generated

CLI Examples

# Generate exports
tsdown --exports

# With publint validation
tsdown --exports --publint

# Export all files
tsdown --exports

# With dev exports
tsdown --exports

Related Options

• Entry - Configure entry points
• Output Format - Module formats
• DTS - Type declarations