Source Code Transformations
If a plugin transforms source code, it should generate a sourcemap automatically, unless there's a specific sourceMap: false option. For a map with one source, Rolldown only needs the mappings property: that source is the module itself, so Rolldown names it with the module id and fills a missing or empty sourcesContent with the code the hook received. magic-string provides a simple way to generate such a map for elementary transformations like adding or removing code snippets.
A map with more than one source keeps its own sources and sourcesContent, including '' and null entries. Rolldown fills missing, null, or empty content only for sources that name the module. A source names the module if it is the module id, or an absolute path that equals the id when both are normalized. A relative path names the module if it resolves to the normalized id from the module's directory and sourceRoot.
If it doesn't make sense to generate a sourcemap, return an empty sourcemap:
return {
code: transformedCode,
map: { mappings: '' },
};No output mapping then reaches the module's earlier code, so the output sourcemap leaves that code out of sources, sourcesContent and names.
If the transformation does not move code, you can preserve existing sourcemaps by returning null:
return {
code: transformedCode,
map: null,
};Transforming a Chunk
To transform a chunk, you can use renderChunk. If you return the sourcemap for the transform you applied, Rolldown composes that map with the previous transforms and rebuilds x_google_ignoreList field based on the options:
import MagicString from 'magic-string';
export default function myPlugin() {
return {
name: 'example',
renderChunk(code) {
const s = new MagicString(code);
s.prepend('/* banner */\n');
return { code: s.toString(), map: s.generateMap({ hires: 'boundary' }) };
},
};
}We discourage transforming in generateBundle. It runs after hashing, so the emitted filename keeps the hash of the untransformed code. It also runs after the .map asset is built, so editing chunk.map does not change that file. That said, if you have to transform there, compose the maps and write the asset yourself:
import remapping from '@jridgewell/remapping';
import MagicString from 'magic-string';
export default function myPlugin() {
return {
name: 'example',
generateBundle(options, bundle) {
for (const chunk of Object.values(bundle)) {
if (chunk.type !== 'chunk') continue;
const s = new MagicString(chunk.code);
// ...your transform...
if (!s.hasChanged()) continue;
// A low-resolution map can compose down to nothing, so keep the mappings at the boundaries.
const step = s.generateMap({ source: chunk.fileName, hires: 'boundary' });
chunk.code = s.toString();
if (chunk.map) {
// compose the sourcemap
chunk.map = remapping([step, chunk.map], () => null);
// The emitted file comes from this asset, not from `chunk.map`.
const asset = bundle[`${chunk.fileName}.map`];
if (asset) asset.source = chunk.map.toString();
}
}
},
};
}