Interface UserConfig

Options for tsdown.

interface UserConfig {
    alias?: Record<string, string>;
    attw?: WithEnabled<AttwOptions>;
    banner?: ChunkAddon;
    bundle?: boolean;
    checks?: ChecksOptions & { legacyCjs?: boolean };
    cjsDefault?: boolean;
    clean?: boolean | string[];
    copy?: CopyOptions | CopyOptionsFn;
    css?: CssOptions;
    customLogger?: Logger;
    cwd?: string;
    define?: Record<string, string>;
    deps?: DepsConfig;
    devtools?: WithEnabled<DevtoolsOptions>;
    dts?: WithEnabled<DtsOptions>;
    entry?: TsdownInputOption;
    env?: Record<string, any>;
    envFile?: string;
    envPrefix?: string | string[];
    exe?: WithEnabled<ExeOptions>;
    exports?: WithEnabled<ExportsOptions>;
    external?: string | RegExp | (string | RegExp)[] | ExternalOptionFunction;
    failOnWarn?: boolean | CIOption;
    fixedExtension?: boolean;
    footer?: ChunkAddon;
    format?:
        | "module"
        | "es"
        | "cjs"
        | "esm"
        | "commonjs"
        | "iife"
        | "umd"
        | ("module" | "es" | "cjs" | "esm" | "commonjs" | "iife" | "umd")[]
        | Partial<
            Record<
                "module"
                | "es"
                | "cjs"
                | "esm"
                | "commonjs"
                | "iife"
                | "umd",
                Partial<ResolvedConfig>,
            >,
        >;
    fromVite?: boolean | "vitest";
    globalName?: string;
    globImport?: boolean;
    hash?: boolean;
    hooks?:
        | Partial<TsdownHooks>
        | ((hooks: Hookable<TsdownHooks>) => Awaitable<void>);
    ignoreWatch?: Arrayable<string | RegExp>;
    injectStyle?: boolean;
    inlineOnly?: false | Arrayable<string | RegExp>;
    inputOptions?:
        | InputOptions
        | (
            (
                options: InputOptions,
                format: InternalModuleFormat,
                context: { cjsDts: boolean },
            ) => Awaitable<void | InputOptions | null>
        );
    loader?: ModuleTypes;
    logLevel?: LogLevel;
    minify?: boolean | "dce-only" | MinifyOptions;
    name?: string;
    nodeProtocol?: boolean | "strip";
    noExternal?: Arrayable<string | RegExp> | NoExternalFn;
    onSuccess?:
        | string
        | ((config: ResolvedConfig, signal: AbortSignal) => void | Promise<void>);
    outDir?: string;
    outExtension?: OutExtensionFactory;
    outExtensions?: OutExtensionFactory;
    outputOptions?:
        | OutputOptions
        | (
            (
                options: OutputOptions,
                format: InternalModuleFormat,
                context: { cjsDts: boolean },
            ) => Awaitable<void | OutputOptions | null>
        );
    platform?: "neutral" | "node" | "browser";
    plugins?: TsdownPluginOption;
    publicDir?: CopyOptions | CopyOptionsFn;
    publint?: WithEnabled<PublintOptions>;
    removeNodeProtocol?: boolean;
    report?: WithEnabled<ReportOptions>;
    root?: string;
    shims?: boolean;
    skipNodeModulesBundle?: boolean;
    sourcemap?: Sourcemap;
    suppressWarnings?: Arrayable<string | RegExp> | ((msg: string) => boolean);
    target?: string | false | string[];
    treeshake?: boolean | TreeshakingOptions;
    tsconfig?: string | boolean;
    unbundle?: boolean;
    unused?: WithEnabled<Options>;
    watch?: boolean | Arrayable<string>;
    workspace?: true | Arrayable<string> | Workspace;
    write?: boolean;
}

Hierarchy (View Summary)

UserConfig
- InlineConfig

Properties

`Optional`alias

alias?: Record<string, string>

`Optional`attw

attw?: WithEnabled<AttwOptions>

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

Default

false

See

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

`Optional`banner

banner?: ChunkAddon

`Optional`bundle

bundle?: boolean

Deprecated

Use unbundle instead.

Default

true

`Optional`checks

checks?: ChecksOptions & { legacyCjs?: boolean }

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

Type Declaration

OptionallegacyCjs?: 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
```

`Optional`cjsDefault

cjsDefault?: boolean

Default

true

`Optional`clean

clean?: boolean | string[]

Clean directories before build.

Default to output directory.

Default

true

`Optional`copy

copy?: CopyOptions | CopyOptionsFn

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 },
]

`Optional`css

css?: CssOptions

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

`Optional`customLogger

customLogger?: Logger

Custom logger.

`Optional`cwd

cwd?: string

The working directory of the config file.

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

Default

process.cwd()

`Optional`define

define?: Record<string, string>

`Optional`deps

deps?: DepsConfig

Dependency handling options.

`Optional`devtools

devtools?: WithEnabled<DevtoolsOptions>

[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

`Optional`dts

dts?: WithEnabled<DtsOptions>

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.

`Optional`entry

entry?: TsdownInputOption

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

`Optional`env

env?: Record<string, any>

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

Example

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

Default

{}

`Optional`envFile

envFile?: string

Path to env file providing compile-time env variables.

Example

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

`Optional`envPrefix

envPrefix?: string | string[]

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

Default

'TSDOWN_'

`Optional`exe

exe?: WithEnabled<ExeOptions>

[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

`Optional`exports

exports?: WithEnabled<ExportsOptions>

Generate package exports for package.json.

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

Default

false

`Optional`external

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

Deprecated

Use deps.neverBundle instead.

`Optional`failOnWarn

failOnWarn?: boolean | CIOption

If true, fails the build on warnings.

Default

false

`Optional`fixedExtension

fixedExtension?: boolean

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'

`Optional`footer

footer?: ChunkAddon

`Optional`format

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

Output format(s). Available formats are

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

Default

'esm'

`Optional`fromVite

fromVite?: boolean | "vitest"

Reuse config from Vite or Vitest (experimental)

Default

false

`Optional`globalName

globalName?: string

`Optional`globImport

globImport?: boolean

import.meta.glob support.

See

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

Default

true

`Optional`hash

hash?: boolean

If enabled, appends hash to chunk filenames.

Default

true

`Optional`hooks

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

`Optional`ignoreWatch

ignoreWatch?: Arrayable<string | RegExp>

Files or patterns to not watch while in watch mode.

`Optional`injectStyle

injectStyle?: boolean

Deprecated

Use css.inject instead.

`Optional`inlineOnly

inlineOnly?: false | Arrayable<string | RegExp>

Deprecated

Use deps.onlyBundle instead.

`Optional`inputOptions

inputOptions?:
    | InputOptions
    | (
        (
            options: InputOptions,
            format: InternalModuleFormat,
            context: { cjsDts: boolean },
        ) => Awaitable<void | InputOptions | null>
    )

Use with caution; ensure you understand the implications.

`Optional`loader

loader?: ModuleTypes

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

`Optional`logLevel

logLevel?: LogLevel

Log level.

Default

'info'

`Optional`minify

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

Default

false

`Optional`name

name?: string

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.

`Optional`nodeProtocol

nodeProtocol?: boolean | "strip"

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

Example

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

// Input
import 'fs'

// Output
import 'node:fs'

Example

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

// Input
import 'node:fs'

// Output
import 'fs'

Example

`nodeProtocol: false` — do not transform imports

// Input
import 'node:fs'

// Output
import 'node:fs'

`Optional`noExternal

noExternal?: Arrayable<string | RegExp> | NoExternalFn

Deprecated

Use deps.alwaysBundle instead.

`Optional`onSuccess

onSuccess?:
| string
| ((config: ResolvedConfig, signal: AbortSignal) => void | Promise<void>)

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

`Optional`outDir

outDir?: string

Default

'dist'

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

`Optional`outputOptions

outputOptions?:
    | OutputOptions
    | (
        (
            options: OutputOptions,
            format: InternalModuleFormat,
            context: { cjsDts: boolean },
        ) => Awaitable<void | OutputOptions | null>
    )

Use with caution; ensure you understand the implications.

`Optional`platform

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

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

`Optional`plugins

plugins?: TsdownPluginOption

`Optional`publicDir

publicDir?: CopyOptions | CopyOptionsFn

Alias

copy

Deprecated

Alias for copy, will be removed in the future.

`Optional`publint

publint?: WithEnabled<PublintOptions>

Run publint after bundling. Requires publint to be installed.

Default

false

`Optional`removeNodeProtocol

removeNodeProtocol?: boolean

Remove the node: prefix from built-in Node.js module imports. When enabled, rewrites import sources like node:fs to fs.

Default

false

Deprecated

Use nodeProtocol: 'strip' instead.

Example

`removeNodeProtocol: true` — remove the `node:` prefix

// Input
import 'node:fs'

// Output
import 'fs'

`Optional`report

report?: WithEnabled<ReportOptions>

Enable size reporting after bundling.

Default

true

`Optional`root

root?: string

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

`Optional`shims

shims?: boolean

Default

false

`Optional`skipNodeModulesBundle

skipNodeModulesBundle?: boolean

Deprecated

Use deps.skipNodeModulesBundle instead.

Default

false

`Optional`sourcemap

sourcemap?: Sourcemap

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

`Optional`suppressWarnings

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

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.

`Optional`target

target?: string | false | string[]

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.

Example

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

Example

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

Example

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

`Optional`treeshake

treeshake?: boolean | TreeshakingOptions

Configure tree shaking options.

See

https://rolldown.rs/options/treeshake for more details.

Default

true

`Optional`tsconfig

tsconfig?: string | boolean

Default

true

`Optional`unbundle

unbundle?: boolean

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

Default

false

`Optional`unused

unused?: WithEnabled<Options>

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

Default

false

`Optional`watch

watch?: boolean | Arrayable<string>

Default

false

`Optional`workspace

workspace?: true | Arrayable<string> | Workspace

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

`Optional`write

write?: boolean

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

Default

true

Interface UserConfig

Hierarchy (View Summary)

Index

Properties

Properties

Optionalalias

Optionalattw

Default

See

Optionalbanner

Optionalbundle

Deprecated

Default

Optionalchecks

Type Declaration

OptionallegacyCjs?: boolean

Default

OptionalcjsDefault

Default

Optionalclean

Default

Optionalcopy

Example

Optionalcss

OptionalcustomLogger

Optionalcwd

Default

Optionaldefine

Optionaldeps

Optionaldevtools

Default

Optionaldts

Optionalentry

Example

Default

Optionalenv

Example

Default

OptionalenvFile

Example

OptionalenvPrefix

Default

Optionalexe

Default

Optionalexports

Default

Optionalexternal

Deprecated

OptionalfailOnWarn

Default

OptionalfixedExtension

Default

Optionalfooter

Optionalformat

Default

OptionalfromVite

Default

OptionalglobalName

OptionalglobImport

See

Default

Optionalhash

Default

Optionalhooks

OptionalignoreWatch

OptionalinjectStyle

Deprecated

OptionalinlineOnly

Deprecated

OptionalinputOptions

Optionalloader

Example

OptionallogLevel

Default

Optionalminify

Default

Optionalname

OptionalnodeProtocol

Default

Example

`Optional`alias

`Optional`attw

`Optional`banner

`Optional`bundle

`Optional`checks

`Optional`legacyCjs?: boolean

`Optional`cjsDefault

`Optional`clean

`Optional`copy

`Optional`css

`Optional`customLogger

`Optional`cwd

`Optional`define

`Optional`deps

`Optional`devtools

`Optional`dts

`Optional`entry

`Optional`env

`Optional`envFile

`Optional`envPrefix

`Optional`exe

`Optional`exports

`Optional`external

`Optional`failOnWarn

`Optional`fixedExtension

`Optional`footer

`Optional`format

`Optional`fromVite

`Optional`globalName

`Optional`globImport

`Optional`hash

`Optional`hooks

`Optional`ignoreWatch

`Optional`injectStyle

`Optional`inlineOnly

`Optional`inputOptions

`Optional`loader

`Optional`logLevel

`Optional`minify

`Optional`name

`Optional`nodeProtocol

`Optional`noExternal

`Optional`onSuccess

`Optional`outDir

`Optional`outExtension

`Optional`outExtensions

`Optional`outputOptions

`Optional`platform

`Optional`plugins

`Optional`publicDir

`Optional`publint

`Optional`removeNodeProtocol

`Optional`report

`Optional`root

`Optional`shims

`Optional`skipNodeModulesBundle

`Optional`sourcemap

`Optional`suppressWarnings

`Optional`target

`Optional`treeshake

`Optional`tsconfig

`Optional`unbundle

`Optional`unused

`Optional`watch

`Optional`workspace

`Optional`write