stack/packages/mosaic/framework/skills/tsdown/references/reference-cli.md

CLI Reference

Complete reference for tsdown command-line interface.

Overview

All CLI flags can also be set in the config file. CLI flags override config file options.

Flag Patterns

CLI flag mapping rules:

• --foo sets foo: true
• --no-foo sets foo: false
• --foo.bar sets foo: { bar: true }
• --format esm --format cjs sets format: ['esm', 'cjs']

CLI flags support both camelCase and kebab-case. For example, --outDir and --out-dir are equivalent.

Basic Commands

Build

# Build with default config
tsdown

# Build specific files
tsdown src/index.ts src/cli.ts

# Build with watch mode
tsdown --watch

Configuration

--config, -c <filename>

Specify custom config file:

tsdown --config build.config.ts
tsdown -c custom-config.js

--no-config

Disable config file loading:

tsdown --no-config src/index.ts

--config-loader <loader>

Choose config loader (auto, native, unrun):

tsdown --config-loader unrun

--tsconfig <file>

Specify TypeScript config file:

tsdown --tsconfig tsconfig.build.json

Entry Points

[...files]

Specify entry files as arguments:

tsdown src/index.ts src/utils.ts

Output Options

--format <format>

Output format (esm, cjs, iife, umd):

tsdown --format esm
tsdown --format esm --format cjs

--out-dir, -d <dir>

Output directory:

tsdown --out-dir lib
tsdown -d dist

--dts

Generate TypeScript declarations:

tsdown --dts

--clean

Clean output directory before build:

tsdown --clean

Build Options

--target <target>

JavaScript target version:

tsdown --target es2020
tsdown --target node18
tsdown --target chrome100
tsdown --no-target  # Disable transformations

--platform <platform>

Target platform (node, browser, neutral):

tsdown --platform node
tsdown --platform browser

--minify

Enable minification:

tsdown --minify
tsdown --no-minify

--sourcemap

Generate source maps:

tsdown --sourcemap
tsdown --sourcemap inline

--treeshake

Enable/disable tree shaking:

tsdown --treeshake
tsdown --no-treeshake

Dependencies

--external <module>

Mark module as external (not bundled):

tsdown --external react --external react-dom

--shims

Add ESM/CJS compatibility shims:

tsdown --shims

Development

--watch, -w [path]

Enable watch mode:

tsdown --watch
tsdown -w
tsdown --watch src  # Watch specific directory

--ignore-watch <path>

Ignore paths in watch mode:

tsdown --watch --ignore-watch test

--on-success <command>

Run command after successful build:

tsdown --watch --on-success "echo Build complete!"

Environment Variables

--env.* <value>

Set compile-time environment variables:

tsdown --env.NODE_ENV=production --env.API_URL=https://api.example.com

Access as import.meta.env.* or process.env.*.

--env-file <file>

Load environment variables from file:

tsdown --env-file .env.production

--env-prefix <prefix>

Filter environment variables by prefix (default: TSDOWN_):

tsdown --env-file .env --env-prefix APP_ --env-prefix TSDOWN_

Assets

--copy <dir>

Copy directory to output:

tsdown --copy public
tsdown --copy assets --copy static

Package Management

--exports

Auto-generate package.json exports field:

tsdown --exports

--publint

Enable package validation:

tsdown --publint

--attw

Enable "Are the types wrong" validation:

tsdown --attw

--unused

Check for unused dependencies:

tsdown --unused

Logging

--log-level <level>

Set logging verbosity (silent, error, warn, info):

tsdown --log-level error
tsdown --log-level warn

--report / --no-report

Enable/disable build report:

tsdown --no-report  # Disable size report
tsdown --report     # Enable (default)

--debug [feat]

Show debug logs:

tsdown --debug
tsdown --debug rolldown  # Debug specific feature

Integration

--from-vite [vitest]

Extend Vite or Vitest config:

tsdown --from-vite         # Use vite.config.*
tsdown --from-vite vitest  # Use vitest.config.*

Common Usage Patterns

Basic Build

tsdown

Library (ESM + CJS + Types)

tsdown --format esm --format cjs --dts --clean

Production Build

tsdown --minify --clean --no-report

Development (Watch)

tsdown --watch --sourcemap

Browser Bundle (IIFE)

tsdown --format iife --platform browser --minify

Node.js CLI Tool

tsdown --format esm --platform node --shims

Monorepo Package

tsdown --clean --dts --exports --publint

With Environment Variables

tsdown --env-file .env.production --env.BUILD_TIME=$(date +%s)

Copy Assets

tsdown --copy public --copy assets --clean

Tips

1. Use config file for complex setups
2. CLI flags override config file options
3. Chain multiple formats for multi-target builds
4. Use --clean to avoid stale files
5. Enable --dts for TypeScript libraries
6. Use --watch during development
7. Add --on-success for post-build tasks
8. Use --exports to auto-generate package.json fields

Related Documentation

• Config File - Configuration file options
• Entry - Entry point configuration
• Output Format - Format options
• Watch Mode - Watch mode details