next-napi-bindings

Purpose

next-napi-bindings is the napi-rs layer that exposes Next.js's Rust pipeline to Node.js. The compiled output is the .node binary distributed under @next/swc-{platform} packages and loaded by packages/next/src/build/swc/.

Source: crates/next-napi-bindings/src/. The crate is small (~50 KB) because most logic lives in the underlying crates (next-api, next-core, next-custom-transforms); this crate is glue.

What it exposes

graph LR
    Node[Node.js next] --> Bindings[next-napi-bindings<br/>.node]
    Bindings --> Transform[transform()<br/>SWC compilation]
    Bindings --> Minify[minify()]
    Bindings --> Parse[parse()]
    Bindings --> Project[NextProject<br/>turbopack pipeline]
    Bindings --> Lockfile[lockfile probes]
    Bindings --> Mdx[mdx()<br/>Rust MDX]
    Bindings --> Css[css transforms]
    Bindings --> Rspack[rspack helpers]
    Bindings --> ReactCompiler[react_compiler]

File breakdown

File	What
crates/next-napi-bindings/src/lib.rs	napi entry; declares the public Rust functions
crates/next-napi-bindings/src/transform.rs	transform() — runs the full SWC pass chain
crates/next-napi-bindings/src/minify.rs	minify() — wrapper around swc_ecma_minifier
crates/next-napi-bindings/src/parse.rs	parse() — exposes the AST
crates/next-napi-bindings/src/turbopack.rs	Turbopack project + entrypoint plumbing
crates/next-napi-bindings/src/next_api/	Bindings for the Project API in crates/next-api
crates/next-napi-bindings/src/lockfile.rs	pnpm/yarn/npm lockfile probes
crates/next-napi-bindings/src/mdx.rs	Rust MDX compilation (mdxjs-rs)
crates/next-napi-bindings/src/css/	CSS transforms (lightningcss-style)
crates/next-napi-bindings/src/rspack.rs	rspack-specific helpers
crates/next-napi-bindings/src/react_compiler.rs	React Compiler invocation
crates/next-napi-bindings/src/turbo_trace_server.rs	Trace server (the trace UI consumes this)
crates/next-napi-bindings/src/code_frame.rs	Source-mapped code-frame error formatting

How JS calls a binding

// packages/next/src/build/swc/index.ts (simplified)
const bindings = require('@next/swc');

// Single-file SWC compile
const result = bindings.transform(code, {
  filename: 'app/page.tsx',
  jsc: {
    /* swc config */
  },
  module: { type: 'es6' },
  // ...next-specific opts
});

// Turbopack project
const project = bindings.createProject({
  rootDir,
  projectDir,
  config,
  jsConfig,
  env,
  // ...
});
const entries = await project.entrypoints();
for (const entry of entries.app) {
  await project.write(entry);
}

The bindings expose Rust types as napi-friendly JS objects. The bridge does conversion at the boundary (e.g., Rust Vec<u8> ↔ JS Buffer).

Loading the binary

The .node binary loads with native Node require(). The framework first tries the npm-published platform package (@next/swc-darwin-arm64, etc.), then falls back to a local build, then to the wasm version (from crates/wasm). The cascade is implemented in packages/next/src/build/swc/load.ts.

Errors

Errors that originate in Rust go through the napi error bridge with their full Error.cause chain. The code_frame.rs helper produces source-mapped frames that match what Node would format.

Build

cargo build --release -p next-napi-bindings
# or
pnpm swc-build-native

The pnpm swc-build-native script invokes scripts/build-native.ts, which runs cargo and then moves the resulting .node into packages/next-swc/native/.

Integration points

• Built and published as @next/swc-{platform} packages.
• Loaded by packages/next/src/build/swc/.
• Bridges every public method on crates/next-api and the SWC transforms in crates/next-custom-transforms.

Entry points for modification

• To add a new exposed function: declare it in lib.rs, implement under one of the existing modules.
• To wire a new Project method: add the napi binding in next_api/.
• To change error reporting: code_frame.rs.

Key source files

File	Purpose
crates/next-napi-bindings/src/lib.rs	Crate / napi entry
crates/next-napi-bindings/src/transform.rs	SWC compilation
crates/next-napi-bindings/src/turbopack.rs	Turbopack project surface
crates/next-napi-bindings/src/next_api/	Bindings for the Project API
crates/next-napi-bindings/src/code_frame.rs	Source-mapped code-frame errors
crates/next-napi-bindings/src/turbo_trace_server.rs	Build-trace inspection server
scripts/build-native.ts	The build script invoked by pnpm swc-build-native