tsdown

Interface: TsdownPlugin<A> ​

Defined in: src/features/plugin.ts:16

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
api?: A;

Defined in: node_modules/.pnpm/rolldown@1.2.15/node_modules/rolldown/dist/shared/define-config-BoIay7tU.d.mts:3342

Used for inter-plugin communication.

Inherited from ​

Plugin.api

meta? ​

ts
meta?: PluginMeta;

Defined in: node_modules/.pnpm/rolldown@1.2.15/node_modules/rolldown/dist/shared/define-config-BoIay7tU.d.mts:3327

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 ​

Plugin.meta

name ​

ts
name: string

Defined in: node_modules/.pnpm/rolldown@1.2.15/node_modules/rolldown/dist/shared/define-config-BoIay7tU.d.mts:3316

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

Inherited from ​

Plugin.name

tsdownConfig? ​

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

Defined in: src/features/plugin.ts:36

Modify tsdown's user config before it is resolved. Analogous to Vite's config hook.

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

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

Plugins injected via fromVite do not receive this hook, because they are loaded after the tsdownConfig phase. Likewise, new plugins added by another plugin's tsdownConfig do not themselves receive this hook (plugins are snapshotted before dispatch).

Parameters ​

config ​

UserConfig

inlineConfig ​

InlineConfig

Returns ​

Awaitable<void | UserConfig | null>

tsdownConfigResolved? ​

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

Defined in: src/features/plugin.ts:51

Called after tsdown has fully resolved the user config. Analogous to Vite's configResolved hook.

This hook fires once per produced ResolvedConfig — i.e. once per output format when 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

Returns ​

Awaitable<void>

version? ​

ts
version?: string;

Defined in: node_modules/.pnpm/rolldown@1.2.15/node_modules/rolldown/dist/shared/define-config-BoIay7tU.d.mts:3318

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

Inherited from ​

Plugin.version

Build Hooks ​

buildEnd? ​

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

Defined in: node_modules/.pnpm/rolldown@1.2.15/node_modules/rolldown/dist/shared/define-config-BoIay7tU.d.mts:3104

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 ​

Plugin.buildEnd

buildStart? ​

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

Defined in: node_modules/.pnpm/rolldown@1.2.15/node_modules/rolldown/dist/shared/define-config-BoIay7tU.d.mts:3025

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 ​

Plugin.buildStart

closeWatcher? ​

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

Defined in: node_modules/.pnpm/rolldown@1.2.15/node_modules/rolldown/dist/shared/define-config-BoIay7tU.d.mts:3233

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 ​

Plugin.closeWatcher

load? ​

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

Defined in: node_modules/.pnpm/rolldown@1.2.15/node_modules/rolldown/dist/shared/define-config-BoIay7tU.d.mts:3065

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 ​

Plugin.load

moduleParsed? ​

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

Defined in: node_modules/.pnpm/rolldown@1.2.15/node_modules/rolldown/dist/shared/define-config-BoIay7tU.d.mts:3096

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

Kind ​

async parallel

Inherited from ​

Plugin.moduleParsed

onLog? ​

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

Defined in: node_modules/.pnpm/rolldown@1.2.15/node_modules/rolldown/dist/shared/define-config-BoIay7tU.d.mts:2988

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 ​

Plugin.onLog

options? ​

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

Defined in: node_modules/.pnpm/rolldown@1.2.15/node_modules/rolldown/dist/shared/define-config-BoIay7tU.d.mts:3001

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 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 ​

Plugin.options

outputOptions? ​

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

Defined in: node_modules/.pnpm/rolldown@1.2.15/node_modules/rolldown/dist/shared/define-config-BoIay7tU.d.mts:3016

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 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 ​

Plugin.outputOptions

resolveDynamicImport? ​

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

Defined in: node_modules/.pnpm/rolldown@1.2.15/node_modules/rolldown/dist/shared/define-config-BoIay7tU.d.mts:3054

Defines a custom resolver for dynamic imports.

Deprecated ​

This hook exists only for Rollup compatibility. Please use resolveId instead.

Kind ​

async first

Inherited from ​

Plugin.resolveDynamicImport

resolveId? ​

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

Defined in: node_modules/.pnpm/rolldown@1.2.15/node_modules/rolldown/dist/shared/define-config-BoIay7tU.d.mts:3044

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 and transform hooks for that module that may override these values and should take precedence if they do so.

Kind ​

async first

Inherited from ​

Plugin.resolveId

transform? ​

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

Defined in: node_modules/.pnpm/rolldown@1.2.15/node_modules/rolldown/dist/shared/define-config-BoIay7tU.d.mts:3078

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 ​

Plugin.transform

watchChange? ​

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

Defined in: node_modules/.pnpm/rolldown@1.2.15/node_modules/rolldown/dist/shared/define-config-BoIay7tU.d.mts:3222

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 ​

Plugin.watchChange

Output Generation Hooks ​

augmentChunkHash? ​

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

Defined in: node_modules/.pnpm/rolldown@1.2.15/node_modules/rolldown/dist/shared/define-config-BoIay7tU.d.mts:3152

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 ​

Plugin.augmentChunkHash

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

Defined in: node_modules/.pnpm/rolldown@1.2.15/node_modules/rolldown/dist/shared/define-config-BoIay7tU.d.mts:3266

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

Kind ​

async sequential

Inherited from ​

Plugin.banner

closeBundle? ​

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

Defined in: node_modules/.pnpm/rolldown@1.2.15/node_modules/rolldown/dist/shared/define-config-BoIay7tU.d.mts:3208

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 ​

Plugin.closeBundle

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

Defined in: node_modules/.pnpm/rolldown@1.2.15/node_modules/rolldown/dist/shared/define-config-BoIay7tU.d.mts:3273

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

Kind ​

async sequential

Inherited from ​

Plugin.footer

generateBundle? ​

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

Defined in: node_modules/.pnpm/rolldown@1.2.15/node_modules/rolldown/dist/shared/define-config-BoIay7tU.d.mts:3183

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

Kind ​

async sequential

Inherited from ​

Plugin.generateBundle

intro? ​

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

Defined in: node_modules/.pnpm/rolldown@1.2.15/node_modules/rolldown/dist/shared/define-config-BoIay7tU.d.mts:3280

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

Kind ​

async sequential

Inherited from ​

Plugin.intro

outro? ​

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

Defined in: node_modules/.pnpm/rolldown@1.2.15/node_modules/rolldown/dist/shared/define-config-BoIay7tU.d.mts:3287

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

Kind ​

async sequential

Inherited from ​

Plugin.outro

renderChunk? ​

ts
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.15/node_modules/rolldown/dist/shared/define-config-BoIay7tU.d.mts:3137

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.

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 ​

Plugin.renderChunk

renderError? ​

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

Defined in: node_modules/.pnpm/rolldown@1.2.15/node_modules/rolldown/dist/shared/define-config-BoIay7tU.d.mts:3170

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

Kind ​

async parallel

Inherited from ​

Plugin.renderError

renderStart? ​

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

Defined in: node_modules/.pnpm/rolldown@1.2.15/node_modules/rolldown/dist/shared/define-config-BoIay7tU.d.mts:3123

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 and 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 ​

Plugin.renderStart

resolveFileUrl? ​

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

Defined in: node_modules/.pnpm/rolldown@1.2.15/node_modules/rolldown/dist/shared/define-config-BoIay7tU.d.mts:3158

Inherited from ​

Plugin.resolveFileUrl

writeBundle? ​

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

Defined in: node_modules/.pnpm/rolldown@1.2.15/node_modules/rolldown/dist/shared/define-config-BoIay7tU.d.mts:3191

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

Kind ​

async parallel

Inherited from ​

Plugin.writeBundle

Released under the MIT License.

Copyright © 2025-present VoidZero Inc. & Contributors