---
url: /reference/api/Interface.UserConfig.md
---
# Interface: UserConfig

Defined in: [src/config/types.ts:158](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L158)

Options for tsdown.

## Extended by

* [`InlineConfig`](Interface.InlineConfig.md)

## Properties

### alias?

```ts
optional alias?: Record<string, string>;
```

Defined in: [src/config/types.ts:180](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L180)

***

### attw?

```ts
optional attw?: WithEnabled<AttwOptions>;
```

Defined in: [src/config/types.ts:578](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L578)

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

#### Default

```ts
false
```

#### See

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

***

### banner?

```ts
optional banner?: ChunkAddon;
```

Defined in: [src/config/types.ts:405](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L405)

***

### checks?

```ts
optional checks?: ChecksOptions & object;
```

Defined in: [src/config/types.ts:334](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L334)

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?

```ts
optional legacyCjs?: boolean;
```

If the config includes the `cjs` format and
one of its targets is a Node.js version that supports `require(esm)`
(`^20.19.0 || >=22.12.0`),
warn the user about the deprecation of CommonJS.

###### Default

```ts
true
```

***

### cjsDefault?

```ts
optional cjsDefault?: boolean;
```

Defined in: [src/config/types.ts:455](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L455)

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

```ts
true
```

***

### clean?

```ts
optional clean?: boolean | string[];
```

Defined in: [src/config/types.ts:399](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L399)

Clean directories before build.

Default to output directory.

#### Default

```ts
true
```

***

### copy?

```ts
optional copy?:
  | CopyOptions
  | CopyOptionsFn;
```

Defined in: [src/config/types.ts:622](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L622)

Copy files to another directory.

#### Example

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

***

### css?

```ts
optional css?: CssOptions;
```

Defined in: [src/config/types.ts:607](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L607)

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

***

### customLogger?

```ts
optional customLogger?: Logger;
```

Defined in: [src/config/types.ts:508](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L508)

Custom logger.

***

### cwd?

```ts
optional cwd?: string;
```

Defined in: [src/config/types.ts:478](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L478)

The working directory of the config file.

* Defaults to process.cwd | process.cwd() for root config.
* Defaults to the package directory for [`workspace`](#workspace) config.

#### Default

```ts
process.cwd()
```

***

### define?

```ts
optional define?: Record<string, string>;
```

Defined in: [src/config/types.ts:255](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L255)

***

### deps?

```ts
optional deps?: DepsConfig;
```

Defined in: [src/config/types.ts:178](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L178)

Dependency handling options.

***

### devtools?

```ts
optional devtools?: WithEnabled<DevtoolsOptions>;
```

Defined in: [src/config/types.ts:537](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L537)

**\[experimental]** Enable devtools.

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

This may slow down the build process significantly.

#### Default

```ts
false
```

***

### dts?

```ts
optional dts?: WithEnabled<DtsOptions>;
```

Defined in: [src/config/types.ts:555](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L555)

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

By default, this option is auto-detected:

* If [`exe`](#exe) is enabled, declaration file generation is disabled by default.
* If the `types` or `typings` field is present in `package.json`, or if its `exports` field contains a `types` entry, declaration file generation is enabled by default.
* Otherwise, if the resolved `tsconfig.json` has `declaration: true`, declaration file generation is enabled by default.
* Otherwise, declaration file generation is disabled by default.

***

### entry?

```ts
optional entry?: TsdownInputOption;
```

Defined in: [src/config/types.ts:173](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L173)

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

Supports glob patterns with negation to exclude files:

#### Example

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

#### Default

```ts
{
  index: 'src/index.ts'
}
```

***

### env?

```ts
optional env?: Record<string, any>;
```

Defined in: [src/config/types.ts:243](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L243)

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

#### Example

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

#### Default

```ts
{
}
```

***

### envFile?

```ts
optional envFile?: string;
```

Defined in: [src/config/types.ts:249](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L249)

Path to env file providing compile-time env variables.

#### Example

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

***

### envPrefix?

```ts
optional envPrefix?: string | string[];
```

Defined in: [src/config/types.ts:254](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L254)

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

#### Default

```ts
'TSDOWN_'
```

***

### exe?

```ts
optional exe?: WithEnabled<ExeOptions>;
```

Defined in: [src/config/types.ts:635](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L635)

**\[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

```ts
false
```

***

### exports?

```ts
optional exports?: WithEnabled<ExportsOptions>;
```

Defined in: [src/config/types.ts:601](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L601)

Generate package exports for `package.json`.

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

#### Default

```ts
false
```

***

### ~~external?~~

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

Defined in: [src/config/types.ts:651](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L651)

Cannot be combined with `deps.neverBundle`; setting both throws an error.

#### Deprecated

Use [`deps.neverBundle`](Interface.DepsConfig.md#neverbundle) instead.

***

### failOnWarn?

```ts
optional failOnWarn?: boolean | CIOption;
```

Defined in: [src/config/types.ts:496](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L496)

If true, fails the build on warnings.

#### Default

```ts
false
```

***

### fixedExtension?

```ts
optional fixedExtension?: boolean;
```

Defined in: [src/config/types.ts:434](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L434)

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`](#platform) is set to `node`,
`false` otherwise.

#### Default

```ts
platform === 'node'
```

***

### footer?

```ts
optional footer?: ChunkAddon;
```

Defined in: [src/config/types.ts:404](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L404)

***

### format?

```ts
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:371](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L371)

Output format(s). Available formats are

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

#### Default

```ts
'esm'
```

***

### fromVite?

```ts
optional fromVite?: boolean | "vitest";
```

Defined in: [src/config/types.ts:517](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L517)

Reuse config from Vite or Vitest (experimental)

#### Default

```ts
false
```

***

### globalName?

```ts
optional globalName?: string;
```

Defined in: [src/config/types.ts:372](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L372)

***

### globImport?

```ts
optional globImport?: boolean;
```

Defined in: [src/config/types.ts:591](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L591)

`import.meta.glob` support.

#### See

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

#### Default

```ts
true
```

***

### hash?

```ts
optional hash?: boolean;
```

Defined in: [src/config/types.ts:446](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L446)

If enabled, appends hash to chunk filenames.

#### Default

```ts
true
```

***

### hooks?

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

Defined in: [src/config/types.ts:624](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L624)

***

### ignoreWatch?

```ts
optional ignoreWatch?: Arrayable<string | RegExp>;
```

Defined in: [src/config/types.ts:526](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L526)

Files or patterns to not watch while in watch mode.

***

### inputOptions?

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

Defined in: [src/config/types.ts:351](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L351)

Use with caution; ensure you understand the implications.

***

### loader?

```ts
optional loader?: ModuleTypes;
```

Defined in: [src/config/types.ts:285](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L285)

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

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

***

### logLevel?

```ts
optional logLevel?: LogLevel;
```

Defined in: [src/config/types.ts:491](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L491)

Log level.

#### Default

```ts
'info'
```

***

### minify?

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

Defined in: [src/config/types.ts:403](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L403)

#### Default

```ts
'dce-only'
```

***

### name?

```ts
optional name?: string;
```

Defined in: [src/config/types.ts:485](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L485)

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?

```ts
optional nodeProtocol?: boolean | "strip";
```

Defined in: [src/config/types.ts:329](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L329)

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

```ts
false
```

#### Examples

```ts
// Input
import 'fs'

// Output
import 'node:fs'
```

```ts
// Input
import 'node:fs'

// Output
import 'fs'
```

```ts
// Input
import 'node:fs'

// Output
import 'node:fs'
```

***

### ~~noExternal?~~

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

Defined in: [src/config/types.ts:656](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L656)

Cannot be combined with `deps.alwaysBundle`; setting both throws an error.

#### Deprecated

Use [`deps.alwaysBundle`](Interface.DepsConfig.md#alwaysbundle) instead.

***

### onSuccess?

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

Defined in: [src/config/types.ts:542](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L542)

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

***

### outDir?

```ts
optional outDir?: string;
```

Defined in: [src/config/types.ts:376](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L376)

#### Default

```ts
'dist'
```

***

### outExtensions?

```ts
optional outExtensions?: OutExtensionFactory;
```

Defined in: [src/config/types.ts:440](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L440)

Custom extensions for output files.
[`fixedExtension`](#fixedextension) will be overridden by this option.

***

### outputOptions?

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

Defined in: [src/config/types.ts:460](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L460)

Use with caution; ensure you understand the implications.

***

### platform?

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

Defined in: [src/config/types.ts:198](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L198)

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

```ts
'node'
```

#### See

https://tsdown.dev/options/platform

***

### plugins?

```ts
optional plugins?: TsdownPluginOption;
```

Defined in: [src/config/types.ts:346](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L346)

***

### publint?

```ts
optional publint?: WithEnabled<PublintOptions>;
```

Defined in: [src/config/types.ts:569](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L569)

Run `publint` after bundling.
Requires `publint` to be installed.

#### Default

```ts
false
```

***

### report?

```ts
optional report?: WithEnabled<ReportOptions>;
```

Defined in: [src/config/types.ts:584](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L584)

Enable size reporting after bundling.

#### Default

```ts
true
```

***

### root?

```ts
optional root?: string;
```

Defined in: [src/config/types.ts:422](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L422)

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?

```ts
optional shims?: boolean;
```

Defined in: [src/config/types.ts:267](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L267)

Inject CJS `__dirname` and `__filename` shims into ESM output.
Only applies when [`platform`](#platform) is set to `node`.

Note: `import.meta.url`, `import.meta.dirname`, and `import.meta.filename`
are always shimmed in CJS output, regardless of this option.

#### See

https://tsdown.dev/options/shims

#### Default

```ts
false
```

***

### sourcemap?

```ts
optional sourcemap?: Sourcemap;
```

Defined in: [src/config/types.ts:392](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L392)

Whether to generate source map files.

Note that this option will always be `true` if you have
[\`declarationMap\`](https://www.typescriptlang.org/tsconfig/#declarationMap)
option enabled in your `tsconfig.json`.

#### Default

```ts
false
```

***

### suppressWarnings?

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

Defined in: [src/config/types.ts:504](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L504)

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?

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

Defined in: [src/config/types.ts:229](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L229)

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

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

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

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

***

### treeshake?

```ts
optional treeshake?: boolean | TreeshakingOptions;
```

Defined in: [src/config/types.ts:274](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L274)

Configure tree shaking options.

#### See

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

#### Default

```ts
true
```

***

### tsconfig?

```ts
optional tsconfig?: string | boolean;
```

Defined in: [src/config/types.ts:185](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L185)

#### Default

```ts
true
```

***

### unbundle?

```ts
optional unbundle?: boolean;
```

Defined in: [src/config/types.ts:412](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L412)

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

#### Default

```ts
false
```

***

### unused?

```ts
optional unused?: WithEnabled<Options>;
```

Defined in: [src/config/types.ts:562](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L562)

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

#### Default

```ts
false
```

***

### watch?

```ts
optional watch?: boolean | Arrayable<string>;
```

Defined in: [src/config/types.ts:522](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L522)

#### Default

```ts
false
```

***

### workspace?

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

Defined in: [src/config/types.ts:641](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L641)

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

***

### write?

```ts
optional write?: boolean;
```

Defined in: [src/config/types.ts:382](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/config/types.ts#L382)

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

#### Default

```ts
true
```