Interface: TransformPluginContext
Extends
Properties
fs
- Type:
RolldownFsModule
Provides abstract access to the file system.
Inherited from
meta
- Type:
PluginContextMeta
An object containing potentially useful metadata.
Inherited from
Methods
getModuleInfo()
- Type: (
moduleId) =>ModuleInfo|null
Get additional information about the module in question.
During the build, this object represents currently available information about the module which may be inaccurate before the buildEnd hook:
idwill never change.code,exportsare only available after parsing, i.e. in themoduleParsedhook or after awaitingthis.load. At that point, they will no longer change.isEntryistrue, it will no longer change. It is however possible for modules to become entry points after they are parsed, either viathis.emitFileor because a plugin inspects a potential entry point viathis.loadin theresolveIdhook when resolving an entry point. Therefore, it is not recommended relying on this flag in thetransformhook. It will no longer change afterbuildEnd.importersanddynamicImporterswill start as empty arrays, which receive additional entries as new importers and are discovered. They will no longer change afterbuildEnd.importedIdsanddynamicallyImportedIdsare available when a module has been parsed and its dependencies have been resolved. This is the case in themoduleParsedhook or after awaitingthis.loadwith theresolveDependenciesflag. At that point, they will no longer change.metaandmoduleSideEffectscan be changed byloadandtransformhooks. Moreover, while most properties are read-only, these properties are writable and changes will be picked up if they occur before thebuildEndhook is triggered. meta itself should not be overwritten, but it is ok to mutate its properties at any time to store meta information about a module. The advantage of doing this instead of keeping state in a plugin is that meta is persisted to and restored from the cache if it is used, e.g. when using watch mode from the CLI.
Parameters
moduleId
string
Returns
ModuleInfo | null
Module information for that module. null if the module could not be found.
Inherited from
addWatchFile()
addWatchFile(
id):void
Adds additional files to be monitored in watch mode so that changes to these files will trigger rebuilds.
Note that when emitting assets that correspond to an existing file, it is recommended to set the originalFileName property in the this.emitFile call instead as that will not only watch the file but also make the connection transparent to other plugins.
Note: Usually in watch mode to improve rebuild speed, the transform hook will only be triggered for a given module if its contents actually changed. Using this.addWatchFile from within the transform hook will make sure the transform hook is also reevaluated for this module if the watched file changes.
In general, it is recommended to use this.addWatchFile from within the hook that depends on the watched file.
Parameters
id
string
The path to be monitored.
This can be an absolute path to a file or directory or a path relative to the current working directory.
Returns
void
Inherited from
emitFile()
emitFile(
file):string
Emits a new file that is included in the build output. You can emit chunks, prebuilt chunks or assets.
In-depth (type: 'chunk')
If the type is 'chunk', this emits a new chunk with the given module id as entry point. This will not result in duplicate modules in the graph, instead if necessary, existing chunks will be split or a facade chunk with reexports will be created. Chunks with a specified fileName will always generate separate chunks while other emitted chunks may be deduplicated with existing chunks even if the name does not match. If such a chunk is not deduplicated, the output.chunkFileNames pattern will be used.
You can reference the URL of an emitted file in any code returned by a load or transform plugin hook via import.meta.ROLLUP_FILE_URL_referenceId (returns a string). See File URLs for more details and an example.
You can use this.getFileName(referenceId) to determine the file name as soon as it is available. If the file name is not set explicitly, then:
- asset file names are available starting with the
renderStarthook. For assets that are emitted later, the file name will be available immediately after emitting the asset. - chunk file names that do not contain a hash are available as soon as chunks are created after the
renderStarthook. - if a chunk file name would contain a hash, using
getFileNamein any hook beforegenerateBundlewill return a name containing a placeholder instead of the actual name. If you use this file name or parts of it in a chunk you transform inrenderChunk, Rolldown will replace the placeholder with the actual hash beforegenerateBundle, making sure the hash reflects the actual content of the final generated chunk including all referenced file hashes.
In-depth (type: 'prebuilt-chunk')
If the type is 'prebuilt-chunk', this emits a chunk with fixed contents provided by the code property.
To reference a prebuilt chunk in imports, we need to mark the "module" as external in the resolveId hook as prebuilt chunks are not part of the module graph. Instead, they behave like assets with chunk meta-data:
function emitPrebuiltChunkPlugin() {
return {
name: 'emit-prebuilt-chunk',
resolveId: {
filter: { id: /^\.\/my-prebuilt-chunk\.js$/ },
handler(source) {
return {
id: source,
external: true,
};
},
},
buildStart() {
this.emitFile({
type: 'prebuilt-chunk',
fileName: 'my-prebuilt-chunk.js',
code: 'export const foo = "foo"',
exports: ['foo'],
});
},
};
}Then you can reference the prebuilt chunk in your code by import { foo } from './my-prebuilt-chunk.js';.
In-depth (type: 'asset')
If the type is 'asset', this emits an arbitrary new file with the given source as content. Assets with a specified fileName will always generate separate files while other emitted assets may be deduplicated with existing assets if they have the same source even if the name does not match. If an asset without a fileName is not deduplicated, the output.assetFileNames pattern will be used.
Parameters
file
EmittedAsset | EmittedChunk | EmittedPrebuiltChunk
Returns
string
A referenceId for the emitted file that can be used in various places to reference the emitted file.
Inherited from
getCombinedSourcemap()
getCombinedSourcemap():
SourceMap
Get the combined source maps of all previous plugins.
Returns
getFileName()
getFileName(
referenceId):string
Get the file name of a chunk or asset that has been emitted via this.emitFile.
Parameters
referenceId
string
Returns
string
The file name of the emitted file. Relative to output.dir.
Inherited from
getModuleIds()
getModuleIds():
IterableIterator<string>
Get all module ids in the current module graph.
Returns
IterableIterator<string>
An iterator of module ids. It can be iterated via
for (const moduleId of this.getModuleIds()) {
// ...
}or converted into an array via Array.from(this.getModuleIds()).
Inherited from
load()
load(
options):Promise<ModuleInfo>
Loads and parses the module corresponding to the given id, attaching additional meta information to the module if provided. This will trigger the same load, transform and moduleParsed hooks as if the module was imported by another module.
This allows you to inspect the final content of modules before deciding how to resolve them in the resolveId hook and e.g. resolve to a proxy module instead. If the module becomes part of the graph later, there is no additional overhead from using this context function as the module will not be parsed again. The signature allows you to directly pass the return value of this.resolve to this function as long as it is neither null nor external.
The returned Promise will resolve once the module has been fully transformed and parsed but before any imports have been resolved. That means that the resulting ModuleInfo will have empty importedIds and dynamicallyImportedIds. This helps to avoid deadlock situations when awaiting this.load in a resolveId hook. If you are interested in importedIds and dynamicallyImportedIds, you can either implement a moduleParsed hook or pass the resolveDependencies flag, which will make the Promise returned by this.load wait until all dependency ids have been resolved.
Note that with regard to the meta and moduleSideEffects options, the same restrictions apply as for the resolveId hook: Their values only have an effect if the module has not been loaded yet. Thus, it is very important to use this.resolve first to find out if any plugins want to set special values for these options in their resolveId hook, and pass these options on to this.load if appropriate. The example below showcases how this can be handled to add a proxy module for modules containing a special code comment. Note the special handling for re-exporting the default export:
export default function addProxyPlugin() {
return {
async resolveId(source, importer, options) {
if (importer?.endsWith('?proxy')) {
// Do not proxy ids used in proxies
return null;
}
// We make sure to pass on any resolveId options to
// this.resolve to get the module id
const resolution = await this.resolve(source, importer, options);
// We can only pre-load existing and non-external ids
if (resolution && !resolution.external) {
// we pass on the entire resolution information
const moduleInfo = await this.load(resolution);
if (moduleInfo.code.includes('/* use proxy */')) {
return `${resolution.id}?proxy`;
}
}
// As we already fully resolved the module, there is no reason
// to resolve it again
return resolution;
},
load: {
filter: { id: /\?proxy$/ },
handler(id) {
const importee = id.slice(0, -'?proxy'.length);
// Note that namespace reexports do not reexport default exports
let code =
`console.log('proxy for ${importee}'); ` + `export * from ${JSON.stringify(importee)};`;
// We know that while resolving the proxy, importee was
// already fully loaded and parsed, so we can rely on `exports`
if (this.getModuleInfo(importee).exports.includes('default')) {
code += `export { default } from ${JSON.stringify(importee)};`;
}
return code;
},
},
};
}If the module was already loaded, this.load will just wait for the parsing to complete and then return its module information. If the module was not yet imported by another module, it will not automatically trigger loading other modules imported by this module. Instead, static and dynamic dependencies will only be loaded once this module has actually been imported at least once.
Deadlocks caused by awaiting this.load in cyclic dependencies
While it is safe to use this.load in a resolveId hook, you should be very careful when awaiting it in a load or transform hook. If there are cyclic dependencies in the module graph, this can easily lead to a deadlock, so any plugin needs to manually take care to avoid waiting for this.load inside the load or transform of the any module that is in a cycle with the loaded module.
Parameters
options
{ id: string; resolveDependencies?: boolean; } & Partial<PartialNull<ModuleOptions>>
Returns
Promise<ModuleInfo>
Inherited from
parse()
parse(
input,options?):Program
Use Rolldown's internal parser to parse code to an ESTree-compatible AST.
Parameters
input
string
options?
ParserOptions | null
Returns
Program
Inherited from
resolve()
resolve(
source,importer?,options?):Promise<ResolvedId|null>
Resolve imports to module ids (i.e. file names) using the same plugins that Rolldown uses, and determine if an import should be external.
When calling this function from a resolveId hook, you should always check if it makes sense for you to pass along the options.
Parameters
source
string
importer?
string
options?
Returns
Promise<ResolvedId | null>
If Promise<null> is returned, the import could not be resolved by Rolldown or any plugin but was not explicitly marked as external by the user. If an absolute external id is returned that should remain absolute in the output either via the makeAbsoluteExternalsRelative option or by explicit plugin choice in the resolveId hook, external will be "absolute" instead of true.
Inherited from
Logging Methods
debug()
- Type: (
log,pos?) =>void
Same as PluginContext.debug, but a position param can be supplied.
Parameters
log
string | RolldownLog | () => string | RolldownLog
pos?
A character index or file location which will be used to augment the log with pos, loc and frame.
number | { column: number; line: number; }
Returns
void
Overrides
info()
- Type: (
log,pos?) =>void
Same as PluginContext.info, but a position param can be supplied.
Parameters
log
string | RolldownLog | () => string | RolldownLog
pos?
A character index or file location which will be used to augment the log with pos, loc and frame.
number | { column: number; line: number; }
Returns
void
Overrides
warn()
- Type: (
log,pos?) =>void
Same as PluginContext.warn, but a position param can be supplied.
Parameters
log
string | RolldownLog | () => string | RolldownLog
pos?
A character index or file location which will be used to augment the log with pos, loc and frame.
number | { column: number; line: number; }
Returns
void
Overrides
error()
error(
e,pos?):never
Same as PluginContext.error, but the id of the current module will also be added and a position param can be supplied.
Parameters
e
string | RolldownError
pos?
A character index or file location which will be used to augment the log with pos, loc and frame.
number | { column: number; line: number; }
Returns
never
Overrides
PluginContext.error