rolldown

What it is

rolldown is a Rust rewrite of Rollup by the VoidZero / vitejs team — same Rollup-compatible plugin API and output formats, but the heavy lifting happens in native code with oxc as the parser. The stated goal is "drop-in Rollup replacement, ~10× faster" with eventual integration into Vite as the default bundler (replacing Rollup for prod builds and esbuild for dev pre-bundling).

rolldown is pre-1.0 as of writing. The API surface is converging on Rollup-compat, plugin compatibility is partial, and the package is published under rolldown on npm with frequent breaking releases. Vite is integrating it behind a flag and will eventually flip the default. For most users today, the right answer is "use Vite normally and let it adopt rolldown when ready"; for early adopters, the standalone CLI is usable for narrow scenarios but expect rough edges.

This page documents the surface as of the late 0.x / 1.0-RC line. Hedge heavily: APIs change between minor releases. Always check the current changelog before adopting.

Install

# Project-local (always pin a specific version — pre-1.0 means breakage)
npm install -D rolldown
pnpm add -D rolldown
yarn add -D rolldown

Output: rolldown CLI under node_modules/.bin/rolldown; ships pre-built Rust binaries per platform via optional deps (like esbuild).

# One-off
npx rolldown -c rolldown.config.js

Output:

created dist/bundle.js in 84ms

Versioning & Node support

• Currently a pre-1.0 0.x line — at time of writing the version is in the 0.13+ range and changing rapidly. A 1.0 release is on the roadmap but not yet shipped.
• Requires Node 18 or newer (matches Vite 5+).
• API treats 0.x like SemVer-major bumps — every minor can break.
• Always pin exact versions in lockfile. Don't use a caret range on a 0.x rolldown dep.
• Active development under the vitejs org — releases land weekly during major-feature phases.

Caveat: much of the surface below may shift before 1.0. Verify against rolldown.rs and the GitHub README before relying on any specific flag.

Package metadata

• Maintainers: Rolldown team / VoidZero (vitejs org)
• Project home: github.com/rolldown/rolldown
• Docs: rolldown.rs (early-stage, evolving)
• npm: npmjs.com/package/rolldown
• License: MIT
• First released: 2024
• Downloads: modest but growing; majority of installs are via Vite's experimental rolldown-vite package.

Peer dependencies & extras

rolldown has zero peers. The Rust binary is self-contained. Plugin compatibility:

• Rollup plugins — many work as-is; some require minor tweaks. The compatibility matrix is tracked in the rolldown repo.
• Native rolldown plugins — a new plugin format (with Rust+JS halves) is being designed for cases where JS plugin overhead is the bottleneck. Mostly internal for now.
• @rollup/plugin-* family — generally compatible. Specific plugins (commonjs, node-resolve, replace, terser) are tested in the rolldown CI.

Alternatives

Real-world recipes

Rollup-compatible config (basic library)

// rolldown.config.js
import { defineConfig } from "rolldown";

export default defineConfig({
  input: "src/index.ts",
  output: [
    { file: "dist/index.mjs", format: "esm" },
    { file: "dist/index.cjs", format: "cjs" },
  ],
  external: ["react"],
});

npx rolldown -c

Output:

[rolldown] src/index.ts → dist/index.mjs, dist/index.cjs
[rolldown] Done in 78ms

For simple library scenarios the config is identical to Rollup's. Where rolldown diverges, the diffs are usually flagged in the rolldown docs migration page.

Use under Vite (recommended path)

The future Vite default is rolldown. The migration is two install commands:

# Remove vite, add rolldown-vite (still pre-1.0)
npm uninstall vite
npm install -D rolldown-vite

Output:

removed 1 package in 1s
added 1 package in 3s

// vite.config.ts — same imports, same API
import { defineConfig } from "rolldown-vite";

export default defineConfig({
  plugins: [/* ... */],
});

npx vite build

Output:

vite v6.0.0-rolldown-experimental
✓ built in 1.2s   (vs ~4s under Rollup for the same project)

Caveat: rolldown-vite is experimental and the package name may change. As Vite officially adopts rolldown, expect the npm name to migrate back to vite. Watch the Vite release notes.

Plugin compatibility check

// Use Rollup-style plugins as-is — most work
import nodeResolve from "@rollup/plugin-node-resolve";
import commonjs from "@rollup/plugin-commonjs";
import typescript from "@rollup/plugin-typescript";

export default {
  input: "src/index.ts",
  output: { file: "dist/index.mjs", format: "esm" },
  plugins: [
    nodeResolve(),
    commonjs(),
    typescript(),
  ],
};

If a plugin fails: file an issue at github.com/rolldown/rolldown/issues. The team tracks plugin-compat regressions actively. Workaround: fall back to Rollup for that specific build.

Migration from Rollup

In most cases:

- import { defineConfig } from "rollup";
+ import { defineConfig } from "rolldown";

- "build": "rollup -c"
+ "build": "rolldown -c"

Then test. Common gotchas:

• Output sourcemap differences. rolldown's sourcemap format is @source-map v3 — same as Rollup but with subtle path-resolution differences. Some error trackers (Sentry, Datadog) need a re-upload.
• Plugin hooks not yet implemented. A handful of Rollup hooks (closeBundle, moduleParsed) are present but with different timing. Plugins that depend on precise hook order may fail.
• treeshake options. rolldown's tree-shaker is its own implementation; aggressive Rollup-specific options (moduleSideEffects: "no-external") behave slightly differently.

Production deployment

Production-grade use is currently limited to projects willing to track pre-1.0 churn. Recommendations:

1. Use under Vite, not standalone. The Vite team is responsible for stabilising the integration; standalone rolldown adoption is more brittle.
2. Pin exact version. No caret ranges on rolldown.
3. Keep Rollup as a fallback config. A rollup.config.js alongside rolldown.config.js lets you switch back instantly if a release breaks something.
4. Re-upload sourcemaps after each version bump. Format quirks change between minors.
5. Test the produced artefact byte-by-byte against Rollup output. Differences are expected; the question is whether they affect consumers. Use node-dir-compare or a build-comparison script.

For production-stable bundling today, use Rollup. Migrate to rolldown when Vite flips the default.

Performance tuning

rolldown is fast by default — the entire point. Knobs that matter:

Parallel modules

The Rust runtime parallelises module parsing automatically. No flag needed.

Minimise plugin overhead

JS plugins re-cross the FFI boundary per hook invocation — that's where rolldown can lose its speed advantage. Native rolldown plugins (Rust-side) bypass this; once published, prefer them where available.

Tree-shaking

treeshake: {
  moduleSideEffects: false,
  propertyReadSideEffects: false,
}

The same options as Rollup. rolldown's tree-shaker is being tuned — current builds may differ from Rollup's by a few bytes either way.

Sourcemap

output: { sourcemap: false }

Disable for max-speed CI builds; turn back on for local dev.

Version migration guide

Below the surface of rolldown's stability, every minor can break. The high-level arc:

For any specific rolldown version, the authoritative source is the rolldown changelog. Bumping rolldown should always be a deliberate test-pass, not an auto-update.

Security considerations

1. Pre-1.0 supply-chain risk. Frequent releases mean less time for security review. Pin and audit.
2. Platform binary install. Like esbuild, rolldown downloads platform-specific Rust binaries on install. Lockfile pins the binary version. If you build offline, stage the binary first.
3. Plugin trust boundary. Same as Rollup — JS plugins run with full Node privileges. Audit any community plugin.
4. Sourcemap path leaks. Default sourcemap behaviour includes absolute paths; same caveat as Rollup. Use output.sourcemapPathTransform.
5. Unstable API = unstable assumptions. Code that relies on undocumented rolldown behaviour will break across minors. Stick to the documented surface.

Testing & CI integration

# .github/workflows/ci.yml — rolldown experimental track
jobs:
  build-rolldown:
    runs-on: ubuntu-latest
    continue-on-error: true   # don't fail CI if rolldown breaks
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npx rolldown -c
      - run: node dist/index.mjs   # smoke test

A pattern many teams adopt: run rolldown as a side-by-side build alongside Rollup, compare output sizes and load behaviour, flip the default when the gap narrows.

Ecosystem integrations

• Vite is the primary consumer — rolldown-vite is the in-progress bundle. Eventual goal: vite package uses rolldown by default with no user-visible change.
• Astro, SvelteKit, Nuxt — all depend on Vite, so they inherit rolldown's adoption transparently when Vite flips.
• Rollup plugins — the @rollup/plugin-* family is the compatibility test bed. Custom community plugins vary.
• oxc — rolldown uses oxc as the parser. As oxc matures, rolldown inherits speed and correctness improvements.
• unbuild — has experimental rolldown support; not yet default.

Troubleshooting common errors

Plugin works in Rollup but fails in rolldown

Check the rolldown changelog for known incompatibilities. File an issue with a minimal repro — the maintainers are actively triaging plugin-compat reports.

Module not found for a path that resolves in Rollup

rolldown's resolver implementation is its own. Common issue: tsconfig.json paths resolution differs. Use @rollup/plugin-typescript (which handles paths via the TS compiler) until the rolldown native resolver supports them fully.

Slow first build, fast subsequent builds

rolldown caches parsed modules in memory. First build does the Rust-parser warm-up; subsequent builds in the same process are fast. CLI-style fresh invocations always pay the cold cost.

Output bytes differ from Rollup

Expected. rolldown's minifier and tree-shaker are independent implementations. Diff the output, verify equivalence with a smoke-test, and accept the new bytes if they pass.

Cannot find @rolldown/<platform>-<arch>

Platform optional dep didn't install. Fix:

npm install --include=optional
# or force-rebuild
npm rebuild rolldown

Output:

added 3 packages, and audited 87 packages in 1s

When NOT to use this

• Production builds today. rolldown is pre-1.0. For stable production use, stay on Rollup (or wait for Vite to flip the default).
• Maximum plugin compatibility. Some Rollup plugins haven't been tested against rolldown. If your build leans on exotic plugins, Rollup is safer.
• Library publishing that affects many consumers. Bundle output stability matters for libraries — wait until 1.0.
• Apps already using Vite. Don't manually switch to rolldown-vite unless you're an early adopter; let Vite flip the default when ready.
• CI pipelines that demand byte-stable artefacts. rolldown's output can shift between minors. Lock to one version if you need reproducibility.

See also

• Packages: npm-rollup — the predecessor
• Packages: npm-vite — the main consumer
• Packages: npm-esbuild — alternative speed tool
• Concept: HTTP — bundle delivery