@next/swc

The @next/swc is a binding that makes features written in Rust available to the JavaScript runtime. This binding contains not only Turbopack, but also other features needed by Next.js (SWC, LightningCSS, etc.).

Package hierarchies

The figure below shows the dependencies between packages at a high level.

flowchart TD
    C(next-custom-transforms) --> A(napi)
    C(next-custom-transforms) --> B(wasm)
    D(next-core) --> A(napi)
    E(next-build) --> A(napi)
    F(next-api) --> A(napi)
    C(next-custom-transforms) --> D
    D(next-core) --> F(next-api)
    D(next-core) --> E(next-build)

next-custom-transforms: provides next-swc specific SWC transform visitors. Turbopack, and the plain next-swc bindings (transform) use these transforms. Since this is a bottom package can be imported in any place (turbopack / next-swc / wasm), it is important package do not contain specific dependencies. For example, using Turbopack's VC in this package will cause build failures to wasm bindings.
next-core: Implements Turbopack features for the next.js core functionality. This is also the place where Turbopack-specific transform providers (implementing CustomTransformer) lives, which wraps swc's transformer in the next-custom-transforms.
next-api: Binding interface to the next.js provides a proper next.js functionality using next-core.
napi / wasm: The actual binding interfaces, napi for the node.js and wasm for the wasm. Note wasm bindings cannot import packages using turbopack's feature.

How to add new swc transforms

Implement a new visitor in next-custom-transforms. It is highly encouraged to use VisitMut instead of Fold for the performance reasons.
Implement a new CustomTransformer under packages/next-swc/crates/next-core/src/next_shared/transforms to make a Turbopack ecma transform plugin, then adjust corresponding rules in packages/next-swc/crates/next-core/src/(next_client|next_server)/context.rs.

napi bindings feature matrix

Due to platform differences napi bindings selectively enables supported features. See below tables for the currently enabled features.

arch\platform	Linux(gnu)	Linux(musl)	Darwin	Win32
ia32				a,b,d,e
x64	a,b,d,e,f	a,b,d,e,f	a,b,d,e,f	a,b,d,e,f
aarch64	a,d,e,f	a,d,e,f	a,b,d,e,f	a,b,c,e

a: turbo_tasks_malloc,
b: turbo_tasks_malloc_custom_allocator,
c: native-tls,
d: rustls-tls,
e: image-extended (webp)
f: plugin

Napi-rs

To generate bindings for the node.js, @next/swc relies on napi-rs. Check napi packages for the actual implementation.

Turbopack, turbopack-binding, and next-swc

Since Turbopack currently has features split across multiple packages and no official SDK, we've created a single entry point package, turbopack-binding, to use Turbopack features in next-swc. Turbopack-binding also reexports SWC, which helps to reduce the version difference between next-swc and turbopack. However, there are currently some places that use direct dependencies for macros and other issues.

Turbopack-binding is a package that is only responsible for simple reexports, allowing you to access each package by feature. The features currently in use in next-swc are roughly as follows.

SWC

__swc_core_binding_napi: Features for using napi with swc
__swc_core_serde: Serde serializable ast
__swc_core_binding_napi_plugin_*: swc wasm plugin support
__swc_transform_modularize_imports: Modularize imports custom transform
__swc_transform_relay: Relay custom transform
__swc_core_next_core: Features required for next-core package

Turbo

__turbo: Core feature to enable other turbo features.
__turbo_tasks_*: Features related to Turbo task.
__turbo_tasks_malloc_*: Custom memory allocator features.

Turbopack

__turbopack: Core feature to enable other turbopack features.
__turbopack_build: Implements functionality for production builds
__turbopack_cli_utils: Formatting utilities for building CLIs around turbopack
__turbopack_core: Implements most of Turbopack's core structs and functionality. Used by many Turbopack crates
__turbopack_dev: Implements development-time builds
__turbopack_ecmascript: Ecmascript parse, transform, analysis
__turbopack_ecmascript_plugin: Entrypoint for the custom swc transforms
__turbopack_ecmascript_hmr_protocol
__turbopack_ecmascript_runtime: Runtime code implementing chunk loading, hmr, etc.
__turbopack_env: Support for process.env and dotenv
__turbopack_static: Support for static assets
__turbopack_image_*: Native image decoding / encoding support. Some codecs have separate features (avif, etcs)
__turbopack_node: Evaluates JavaScript code from Rust via a Node.js process pool
__turbopack_trace_utils

Other features

__feature_auto_hash_map
__feature_node_file_trace: Node file trace
__feature_mdx_rs: Mdx compilation support

Keyboard shortcuts

Turbopack