moeka-project/.agents/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

--deps.never-bundle <module>

Mark module as external (not bundled):

tsdown --deps.never-bundle react --deps.never-bundle react-dom

--deps.skip-node-modules-bundle

Skip resolving and bundling all node_modules:

tsdown --deps.skip-node-modules-bundle

--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

Executable

--exe

[experimental] Bundle as a standalone executable using Node.js Single Executable Applications. Requires Node.js >= 25.5.0, not supported in Bun or Deno. Cross-platform builds supported via @tsdown/exe.

tsdown --exe

When enabled:

• Default format changes to cjs (unless Node.js >= 25.7.0)
• Declaration file generation (dts) is disabled by default
• Code splitting is disabled
• Only single entry points are supported

See Executable for advanced configuration and cross-platform builds.

Package Management

--exports

Generate the exports field in package.json:

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.*

Workspace / Monorepo

--workspace, -W [dir]

Enable workspace mode for building multiple packages:

tsdown -W
tsdown -W packages/

--filter, -F <pattern>

Filter configs by name or working directory. Supports regex:

tsdown -W -F my-package
tsdown -W -F /^pkg-/

--unbundle

Enable unbundle (bundleless) mode:

tsdown --unbundle

--root <dir>

Specify the root directory of input files (similar to TypeScript's rootDir). Controls the output directory structure by determining how entry file paths map to output paths. Defaults to the common base directory of all entry files.

tsdown --root src
tsdown --root .

--fail-on-warn

Fail on warnings (enabled by default):

tsdown --no-fail-on-warn  # Disable

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

Standalone Executable

tsdown src/cli.ts --exe

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