Files

T

fargo 1a822493ba format: apply repo prettier (3.8.1) to the folded skills tree

963 markdown files reformatted with the repository's pinned prettier so
pnpm format:check covers the folded tree like every other repo file.

The formatter's embedded-language pass also normalized code fences
(TS semicolons, closed HTML tags in examples, lowercased CSS hex colors,
one renumbered list that skipped an index). Alphanumeric token deltas vs
the fold commit were audited file-by-file; all are formatter-equivalent
markup normalizations plus the four sanitized skills.

2026-08-19 14:37:17 -05:00

3.7 KiB

Raw Blame History

Output Format

Configure the module format(s) for generated bundles.

Overview

tsdown can generate bundles in multiple formats. Default is ESM.

Available Formats

Format	Description	Use Case
`esm`	ECMAScript Module (default)	Modern Node.js, browsers, Deno
`cjs`	CommonJS	Legacy Node.js, require()
`iife`	Immediately Invoked Function Expression	Browser `<script>` tags
`umd`	Universal Module Definition	AMD, CommonJS, and globals

Usage

CLI

# Single format
tsdown --format esm

# Multiple formats
tsdown --format esm --format cjs

# Or comma-separated
tsdown --format esm,cjs

Config File

Single Format

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

Multiple Formats

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

Per-Format Configuration

Override options for specific formats:

export default defineConfig({
  entry: ['src/index.ts'],
  format: {
    esm: {
      target: ['es2015'],
    },
    cjs: {
      target: ['node20'],
    },
  },
});

This allows different targets, platforms, or other settings per format.

Common Patterns

Modern Library (ESM + CJS)

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

Output:

dist/index.mjs (ESM)
dist/index.cjs (CJS)
dist/index.d.ts (Types)

Browser Library (IIFE)

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['iife'],
  globalName: 'MyLib',
  platform: 'browser',
  minify: true,
});

Output: dist/index.global.js (IIFE with global MyLib)

Universal Library (UMD)

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['umd'],
  globalName: 'MyLib',
  platform: 'neutral',
});

Works with AMD, CommonJS, and browser globals.

Node.js Package (CJS + ESM)

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  platform: 'node',
  dts: true,
  shims: true, // Add __dirname, __filename for CJS compat
});

Framework Component Library

export default defineConfig({
  entry: ['src/index.tsx'],
  format: ['esm', 'cjs'],
  external: ['react', 'react-dom'], // Don't bundle dependencies
  dts: true,
});

Format-Specific Outputs

File Extensions

Format	Extension
ESM	`.mjs` or `.js` (with `"type": "module"`)
CJS	`.cjs` or `.js` (without `"type": "module"`)
IIFE	`.global.js`
UMD	`.umd.js`

Customize Extensions

Use outExtensions to override:

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  outExtensions: ({ format }) => ({
    js: format === 'esm' ? '.js' : '.cjs',
  }),
});

Tips

Use ESM + CJS for maximum compatibility
Use IIFE for browser-only libraries
Use UMD for universal compatibility (less common now)
Externalize dependencies to avoid bundling framework code
Add shims for CJS compatibility when using Node.js APIs
Set globalName for IIFE/UMD formats

Target - Set JavaScript version
Platform - Set platform (node, browser, neutral)
Shims - Add ESM/CJS compatibility
Output Directory - Customize output paths

3.7 KiB Raw Blame History