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>;
    devtools?: WithEnabled<DevtoolsOptions>;
    dts?: WithEnabled<Options>;
    entry?: TsdownInputOption;
    env?: Record<string, any>;
    envFile?: string;
    envPrefix?: string | string[];
    exports?: WithEnabled<ExportsOptions>;
    external?: string | RegExp | (string | RegExp)[] | ExternalOptionFunction;
    failOnWarn?: boolean | CIOption;
    fixedExtension?: boolean;
    footer?: ChunkAddon;
    format?:
        | "es"
        | "cjs"
        | "esm"
        | "module"
        | "commonjs"
        | "iife"
        | "umd"
        | ("es" | "cjs" | "esm" | "module" | "commonjs" | "iife" | "umd")[]
        | Partial<
            Record<
                "es"
                | "cjs"
                | "esm"
                | "module"
                | "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>;
    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;
    outExtensions?: OutExtensionFactory;
    outputOptions?:
        | OutputOptions
        | (
            (
                options: OutputOptions,
                format: InternalModuleFormat,
                context: { cjsDts: boolean },
            ) => Awaitable<void | OutputOptions | null>
        );
    platform?: "neutral" | "node" | "browser";
    plugins?: RolldownPluginOption<any>;
    publicDir?: CopyOptions | CopyOptionsFn;
    publint?: WithEnabled<PublintOptions>;
    removeNodeProtocol?: boolean;
    report?: WithEnabled<ReportOptions>;
    shims?: boolean;
    skipNodeModulesBundle?: boolean;
    sourcemap?: Sourcemap;
    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;
}

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.

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

`Optional`define

define?: Record<string, string>

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

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

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

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

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

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

exports?: WithEnabled<ExportsOptions>

Generate package exports for package.json.

This will set the main, module, types, exports fields in package.json to point to the generated files.

`Optional`external

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

`Optional`failOnWarn

failOnWarn?: boolean | CIOption

If true, fails the build on warnings.

Default

'ci-only'

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

`Optional`footer

footer?: ChunkAddon

`Optional`format

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

Default

'es'

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

inlineOnly?: false | Arrayable<string | RegExp>

Bundle only the dependencies listed here; throw an error if any others are missing.

undefined (default): Show warnings for bundled dependencies.
false: Suppress all warnings about inlineOnly option.

Note: Be sure to include all required sub-dependencies as well.

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

If true, add node: prefix to built-in modules.
If 'strip', strips the node: protocol prefix from import source.
If false, does not modify the import source.

Default

false

Example

// With nodeProtocol enabled:
import('fs'); // becomes import('node:fs')
// With nodeProtocol set to 'strip':
import('node:fs'); // becomes import('fs')
// With nodeProtocol set to false:
import('node:fs'); // remains import('node:fs')

`Optional`noExternal

noExternal?: Arrayable<string | RegExp> | NoExternalFn

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

`Optional`outExtensions

outExtensions?: OutExtensionFactory

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'

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

If enabled, strips the node: protocol prefix from import source.

Default

false

Deprecated

Use nodeProtocol: 'strip' instead.

Example

// With removeNodeProtocol enabled:
import('node:fs'); // becomes import('fs')

`Optional`report

report?: WithEnabled<ReportOptions>

Enable size reporting after bundling.

Default

true

`Optional`shims

shims?: boolean

Default

false

`Optional`skipNodeModulesBundle

skipNodeModulesBundle?: boolean

Skip bundling node_modules.

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`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'), 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

`Optional`unbundle

unbundle?: boolean

Determines whether unbundle mode 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

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

Optionaldefine

Optionaldevtools

Default

Optionaldts

Optionalentry

Example

Optionalenv

Example

OptionalenvFile

Example

OptionalenvPrefix

Default

Optionalexports

Optionalexternal

OptionalfailOnWarn

Default

OptionalfixedExtension

Optionalfooter

Optionalformat

Default

OptionalfromVite

Default

OptionalglobalName

OptionalglobImport

See

Default

Optionalhash

Default

Optionalhooks

OptionalignoreWatch

OptionalinlineOnly

OptionalinputOptions

Optionalloader

Example

OptionallogLevel

Default

Optionalminify

Default

Optionalname

OptionalnodeProtocol

Default

Example

OptionalnoExternal

OptionalonSuccess

OptionaloutDir

Default

OptionaloutExtensions

OptionaloutputOptions

Optionalplatform

Default

See

Optionalplugins

OptionalpublicDir

Deprecated

Optionalpublint

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

`Optional`dts

`Optional`entry

`Optional`env

`Optional`envFile

`Optional`envPrefix

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

`Optional`inputOptions

`Optional`loader

`Optional`logLevel

`Optional`minify

`Optional`name

`Optional`nodeProtocol

`Optional`noExternal

`Optional`onSuccess

`Optional`outDir

`Optional`outExtensions

`Optional`outputOptions

`Optional`platform

`Optional`plugins

`Optional`publicDir

`Optional`publint

`Optional`removeNodeProtocol

`Optional`report

`Optional`shims

`Optional`skipNodeModulesBundle

`Optional`sourcemap

`Optional`target

`Optional`treeshake

`Optional`tsconfig

`Optional`unbundle

`Optional`unused

`Optional`watch

`Optional`workspace

`Optional`write