@rolldown/debug
1.3.3 · 18 Nov 2026MIT312.2k / weekRepositoryHomepagenpmAtom feed
1.3.3 is the newest release of 1.x.
Summary· from the note as AI read it
Migration neededRead before upgrading: 7 changes to make.
Before you upgrade
- Don't force rolldown 1.3.0 into Vite 8.3.6 or earlier via overrides
- Update exports pointing at preserveModules files; non-JS extensions now kept
- Update exports paths, e.g. data.json.js instead of data.js
- Don't mix --input with positional entries in CLI calls
- Use only positional entries or only --input flags
- Check plugins handling external ids that now include an attributes query
- Builds now error if an id resolves as both external and non-external
New
- expose notify APIs
- Import attributes support (experimental)
- The same file imported with different attributes becomes different modules.
type: 'json','text'and'bytes'work without a plugin.- Plugins can read the attributes in
resolveId,loadandtransform, and change them inresolveId.
In short
7 breaking8 new14 fixed20 internal
- Breaking
[!WARNING] Vite users: Please do not force rolldown@1.3.0 into Vite with overrides or resolutions yet. Vite 8.3.6 and earlier need changes to work with it. Vite pins its rolldown version, so a normal install is not affected. Please wait for a Vite release that supports Rolldown 1.3.
- Breaking
preserveModulesfile names now follow Rollup - Breaking
[name]now keeps non-JS extensions, sodata.jsonbecomesdata.json.jsinstead ofdata.js, andComp.vuebecomesComp.vue.jsinstead ofComp.js. Libraries that pointexportsat the old file names need to update them. - Breaking
CLI:
--inputcannot be used together with positional entries - Breaking
rolldown 1.js --input 2.jsnow fails. Userolldown 1.js 2.jsorrolldown --input 1.js --input 2.js. - Breaking
Plugins now see such an external with the attributes in its id, for example
ext?attributes=%7B%22type%22%3A%22json%22%7Dinthis.getModuleIds(). - Breaking
error when one module id resolves as both external and non-external
Release note
The section about @rolldown/debug of a note shared by several packages.
Important
This is a minor release. It adds experimental support for import attributes, and some changes alter default behavior compared to 1.2.16. Please read Breaking changes before upgrading.
Warning
Vite users: Please do not force rolldown@1.3.0 into Vite with overrides or resolutions yet. Vite 8.3.6 and earlier need changes to work with it. Vite pins its rolldown version, so a normal install is not affected. Please wait for a Vite release that supports Rolldown 1.3.
Import attributes support (experimental)
Import attributes are the with { ... } part of an import. Node.js and browsers require them for JSON and CSS module scripts, so they are common in code written for these runtimes.
import config from './config.json' with { type: 'json' };
import shader from './shader.glsl' with { type: 'text' };
import wasm from './module.wasm' with { type: 'bytes' };With experimental.importAttributes:
The same file imported with different attributes becomes different modules.
type: 'json','text'and'bytes'work without a plugin.Plugins can read the attributes in
resolveId,loadandtransform, and change them inresolveId.
// rolldown.config.js
export default {
experimental: {
importAttributes: true,
},
};The design follows Rollup 5. The option is off by default, because it changes the id of modules imported with attributes, and plugins that use the id as a file path can break.
Rolldown's dev mode and Vite do not support it yet. See the Import Attributes guide for details and plugin migration.
Agent-friendly build report (experimental)
With devtools: { mode: 'report' }, Rolldown writes small Markdown and JSON files about each build to node_modules/.rolldown/report/. A coding agent can read the numbers directly, and does not need scripts to parse a large event log. People and CI can use them too.
// rolldown.config.js
export default {
devtools: { mode: 'report' },
};The report shows:
Packages: the largest packages, direct and transitive dependencies, and packages with more than one version.
See the Build Report guide for how to read each file and how to use the numbers in CI.
@rolldown/perf-kit (experimental)
@rolldown/perf-kit is a new package that consumes the data from devtools: { mode: 'report' } and adds its own measurements. An agent or a person can use the processed data to improve LCP, FCP and startup time. A fixed baseline and a check of the rendered output show which changes to keep.
npx @rolldown/perf-kit help
It measures 3 targets:
A page: LCP and FCP in a throttled browser (
scan). The build needs sourcemaps.A Node.js or Deno server: the time until the server is ready (
node-scan).A Cloudflare Worker: The time in global scope (
worker-scan).
See the Perf Kit guide for the agent prompts and more details.
We compared an agent alone with an agent using perf-kit on 3 open-source Cloudflare Workers. The prompts, results and steps to reproduce are in perf-kit-worker-startup.
Breaking changes
preserveModules file names now follow Rollup (#11410, #11413)
[name] now keeps non-JS extensions, so data.json becomes data.json.js instead of data.js, and Comp.vue becomes Comp.vue.js instead of Comp.js. Libraries that point exports at the old file names need to update them.
CLI: --input cannot be used together with positional entries (#11445)
rolldown 1.js --input 2.js now fails. Use rolldown 1.js 2.js or rolldown --input 1.js --input 2.js.
Notable fixes
External imports keep their attributes correctly (#11302, #11303)
This applies to every build, with or without experimental.importAttributes. Before, two imports of one external with different attributes became one module, and one import was lost. The legacy assert keyword was also copied to the output, which Node.js 22+ cannot load.
// input (`ext` is external)
import 'ext';
import 'ext' with { type: 'json' };
import data from 'ext2' assert { type: 'json' };
// 1.2.16 output
import 'ext' with { type: 'json' };
import data from 'ext2' assert { type: 'json' };
// 1.3.0 output, with a DEPRECATED_IMPORT_ASSERTION warning
import 'ext';
import 'ext' with { type: 'json' };
import data from 'ext2' with { type: 'json' };Plugins now see such an external with the attributes in its id, for example ext?attributes=%7B%22type%22%3A%22json%22%7D in this.getModuleIds().
Features
Expose notify APIs
Bug Fixes
Respect
NO_COLORin error and warning diagnosticsAvoid following output directory symlinks with
output.cleanDirEscape URL in sourceMappingURL
Error when one module id resolves as both external and non-external
Give module namespace objects a
nullprototype and make them non-extensibleDerive reference ids from stable seeds for deterministic builds
Avoid inferring constants from compound CommonJS exports
Don't inline a CommonJS export that is assigned conditionally or also through
module.exportsRespect
externalLiveBindingsfor star re-exports from externals in cjsDon't export JSON keys that the finalizer inlines away from a shared chunk
Handle nullish thrown values in error summary
Don't inline a
varthat module-level code reads before its declarationTreat a repeated
vardeclaration as a reassignment
A whole project to check? Paste its package.json in the dependency check: every deprecated, outdated or vulnerable dependency, with what to upgrade to. Free, no account.