stack/v1/packages/mosaic/framework/skills/tsdown/references/option-target.md

Target Environment

Configure JavaScript syntax transformations for target environments.

Overview

The target option controls which JavaScript features are downleveled (transformed to older syntax) for compatibility.

Important: Only affects syntax transformations, not runtime polyfills.

Default Behavior

tsdown auto-reads from package.json:

// package.json
{
  "engines": {
    "node": ">=18.0.0"
  }
}

Automatically sets target to node18.0.0.

If no engines.node field exists, behaves as if target: false (no transformations).

Disabling Transformations

Set to false to preserve modern syntax:

export default defineConfig({
  target: false,
});

Result:

• No JavaScript downleveling
• Modern features preserved (optional chaining ?., nullish coalescing ??, etc.)

Use when:

• Targeting modern environments
• Handling transformations elsewhere
• Building libraries for further processing

Setting Target

CLI

# Single target
tsdown --target es2020
tsdown --target node20

# Multiple targets
tsdown --target chrome100 --target node20.18

# Disable
tsdown --no-target

Config File

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

Multiple Targets

export default defineConfig({
  entry: ['src/index.ts'],
  target: ['chrome100', 'safari15', 'node18'],
});

Supported Targets

ECMAScript Versions

• es2015, es2016, es2017, es2018, es2019, es2020, es2021, es2022, es2023, esnext

Browser Versions

• chrome100, safari18, firefox110, edge100, etc.

Node.js Versions

• node16, node18, node20, node20.18, etc.

Examples

Modern Browsers

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

Node.js Library

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

Legacy Support

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

Per-Format Targets

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

Decorators

Legacy Decorators (Stage 2)

Enable in tsconfig.json:

{
  "compilerOptions": {
    "experimentalDecorators": true
  }
}

Stage 3 Decorators

Not currently supported by tsdown/Rolldown/Oxc.

See oxc issue #9170.

Common Patterns

Universal Library

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

Modern-Only Library

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

Browser Component

export default defineConfig({
  entry: ['src/index.tsx'],
  format: ['esm'],
  target: ['chrome100', 'safari15', 'firefox100'],
  platform: 'browser',
});

Tips

1. Let tsdown auto-detect from package.json when possible
2. Use false for modern-only builds
3. Specify multiple targets for broader compatibility
4. Use legacy decorators with experimentalDecorators
5. Test output in target environments

Related Options

• Platform - Runtime environment
• Output Format - Module formats
• Minification - Code optimization