---
url: /reference/api/Interface.TsdownPlugin.md
---
# Interface: TsdownPlugin\<A>

Defined in: [src/features/plugin.ts:16](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/features/plugin.ts#L16)

A tsdown-aware plugin. Extends Rolldown's `Plugin` with
tsdown-specific lifecycle hooks.

Plugins that only use Rolldown's own lifecycle continue to work unchanged;
tsdown detects these optional methods via runtime duck-typing.

## Type Parameters

### A

`A` = `any`

## Properties

### api?

```ts
optional api?: A;
```

Defined in: node\_modules/.pnpm/rolldown@1.2.8/node\_modules/rolldown/dist/shared/define-config-DjHYbH6S.d.mts:3299

Used for inter-plugin communication.

#### Inherited from

```ts
Plugin.api
```

***

### meta?

```ts
optional meta?: PluginMeta;
```

Defined in: node\_modules/.pnpm/rolldown@1.2.8/node\_modules/rolldown/dist/shared/define-config-DjHYbH6S.d.mts:3284

**`Experimental`**

Descriptive metadata about the plugin, such as the npm package it ships in.

This does not affect bundling; it is informational and intended to be
surfaced by tooling that inspects a build. See `PluginMeta`.

#### Inherited from

```ts
Plugin.meta
```

***

### name

```ts
name: string
```

Defined in: node\_modules/.pnpm/rolldown@1.2.8/node\_modules/rolldown/dist/shared/define-config-DjHYbH6S.d.mts:3273

The name of the plugin, for use in error messages and logs.

#### Inherited from

```ts
Plugin.name
```

***

### tsdownConfig?

```ts
optional tsdownConfig?: (config, inlineConfig) => Awaitable<void | UserConfig | null>;
```

Defined in: [src/features/plugin.ts:36](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/features/plugin.ts#L36)

Modify tsdown's user config before it is resolved. Analogous to Vite's
[`config`](https://vite.dev/guide/api-plugin.html#config) hook.

The hook may mutate `config` in place, or return a partial
[`UserConfig`](Interface.UserConfig.md) that will be deep-merged into the current config.
Array fields are replaced (not concatenated) during merging — to append
plugins, mutate [`config.plugins`](Interface.UserConfig.md#plugins) in place.

The second argument is the original [`InlineConfig`](Interface.InlineConfig.md) passed to
[`build()`](Function.build.md) (typically the CLI flags), useful for
distinguishing values that came from the command line vs. the config file.

Plugins injected via [`fromVite`](Interface.UserConfig.md#fromvite) do not
receive this hook, because they are loaded after the
[`tsdownConfig`](#tsdownconfig) phase. Likewise, new plugins added by another
plugin's [`tsdownConfig`](#tsdownconfig) do not themselves receive this hook
(plugins are snapshotted before dispatch).

#### Parameters

##### config

[`UserConfig`](Interface.UserConfig.md)

##### inlineConfig

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

#### Returns

`Awaitable`<`void` | [`UserConfig`](Interface.UserConfig.md) | `null`>

***

### tsdownConfigResolved?

```ts
optional tsdownConfigResolved?: (resolvedConfig) => Awaitable<void>;
```

Defined in: [src/features/plugin.ts:51](https://github.com/rolldown/tsdown/blob/eb40c95efdf7f98d0aa7b0178a3b7322986bd419/src/features/plugin.ts#L51)

Called after tsdown has fully resolved the user config. Analogous to
Vite's [`configResolved`](https://vite.dev/guide/api-plugin.html#configresolved)
hook.

This hook fires once per produced [`ResolvedConfig`](TypeAlias.ResolvedConfig.md) — i.e. once
per output format when [`format`](Interface.UserConfig.md#format) is an array.
Typical usage is to stash the resolved config for later use in
Rolldown hooks. Mutations made to `resolvedConfig` here are
not supported.

#### Parameters

##### resolvedConfig

[`ResolvedConfig`](TypeAlias.ResolvedConfig.md)

#### Returns

`Awaitable`<`void`>

***

### version?

```ts
optional version?: string;
```

Defined in: node\_modules/.pnpm/rolldown@1.2.8/node\_modules/rolldown/dist/shared/define-config-DjHYbH6S.d.mts:3275

The version of the plugin, for use in inter-plugin communication scenarios.

#### Inherited from

```ts
Plugin.version
```

## Build Hooks

### buildEnd?

```ts
optional buildEnd?: ObjectHook<(this, ...parameters) => void | Promise<void>, {
  sequential?: boolean;
}>;
```

Defined in: node\_modules/.pnpm/rolldown@1.2.8/node\_modules/rolldown/dist/shared/define-config-DjHYbH6S.d.mts:3061

Called when Rolldown has finished bundling, but before Output Generation Hooks.
If an error occurred during the build, it is passed on to this hook.

#### Kind

async parallel

#### Inherited from

```ts
Plugin.buildEnd
```

***

### buildStart?

```ts
optional buildStart?: ObjectHook<(this, ...parameters) => void | Promise<void>, {
  sequential?: boolean;
}>;
```

Defined in: node\_modules/.pnpm/rolldown@1.2.8/node\_modules/rolldown/dist/shared/define-config-DjHYbH6S.d.mts:2982

Called on each rolldown | rolldown() build.

This is the recommended hook to use when you need access to the options passed to rolldown | rolldown() as it takes the transformations by all options hooks into account and also contains the right default values for unset options.

#### Kind

async parallel

#### Inherited from

```ts
Plugin.buildStart
```

***

### closeWatcher?

```ts
optional closeWatcher?: ObjectHook<(this, ...parameters) => void | Promise<void>, {
  sequential?: boolean;
}>;
```

Defined in: node\_modules/.pnpm/rolldown@1.2.8/node\_modules/rolldown/dist/shared/define-config-DjHYbH6S.d.mts:3190

Notifies a plugin when the watcher process will close so that all open resources can be closed too.

This hook cannot be used by output plugins.

#### Kind

async parallel

#### Inherited from

```ts
Plugin.closeWatcher
```

***

### load?

```ts
optional load?: ObjectHook<(this, ...parameters) => MaybePromise<LoadResult> | Promise<MaybePromise<LoadResult>>, {
  filter?: TopLevelFilterExpression[] | Pick<HookFilter, "id">;
}>;
```

Defined in: node\_modules/.pnpm/rolldown@1.2.8/node\_modules/rolldown/dist/shared/define-config-DjHYbH6S.d.mts:3022

Defines a custom loader.

Returning `null` defers to other `load` hooks or the built-in loading mechanism.

You can use PluginContext.getModuleInfo | this.getModuleInfo() to find out the previous values of `meta`, `moduleSideEffects` inside this hook.

#### Kind

async first

#### Inherited from

```ts
Plugin.load
```

***

### moduleParsed?

```ts
optional moduleParsed?: ObjectHook<(this, ...parameters) => void | Promise<void>, {
  sequential?: boolean;
}>;
```

Defined in: node\_modules/.pnpm/rolldown@1.2.8/node\_modules/rolldown/dist/shared/define-config-DjHYbH6S.d.mts:3053

This hook is called each time a module has been fully parsed by Rolldown.

This hook will wait until all imports are resolved so that the information in
ModuleInfo.importedIds | moduleInfo.importedIds,
ModuleInfo.dynamicallyImportedIds | moduleInfo.dynamicallyImportedIds
are complete and accurate. Note however that information about importing modules
may be incomplete as additional importers could be discovered later.
If you need this information, use the [`buildEnd`](#buildend) hook.

#### Kind

async parallel

#### Inherited from

```ts
Plugin.moduleParsed
```

***

### onLog?

```ts
optional onLog?: ObjectHook<(this, level, log) => boolean | NullValue<void>, {
}>;
```

Defined in: node\_modules/.pnpm/rolldown@1.2.8/node\_modules/rolldown/dist/shared/define-config-DjHYbH6S.d.mts:2945

A function that receives and filters logs and warnings generated by Rolldown and
plugins before they are passed to the InputOptions.onLog | onLog option
or printed to the console.

If `false` is returned, the log will be filtered out.
Otherwise, the log will be handed to the `onLog` hook of the next plugin,
the InputOptions.onLog | onLog option, or printed to the console.
Plugins can also change the log level of a log or turn a log into an error by passing
the `log` object to MinimalPluginContext.error | this.error,
MinimalPluginContext.warn | this.warn,
MinimalPluginContext.info | this.info or
MinimalPluginContext.debug | this.debug and returning `false`.

#### Kind

sync sequential

#### Inherited from

```ts
Plugin.onLog
```

***

### options?

```ts
optional options?: ObjectHook<(this, ...parameters) => NullValue<void> | InputOptions | Promise<NullValue<void> | InputOptions>, {
}>;
```

Defined in: node\_modules/.pnpm/rolldown@1.2.8/node\_modules/rolldown/dist/shared/define-config-DjHYbH6S.d.mts:2958

Replaces or manipulates the options object passed to rolldown | rolldown().

Returning `null` does not replace anything.

If you just need to read the options, it is recommended to use
the [`buildStart`](#buildstart) hook as that hook has access to the options
after the transformations from all `options` hooks have been taken into account.

#### Kind

async sequential

#### Inherited from

```ts
Plugin.options
```

***

### outputOptions?

```ts
optional outputOptions?: ObjectHook<(this, options) => NullValue<void> | OutputOptions, {
}>;
```

Defined in: node\_modules/.pnpm/rolldown@1.2.8/node\_modules/rolldown/dist/shared/define-config-DjHYbH6S.d.mts:2973

Replaces or manipulates the output options object passed to
RolldownBuild.generate | bundle.generate() or
RolldownBuild.write | bundle.write().

Returning null does not replace anything.

If you just need to read the output options, it is recommended to use
the [`renderStart`](#renderstart) hook as this hook has access to the output options
after the transformations from all `outputOptions` hooks have been taken into account.

#### Kind

sync sequential

#### Inherited from

```ts
Plugin.outputOptions
```

***

### ~~resolveDynamicImport?~~

```ts
optional resolveDynamicImport?: ObjectHook<(this, ...parameters) => ResolveIdResult | Promise<ResolveIdResult>, {
}>;
```

Defined in: node\_modules/.pnpm/rolldown@1.2.8/node\_modules/rolldown/dist/shared/define-config-DjHYbH6S.d.mts:3011

Defines a custom resolver for dynamic imports.

#### Deprecated

This hook exists only for Rollup compatibility. Please use [`resolveId`](#resolveid) instead.

#### Kind

async first

#### Inherited from

```ts
Plugin.resolveDynamicImport
```

***

### resolveId?

```ts
optional resolveId?: ObjectHook<(this, ...parameters) => ResolveIdResult | Promise<ResolveIdResult>, {
  filter?:   | {
     id?: GeneralHookFilter<RegExp> | undefined;
   }
     | TopLevelFilterExpression[];
}>;
```

Defined in: node\_modules/.pnpm/rolldown@1.2.8/node\_modules/rolldown/dist/shared/define-config-DjHYbH6S.d.mts:3001

Defines a custom resolver.

A resolver can be useful for e.g. locating third-party dependencies.

Returning `null` defers to other `resolveId` hooks and eventually the default resolution behavior.
Returning `false` signals that `source` should be treated as an external module and not included in the bundle. If this happens for a relative import, the id will be renormalized the same way as when the `InputOptions.external` option is used.
If you return an object, then it is possible to resolve an import to a different id while excluding it from the bundle at the same time.

Note that while `resolveId` will be called for each import of a module and can therefore
resolve to the same `id` many times, values for `external`, `meta` or `moduleSideEffects`
can only be set once before the module is loaded. The reason is that after this call,
Rolldown will continue with the [`load`](#load) and [`transform`](#transform) hooks for that
module that may override these values and should take precedence if they do so.

#### Kind

async first

#### Inherited from

```ts
Plugin.resolveId
```

***

### transform?

```ts
optional transform?: ObjectHook<(this, ...parameters) => TransformResult | Promise<TransformResult>, {
  filter?: TopLevelFilterExpression[] | HookFilter;
}>;
```

Defined in: node\_modules/.pnpm/rolldown@1.2.8/node\_modules/rolldown/dist/shared/define-config-DjHYbH6S.d.mts:3035

Can be used to transform individual modules.

Note that it's possible to return only properties and no code transformations.

You can use PluginContext.getModuleInfo | this.getModuleInfo() to find out the previous values of `meta`, `moduleSideEffects` inside this hook.

#### Kind

async sequential

#### Inherited from

```ts
Plugin.transform
```

***

### watchChange?

```ts
optional watchChange?: ObjectHook<(this, ...parameters) => void | Promise<void>, {
  sequential?: boolean;
}>;
```

Defined in: node\_modules/.pnpm/rolldown@1.2.8/node\_modules/rolldown/dist/shared/define-config-DjHYbH6S.d.mts:3179

Notifies a plugin whenever Rolldown has detected a change to a monitored file in watch mode.

If a build is currently running, this hook is called once the build finished.
It will be called once for every file that changed.

This hook cannot be used by output plugins.

If you need to be notified immediately when a file changed, you can use the WatcherOptions.onInvalidate | watch.onInvalidate option.

#### Kind

async parallel

#### Inherited from

```ts
Plugin.watchChange
```

## Output Generation Hooks

### augmentChunkHash?

```ts
optional augmentChunkHash?: ObjectHook<(this, chunk) => string | void, {
}>;
```

Defined in: node\_modules/.pnpm/rolldown@1.2.8/node\_modules/rolldown/dist/shared/define-config-DjHYbH6S.d.mts:3109

Can be used to augment the hash of individual chunks. Called for each Rolldown output chunk.

Returning a falsy value will not modify the hash.
Truthy values will be used as an additional source for hash calculation.

#### Kind

sync sequential

#### Inherited from

```ts
Plugin.augmentChunkHash
```

***

### banner?

```ts
optional banner?: ObjectHook<AddonHook, {
}>;
```

Defined in: node\_modules/.pnpm/rolldown@1.2.8/node\_modules/rolldown/dist/shared/define-config-DjHYbH6S.d.mts:3223

A hook equivalent to OutputOptions.banner | output.banner option.

#### Kind

async sequential

#### Inherited from

```ts
Plugin.banner
```

***

### closeBundle?

```ts
optional closeBundle?: ObjectHook<(this, ...parameters) => void | Promise<void>, {
  sequential?: boolean;
}>;
```

Defined in: node\_modules/.pnpm/rolldown@1.2.8/node\_modules/rolldown/dist/shared/define-config-DjHYbH6S.d.mts:3165

Can be used to clean up any external service that may be running.

Rolldown's CLI will make sure this hook is called after each run, but it is the responsibility
of users of the JavaScript API to manually call
RolldownBuild.close | bundle.close() once they are done generating bundles.
For that reason, any plugin relying on this feature should carefully mention this in
its documentation.

If a plugin wants to retain resources across builds in watch mode, they can check for
PluginContextMeta.watchMode | this.meta.watchMode in this hook and perform
the necessary cleanup for watch mode in closeWatcher.

#### Kind

async parallel

#### Inherited from

```ts
Plugin.closeBundle
```

***

### footer?

```ts
optional footer?: ObjectHook<AddonHook, {
}>;
```

Defined in: node\_modules/.pnpm/rolldown@1.2.8/node\_modules/rolldown/dist/shared/define-config-DjHYbH6S.d.mts:3230

A hook equivalent to OutputOptions.footer | output.footer option.

#### Kind

async sequential

#### Inherited from

```ts
Plugin.footer
```

***

### generateBundle?

```ts
optional generateBundle?: ObjectHook<(this, ...parameters) => void | Promise<void>, {
}>;
```

Defined in: node\_modules/.pnpm/rolldown@1.2.8/node\_modules/rolldown/dist/shared/define-config-DjHYbH6S.d.mts:3140

Called at the end of RolldownBuild.generate | bundle.generate() or
immediately before the files are written in
RolldownBuild.write | bundle.write().

To modify the files after they have been written, use the [`writeBundle`](#writebundle) hook.

#### Kind

async sequential

#### Inherited from

```ts
Plugin.generateBundle
```

***

### intro?

```ts
optional intro?: ObjectHook<AddonHook, {
}>;
```

Defined in: node\_modules/.pnpm/rolldown@1.2.8/node\_modules/rolldown/dist/shared/define-config-DjHYbH6S.d.mts:3237

A hook equivalent to OutputOptions.intro | output.intro option.

#### Kind

async sequential

#### Inherited from

```ts
Plugin.intro
```

***

### outro?

```ts
optional outro?: ObjectHook<AddonHook, {
}>;
```

Defined in: node\_modules/.pnpm/rolldown@1.2.8/node\_modules/rolldown/dist/shared/define-config-DjHYbH6S.d.mts:3244

A hook equivalent to OutputOptions.outro | output.outro option.

#### Kind

async sequential

#### Inherited from

```ts
Plugin.outro
```

***

### renderChunk?

```ts
optional renderChunk?: ObjectHook<(this, ...parameters) => string | NullValue<void> | RolldownMagicString | { code: string | RolldownMagicString; map?: SourceMapInput | undefined; } | Promise<...>, {
  filter?: TopLevelFilterExpression[] | Pick<HookFilter, "code">;
}>;
```

Defined in: node\_modules/.pnpm/rolldown@1.2.8/node\_modules/rolldown/dist/shared/define-config-DjHYbH6S.d.mts:3094

Can be used to transform individual chunks. Called for each Rolldown output chunk file.

Returning null will apply no transformations. If you change code in this hook and want to support source maps, you need to return a map describing your changes, see [Source Code Transformations section](https://rolldown.rs/apis/plugin-api/transformations#source-code-transformations).

`chunk` is mutable and changes applied in this hook will propagate to other plugins and
to the generated bundle.
That means if you add or remove imports or exports in this hook, you should update
RenderedChunk.imports | imports, RenderedChunk.importedBindings | importedBindings and/or RenderedChunk.exports | exports accordingly.

#### Kind

async sequential

#### Inherited from

```ts
Plugin.renderChunk
```

***

### renderError?

```ts
optional renderError?: ObjectHook<(this, ...parameters) => void | Promise<void>, {
  sequential?: boolean;
}>;
```

Defined in: node\_modules/.pnpm/rolldown@1.2.8/node\_modules/rolldown/dist/shared/define-config-DjHYbH6S.d.mts:3127

Called when Rolldown encounters an error during
RolldownBuild.generate | bundle.generate() or
RolldownBuild.write | bundle.write().

To get notified when generation completes successfully, use the
[`generateBundle`](#generatebundle) hook.

#### Kind

async parallel

#### Inherited from

```ts
Plugin.renderError
```

***

### renderStart?

```ts
optional renderStart?: ObjectHook<(this, ...parameters) => void | Promise<void>, {
  sequential?: boolean;
}>;
```

Defined in: node\_modules/.pnpm/rolldown@1.2.8/node\_modules/rolldown/dist/shared/define-config-DjHYbH6S.d.mts:3080

Called initially each time RolldownBuild.generate | bundle.generate() or
RolldownBuild.write | bundle.write() is called.

To get notified when generation has completed, use the [`generateBundle`](#generatebundle) and
[`renderError`](#rendererror) hooks.

This is the recommended hook to use when you need access to the output options passed to
RolldownBuild.generate | bundle.generate() or
RolldownBuild.write | bundle.write() as it takes the transformations by all outputOptions hooks into account and also contains the right default values for unset options.

It also receives the input options passed to rolldown | rolldown() so that
plugins that can be used as output plugins, i.e. plugins that only use generate phase hooks,
can get access to them.

#### Kind

async parallel

#### Inherited from

```ts
Plugin.renderStart
```

***

### resolveFileUrl?

```ts
optional resolveFileUrl?: ObjectHook<(this, args) => string | NullValue<void>, {
}>;
```

Defined in: node\_modules/.pnpm/rolldown@1.2.8/node\_modules/rolldown/dist/shared/define-config-DjHYbH6S.d.mts:3115

#### Inherited from

```ts
Plugin.resolveFileUrl
```

***

### writeBundle?

```ts
optional writeBundle?: ObjectHook<(this, ...parameters) => void | Promise<void>, {
  sequential?: boolean;
}>;
```

Defined in: node\_modules/.pnpm/rolldown@1.2.8/node\_modules/rolldown/dist/shared/define-config-DjHYbH6S.d.mts:3148

Called only at the end of RolldownBuild.write | bundle.write() once
all files have been written.

#### Kind

async parallel

#### Inherited from

```ts
Plugin.writeBundle
```