Notable Features

This page documents some notable features in Rolldown that do not have built-in equivalents in Rollup.

Platform presets

• Configurable via the platform option.
• Default: browser
• Possible values: browser | node | neutral

Similar to esbuild's platform option, this option provides some sensible defaults regarding module resolution and how to handle process.env.NODE_ENV.

Notable differences from esbuild:

• The default output format is always esm regardless of platform.
• No </script> escape behavior when platform is browser.

TIP

Rolldown does not polyfill Node built-ins when targeting the browser. You can opt-in to it with rolldown-plugin-node-polyfills.

Built-in transforms

Rolldown supports the following transforms out of the box, powered by Oxc:

• TypeScript
• JSX
  • Configurable via the jsx option, aligned with Rollup's jsx option
• Syntax lowering transforms ^WIP
  • Landing soon, configurable via the target option

ESM / CJS Interop

Rolldown handles mixed ESM / CJS module graphs out of the box, without the need for @rollup/plugin-commonjs. It largely follows esbuild's semantics and passes all esbuild ESM / CJS interop tests.

Module resolution

• Powered by oxc-resolver, aligned with webpack's enhanced-resolve

• node_modules resolution is enabled by default (equivalent of @rollup/plugin-node-resolve)

• tsconfig paths supported via resolve.tsconfigFilename.

• Configurable via the resolve option:

  interface InputOptions {
    resolve?: {
      alias?: Record<string, string[] | string>
      aliasFields?: string[][]
      conditionNames?: string[]
      extensionAlias?: Record<string, string[]>
      exportsFields?: string[][]
      extensions?: string[]
      mainFields?: string[]
      mainFiles?: string[]
      modules?: string[]
      symlinks?: boolean
      tsconfigFilename?: string
    }
  }

  When tsconfigFilename is provided, the resolver will respect compilerOptions.paths in the specified tsconfig.json.

Define

• Configurable via the define option.

This feature provides a way to replace global identifiers with constant expressions. Aligns with the respective options in Vite and esbuild.

Note it behaves differently from @rollup/plugin-replace as the replacement is AST-based, so the value to be replaced must be a valid identifier or member expression.

Inject

• Configurable via the inject option.

This is the feature equivalent of esbuild's inject option and @rollup/plugin-inject.

The API is aligned with @rollup/plugin-inject:

rolldown.config.js

export default {
  inject: {
    // import { Promise } from 'es6-promise'
    Promise: ['es6-promise', 'Promise'],

    // import { Promise as P } from 'es6-promise'
    P: ['es6-promise', 'Promise'],

    // import $ from 'jquery'
    $: 'jquery',

    // import * as fs from 'node:fs'
    fs: ['node:fs', '*'],

    // Inject shims for property access pattern
    'Object.assign': path.resolve('src/helpers/object-assign.js'),
  },
}

CSS bundling

• ⚠️ Experimental

Rolldown supports bundling CSS imported from JS out of the box. Note this feature currently does not support CSS Modules and minification.

Advanced Chunks

• ⚠️ Experimental
• Similar to webpack's optimization.splitChunks
• Configurable via output.advancedChunks:

interface OutputOptions {
  advancedChunks?: {
    minSize?: number
    minShareCount?: number
    groups?: {
      name: string
      test?: StringOrRegExp
      priority?: number
      minSize?: number
      minShareCount?: number
    }[]
  }
}

Module types

• ⚠️ Experimental

This is conceptually similar to esbuild's loader option, allowing users to globally associate file extensions to built-in module types via the moduleTypes option, or specify module type of a specific module in plugin hooks. It is discussed in more details here.

Minification

• ⚠️ WIP
• Configurable via the output.minify option.

This is powered by oxc-minifier, which is currently still work-in-progress. There is no configurability yet and the compression quality is not production ready. Expect improvements in the future!

For now, it is recommended to use an external minifier for production use cases. Rolldown is compatible with Rollup minifier plugins:

With rollup-plugin-esbuild:

rolldown.config.js

import { defineConfig } from 'rolldown'
import { minify } from 'rollup-plugin-esbuild'

export default defineConfig({
  plugins: [minify()],
})

With rollup-plugin-swc3:

rolldown.config.js

import { defineConfig } from 'rolldown'
import { minify } from 'rollup-plugin-swc3'

export default defineConfig({
  plugins: [
    minify({
      // swc's minify option here
      // mangle: {}
      // compress: {}
    }),
  ],
})