ContextQMD
Back to Rolldown

Native MagicString Example

examples/native-magic-string/README.md

0.15.12.8 KB
Original Source

Native MagicString Example

This example demonstrates the use of experimental.nativeMagicString in Rolldown.

What is nativeMagicString?

The nativeMagicString option enables a native Rust implementation of MagicString for source map generation and code transformation. This provides significant performance improvements over the JavaScript implementation, especially for large codebases.

Key Features

  • Better Performance: Native Rust implementation is faster than JavaScript
  • Background Processing: Source map generation happens asynchronously in a background thread
  • Seamless Integration: Works with existing plugins that use the MagicString API

How It Works

When experimental.nativeMagicString is enabled:

  1. Rolldown provides a magicString object in the meta parameter of transform hooks
  2. Plugins can use this object to manipulate code (replace, prepend, append, etc.)
  3. Source maps are automatically generated from the transformations
  4. The native implementation handles the heavy lifting in a background thread

Running This Example

bash
npm run build

This will:

  1. Bundle the source files
  2. Apply transformations using the native MagicString implementation
  3. Generate source maps
  4. Output the bundled code to the dist/ directory

What the Plugins Do

The example includes two plugins demonstrating different use cases:

Plugin 1: example-transform (MagicString only)

Demonstrates basic MagicString operations:

  1. Replace: Changes "Hello" to "Hi" in the code
  2. Prepend: Adds a comment at the beginning of each file
  3. Append: Adds a timestamp comment at the end of each file

Plugin 2: ast-magicstring-example (AST + MagicString)

Demonstrates combining meta.ast and meta.magicString for code transformation:

  • Analyzes code structure using the parsed AST (Abstract Syntax Tree) generated by oxc parser.
  • Transforms patterns transform fn(() => import(url)) into fn(() => import(url), url) with native magicString
  • Shows how to:
    • Use meta.ast to find specific code patterns
    • Use meta.magicString to modify code at precise locations
    • Maintain accurate source maps during transformation

Example transformation in lazy-loader.js:

js
// Before:
registerLazyModule(() => import('./greet.js'));

// After:
registerLazyModule(() => import('./greet.js'), './greet.js');

All transformations maintain accurate source maps thanks to the native MagicString implementation.

Configuration

js
export default defineConfig({
  experimental: {
    nativeMagicString: true, // Enable native Rust implementation
  },
  output: {
    sourcemap: true, // Enable source map generation
  },
});

Learn More