Interface: UserConfig

Defined in: src/config/types.ts:149

Options for tsdown.

Extended by

• InlineConfig

Properties

alias?

optional alias?: Record<string, string>;

Defined in: src/config/types.ts:171

---

attw?

optional attw?: WithEnabled<AttwOptions>;

Defined in: src/config/types.ts:560

Run arethetypeswrong after bundling. Requires @arethetypeswrong/core to be installed.

Default

false

See

https://github.com/arethetypeswrong/arethetypeswrong.github.io

---

banner?

optional banner?: ChunkAddon;

Defined in: src/config/types.ts:388

---

checks?

optional checks?: ChecksOptions & object;

Defined in: src/config/types.ts:318

Controls which warnings are emitted during the build process. Each option can be set to true (emit warning) or false (suppress warning).

Type Declaration

legacyCjs?

optional legacyCjs?: boolean;

If the config includes the cjs format and one of its target >= node 20.19.0 / 22.12.0, warn the user about the deprecation of CommonJS.

Default

true

---

cjsDefault?

optional cjsDefault?: boolean;

Defined in: src/config/types.ts:438

Converts a single default export from an explicit CJS entry module to module.exports. It does not apply to non-entry chunks emitted in unbundle mode.

Default

true

---

clean?

optional clean?: boolean | string[];

Defined in: src/config/types.ts:382

Clean directories before build.

Default to output directory.

Default

true

---

copy?

optional copy?:
  | CopyOptions
  | CopyOptionsFn;

Defined in: src/config/types.ts:604

Copy files to another directory.

Example

;[
  'src/assets',
  'src/env.d.ts',
  'src/styles/**/*.css',
  { from: 'src/assets', to: 'dist/assets' },
  { from: 'src/styles/**/*.css', to: 'dist', flatten: true },
]

---

css?

optional css?: CssOptions;

Defined in: src/config/types.ts:589

[experimental] CSS options. Requires @tsdown/css to be installed.

---

customLogger?

optional customLogger?: Logger;

Defined in: src/config/types.ts:491

Custom logger.

---

cwd?

optional cwd?: string;

Defined in: src/config/types.ts:461

The working directory of the config file.

• Defaults to process.cwd | process.cwd() for root config.
• Defaults to the package directory for workspace config.

Default

process.cwd()

---

define?

optional define?: Record<string, string>;

Defined in: src/config/types.ts:246

---

deps?

optional deps?: DepsConfig;

Defined in: src/config/types.ts:169

Dependency handling options.

---

devtools?

optional devtools?: WithEnabled<DevtoolsOptions>;

Defined in: src/config/types.ts:520

[experimental] Enable devtools.

DevTools is still under development, and this is for early testers only.

This may slow down the build process significantly.

Default

false

---

dts?

optional dts?: WithEnabled<DtsOptions>;

Defined in: src/config/types.ts:537

Enables generation of TypeScript declaration files (.d.ts).

By default, this option is auto-detected based on your project's package.json:

• If exe is enabled, declaration file generation is disabled by default.
• If the types field is present, or if the main exports contains a types entry, declaration file generation is enabled by default.
• Otherwise, declaration file generation is disabled by default.

---

entry?

optional entry?: TsdownInputOption;

Defined in: src/config/types.ts:164

Defaults to 'src/index.ts' if it exists.

Supports glob patterns with negation to exclude files:

Example

entry: {
  "hooks/*": ["./src/hooks/*.ts", "!./src/hooks/index.ts"],
}

Default

{
  index: 'src/index.ts'
}

---

env?

optional env?: Record<string, any>;

Defined in: src/config/types.ts:234

Compile-time env variables, which can be accessed via import.meta.env or process.env.

Example

{
  "DEBUG": true,
  "NODE_ENV": "production"
}

Default

{
}

---

envFile?

optional envFile?: string;

Defined in: src/config/types.ts:240

Path to env file providing compile-time env variables.

Example

`.env`, `.env.production`, etc.

---

envPrefix?

optional envPrefix?: string | string[];

Defined in: src/config/types.ts:245

When loading env variables from envFile, only include variables with these prefixes.

Default

'TSDOWN_'

---

exe?

optional exe?: WithEnabled<ExeOptions>;

Defined in: src/config/types.ts:617

[experimental] Bundle as executable using Node.js SEA (Single Executable Applications).

This will bundle the output into a single executable file using Node.js SEA. Note that this is only supported on Node.js 25.7.0 and later, and is not supported in Bun or Deno.

Default

false

---

exports?

optional exports?: WithEnabled<ExportsOptions>;

Defined in: src/config/types.ts:583

Generate package exports for package.json.

This will set the exports field in package.json to point to the generated files.

Default

false

---

external?

optional external?: string | RegExp | (string | RegExp)[] | ExternalOptionFunction;

Defined in: src/config/types.ts:632

Deprecated

Use deps.neverBundle instead.

---

failOnWarn?

optional failOnWarn?: boolean | CIOption;

Defined in: src/config/types.ts:479

If true, fails the build on warnings.

Default

false

---

fixedExtension?

optional fixedExtension?: boolean;

Defined in: src/config/types.ts:417

Use a fixed extension for output files. The extension will always be .cjs or .mjs. Otherwise, it will depend on the package type.

Defaults to true if platform is set to node, false otherwise.

Default

platform === 'node'

---

footer?

optional footer?: ChunkAddon;

Defined in: src/config/types.ts:387

---

format?

optional format?:
  | "es" | "cjs" | "iife" | "umd" | "commonjs" | "module" | "esm"
  | ("es" | "cjs" | "iife" | "umd" | "commonjs" | "module" | "esm")[]
| Partial<Record<"es" | "cjs" | "iife" | "umd" | "commonjs" | "module" | "esm", Partial<ResolvedConfig>>>;

Defined in: src/config/types.ts:354

Output format(s). Available formats are

• esm: ESM
• cjs: CommonJS
• iife: IIFE
• umd: UMD

Default

'esm'

---

fromVite?

optional fromVite?: boolean | "vitest";

Defined in: src/config/types.ts:500

Reuse config from Vite or Vitest (experimental)

Default

false

---

globalName?

optional globalName?: string;

Defined in: src/config/types.ts:355

---

globImport?

optional globImport?: boolean;

Defined in: src/config/types.ts:573

import.meta.glob support.

See

https://vite.dev/guide/features.html#glob-import

Default

true

---

hash?

optional hash?: boolean;

Defined in: src/config/types.ts:429

If enabled, appends hash to chunk filenames.

Default

true

---

hooks?

optional hooks?:
  | Partial<TsdownHooks>
  | ((hooks) => Awaitable<void>);

Defined in: src/config/types.ts:606

---

ignoreWatch?

optional ignoreWatch?: Arrayable<string | RegExp>;

Defined in: src/config/types.ts:509

Files or patterns to not watch while in watch mode.

---

inputOptions?

optional inputOptions?:
  | InputOptions
  | ((options, format, context) => Awaitable<void | InputOptions | null>);

Defined in: src/config/types.ts:334

Use with caution; ensure you understand the implications.

---

loader?

optional loader?: ModuleTypes;

Defined in: src/config/types.ts:269

Sets how input files are processed. For example, use 'js' to treat files as JavaScript or 'base64' for images. Lets you import or require files like images or fonts.

Example

{ ".jpg": "asset", ".png": "base64" }

---

logLevel?

optional logLevel?: LogLevel;

Defined in: src/config/types.ts:474

Log level.

Default

'info'

---

minify?

optional minify?: boolean | "dce-only" | MinifyOptions;

Defined in: src/config/types.ts:386

Default

false

---

name?

optional name?: string;

Defined in: src/config/types.ts:468

The name to show in CLI output. This is useful for monorepos or workspaces. When using workspace mode, this option defaults to the package name from package.json. In non-workspace mode, this option must be set explicitly for the name to show in the CLI output.

---

nodeProtocol?

optional nodeProtocol?: boolean | "strip";

Defined in: src/config/types.ts:313

Control whether built-in Node.js module imports use the node: protocol.

• true: Add the node: prefix to built-in module imports.
• 'strip': Remove the node: prefix from built-in module imports.
• false: Do not transform built-in module imports.

Default

false

Examples

`nodeProtocol: true` — add the `node:` prefix

// Input
import 'fs'

// Output
import 'node:fs'

`nodeProtocol: 'strip'` — remove the `node:` prefix

// Input
import 'node:fs'

// Output
import 'fs'

`nodeProtocol: false` — do not transform imports

// Input
import 'node:fs'

// Output
import 'node:fs'

---

noExternal?

optional noExternal?:
  | Arrayable<string | RegExp>
  | NoExternalFn;

Defined in: src/config/types.ts:636

Deprecated

Use deps.alwaysBundle instead.

---

onSuccess?

optional onSuccess?: string | ((config, signal) => void | Promise<void>);

Defined in: src/config/types.ts:525

You can specify command to be executed after a successful build, specially useful for Watch mode

---

outDir?

optional outDir?: string;

Defined in: src/config/types.ts:359

Default

'dist'

---

outExtensions?

optional outExtensions?: OutExtensionFactory;

Defined in: src/config/types.ts:423

Custom extensions for output files. fixedExtension will be overridden by this option.

---

outputOptions?

optional outputOptions?:
  | OutputOptions
  | ((options, format, context) => Awaitable<void | OutputOptions | null>);

Defined in: src/config/types.ts:443

Use with caution; ensure you understand the implications.

---

platform?

optional platform?: "node" | "neutral" | "browser";

Defined in: src/config/types.ts:189

Specifies the target runtime platform for the build.

• node: Node.js and compatible runtimes (e.g., Deno, Bun). For CJS format, this is always set to node and cannot be changed.
• neutral: A platform-agnostic target with no specific runtime assumptions.
• browser: Web browsers.

Default

'node'

See

https://tsdown.dev/options/platform

---

plugins?

optional plugins?: TsdownPluginOption;

Defined in: src/config/types.ts:329

---

publint?

optional publint?: WithEnabled<PublintOptions>;

Defined in: src/config/types.ts:551

Run publint after bundling. Requires publint to be installed.

Default

false

---

report?

optional report?: WithEnabled<ReportOptions>;

Defined in: src/config/types.ts:566

Enable size reporting after bundling.

Default

true

---

root?

optional root?: string;

Defined in: src/config/types.ts:405

Specifies the root directory of input files, similar to TypeScript's rootDir. This determines the output directory structure.

By default, the root is computed as the common base directory of all entry files.

See

https://www.typescriptlang.org/tsconfig/#rootDir

---

shims?

optional shims?: boolean;

Defined in: src/config/types.ts:251

Default

false

---

sourcemap?

optional sourcemap?: Sourcemap;

Defined in: src/config/types.ts:375

Whether to generate source map files.

Note that this option will always be true if you have `declarationMap` option enabled in your tsconfig.json.

Default

false

---

suppressWarnings?

optional suppressWarnings?: Arrayable<string | RegExp> | ((msg) => boolean);

Defined in: src/config/types.ts:487

Suppress warnings whose message matches the given pattern(s).

Accepts a string (substring match), a RegExp, an array of either, or a predicate function. Matched warnings are dropped before failOnWarn is applied, so they won't fail the build.

---

target?

optional target?: string | false | string[];

Defined in: src/config/types.ts:220

Specifies the compilation target environment(s).

Determines the JavaScript version or runtime(s) for which the code should be compiled. If not set, defaults to the value of engines.node in your project's package.json. If no engines.node field exists, no syntax transformations are applied.

Accepts a single target (e.g., 'es2020', 'node18', 'baseline-widely-available'), an array of targets, or false to disable all transformations.

See

https://tsdown.dev/options/target#supported-targets for a list of valid targets and more details.

Examples

// Target a single environment
{ "target": "node18" }

// Target multiple environments
{ "target": ["node18", "es2020"] }

// Disable all syntax transformations
{ "target": false }

---

treeshake?

optional treeshake?: boolean | TreeshakingOptions;

Defined in: src/config/types.ts:258

Configure tree shaking options.

See

https://rolldown.rs/reference/InputOptions.treeshake for more details.

Default

true

---

tsconfig?

optional tsconfig?: string | boolean;

Defined in: src/config/types.ts:176

Default

true

---

unbundle?

optional unbundle?: boolean;

Defined in: src/config/types.ts:395

Determines whether unbundle is enabled. When set to true, the output files will mirror the input file structure.

Default

false

---

unused?

optional unused?: WithEnabled<UnusedOptions>;

Defined in: src/config/types.ts:544

Enable unused dependencies check with unplugin-unused Requires unplugin-unused to be installed.

Default

false

---

watch?

optional watch?: boolean | Arrayable<string>;

Defined in: src/config/types.ts:505

Default

false

---

workspace?

optional workspace?: true | Arrayable<string> | Workspace;

Defined in: src/config/types.ts:623

[experimental] Enable workspace mode. This allows you to build multiple packages in a monorepo.

---

write?

optional write?: boolean;

Defined in: src/config/types.ts:365

Whether to write the files to disk. This option is incompatible with watch mode.

Default

true