Adapter implementation for immutable static assets
Adapters supporting immutable static assets must: (1) In modifyConfig, set config.supportsImmutableAssets to true during phase-production-build to signal support (default to true but allow users to opt-out). (2) In onBuildComplete, read outputs.staticFiles[].immutableHash to determine which static assets are immutable. Assets with immutableHash != null are immutable and must be requestable at output.pathname without the ?dpl query parameter. Assets without immutableHash are non-immutable static assets requested with the ?dpl query parameter scoped to the deployment.
Immutable static assets requested without ?dpl parameter
At runtime, immutable static assets are requested without the ?dpl query parameter and thus live in a shared namespace across deployments. They must be immutable and not changed even after a new deployment, or deleted as long as there are active deployments using them.
Immutable static assets adapter implementation example
/** @type {import('next').NextAdapter} */
const adapter = {
name: 'my-custom-adapter',
async modifyConfig(config, { phase }) {
if (phase === 'phase-production-build') {
config.supportsImmutableAssets =
// Default to true, but allow users to opt-out
config.supportsImmutableAssets ?? true
// Optionally, pass a salt for the content hashes
// config.outputHashSalt = getSaltForCurrentProject()
}
return config
},
async onBuildComplete({ outputs }) {
for (const output of outputs.staticFiles) {
if (output.immutableHash != null) {
// This has to be requestable at `output.pathname`
// even without the `?dpl` query parameter.
uploadOrVerifyImmutableStaticAsset(
output.filePath,
output.pathname,
output.immutableHash
)
} else {
// This is a non-immutable static asset and will be requested with
// the `?dpl` query parameter, scoped to the deployment.
uploadStaticAsset(output.filePath, output.pathname)
}
}
// Process other outputs....
},
}
Continue supporting non-immutable static assets in adapters
Adapters must continue supporting non-immutable static assets which may change between deployments and are requested with the ?dpl query parameter. This includes static assets from the public folder or from older Next.js versions.
outputs.staticFiles[].immutableHash property
The outputs.staticFiles[].immutableHash property contains the full content hash for immutable static assets. Next.js may use a truncated shorter content hash as the filename, so this property contains the full content hash which can be used to validate that no hash collision occurred.
edgeRuntime property for edge runtime routes
For any route output with runtime: 'edge', edgeRuntime is included and contains the canonical entry metadata for invoking that output in the edge runtime. edgeRuntime contains modulePath (absolute path to the module registered in the edge runtime), entryKey (canonical key used by the edge entry registry), and handlerExport (export name to invoke, currently 'handler'). The Edge Runtime is deprecated.
outputs.appPages structure for App Router pages
App Router page objects have type: 'APP_PAGE', id (route identifier), filePath (path to built file), pathname (URL pathname, includes .rsc suffix for RSC routes), sourcePage (original relative source file path), runtime ('nodejs' or 'edge'), assets (Record<string, string> of traced dependencies), wasmAssets (optional Record<string, string> of bundled wasm files), edgeRuntime (optional object with modulePath, entryKey, handlerExport), and config object containing maxDuration (optional), preferredRegion (deprecated, optional), env (edge runtime only, optional).
outputs object structure with arrays for each route type
The outputs object contains the following arrays: outputs.pages (React pages from pages/ directory), outputs.pagesApi (API routes from pages/api/), outputs.appPages (React pages from app/ directory), outputs.appRoutes (API and metadata routes from app/), outputs.prerenders (ISR-enabled routes and static prerenders), outputs.staticFiles (static assets and auto-statically optimized pages), and outputs.middleware (middleware function if present).
outputs behavior when config.output is set to 'export'
When config.output is set to 'export', only outputs.staticFiles is populated. All other arrays (pages, appPages, pagesApi, appRoutes, prerenders) will be empty since the entire application is exported as static files.
outputs.pages structure for Pages Router pages
Pages Router page objects have type: 'PAGES', id (route identifier), filePath (path to built file), pathname (URL pathname), sourcePage (original source file path in pages/ directory), runtime ('nodejs' or 'edge'), assets (Record<string, string> of traced dependencies with key as relative path from repo root and value as absolute path), wasmAssets (optional Record<string, string> of bundled wasm files), edgeRuntime (optional object with modulePath, entryKey, handlerExport), and config object containing maxDuration (maximum duration in seconds, optional), preferredRegion (string or string array, deprecated, optional), env (Record<string, string> for edge runtime only, optional).
outputs.pagesApi structure for API routes
Pages Router API route objects have type: 'PAGES_API', id (route identifier), filePath (path to built file), pathname (URL pathname), sourcePage (original relative source file path), runtime ('nodejs' or 'edge'), assets (Record<string, string> of traced dependencies), wasmAssets (optional Record<string, string> of bundled wasm files), edgeRuntime (optional object with modulePath, entryKey, handlerExport), and config object containing maxDuration (optional), preferredRegion (deprecated, optional), env (edge runtime only, optional).
outputs.appRoutes structure for API and metadata routes
App Router route objects have type: 'APP_ROUTE', id (route identifier), filePath (path to built file), pathname (URL pathname), sourcePage (original relative source file path), runtime ('nodejs' or 'edge'), assets (Record<string, string> of traced dependencies), wasmAssets (optional Record<string, string> of bundled wasm files), edgeRuntime (optional object with modulePath, entryKey, handlerExport), and config object containing maxDuration (optional), preferredRegion (deprecated, optional), env (edge runtime only, optional).
outputs.prerenders structure for ISR and static prerender routes
Prerender objects have type: 'PRERENDER', id (route identifier), pathname (URL pathname), parentOutputId (ID of the source page/route), groupId (number for revalidation group, prerenders with same groupId revalidate together), route (source route matcher with dynamic segments preserved, e.g. /blog/[slug]), routeType (optional 'route' | 'fallback' | 'shell' | 'page'), response (optional 'empty' | 'initial' | 'complete' describing completeness before request-time work), compute (optional 'blocking' | 'resuming' | 'static' describing request-time compute needed), htmlSize (optional byte size of prerendered App Router HTML shell), pprChain (optional object with headers Record<string, string>), parentFallbackMode (false | null | string), fallback (optional object with filePath, initialStatus, initialHeaders, initialExpiration, initialRevalidate, postponedState), and config object with allowQuery (optional string array), allowHeader (optional string array), bypassFor (optional RouteHas array), renderingMode (optional 'STATIC' | 'PARTIALLY_STATIC'), partialFallback (optional boolean), bypassToken (optional string).
Prerender routeType classification meanings
routeType identifies the kind of canonical response: 'route' is a non-UI route such as a Route Handler; 'page' is a page whose URL has no missing prerenderable parameters; 'shell' is the most specific reusable page shell for its class of URLs; 'fallback' is a reusable page response that can be specialized by filling more prerenderable parameters.
Prerender response classification meanings
response describes how complete the response is before request-time work: 'empty' means no initial page response can be served; 'initial' means an initial response can be served but it is not the completed page UI (applies to UI routes that are partially prerenderable); 'complete' means the response is complete (can include zero-byte response body like 204 Route Handler response).
Prerender compute classification meanings
compute describes the request-time compute needed to serve the completed response: 'blocking' means no initial response can be sent before request-time compute starts (once started, response can stream while compute continues); 'resuming' means an initial response is served while postponed work resumes on the server; 'static' means no server compute is required per request.
htmlSize property in prerender outputs
htmlSize is only included on the primary App Router HTML output in prerender objects. A value of 0 means the HTML shell is empty. Pages Router prerenders, Route Handlers, and related RSC, data, and segment outputs omit htmlSize.
Prerender field emissions on related outputs
routeType, response, and compute are emitted together on the primary response in a prerender group. Related RSC, data, and segment outputs omit these fields. Pages Router templates with fallback: false also omit them because those templates are never served for unmatched URLs.
outputs.staticFiles structure for static assets
Static file objects have type: 'STATIC_FILE', id (unique identifier), filePath (absolute filesystem path to built file), pathname (routable URL pathname), and immutableHash (optional, content hash when filename contains hash, indicating file is immutable).
outputs.middleware structure for middleware functions
Middleware objects have type: 'MIDDLEWARE', id (route identifier), filePath (path to built file), pathname (always '/_middleware'), sourcePage (always 'middleware'), runtime ('nodejs' or 'edge'), assets (Record<string, string> of traced dependencies), wasmAssets (optional Record<string, string> of bundled wasm files), edgeRuntime (optional object with modulePath, entryKey, handlerExport), and config object containing maxDuration (optional), preferredRegion (deprecated, optional), env (edge runtime only, optional), and matchers (optional array of objects with source, sourceRegex, has, missing).
Middleware matchers array structure
Middleware matchers array contains objects with source (source pattern), sourceRegex (compiled regex for matching requests), has (optional RouteHas array for positive matching conditions), and missing (optional RouteHas array for negative matching conditions).
next-rspack skill scope and limitations
The next-rspack skill applies to code and configuration under the rspack/ directory only. It covers upgrading @rspack/core npm package version, rspack crate dependency versions, Rust version in rspack/rust-toolchain.toml (rspack directory only), fixing Rspack-related compilation issues, and developing Rspack-specific features in Next.js. The rust-toolchain.toml in the repository root is for Turbopack and is outside the scope of this skill.
Rspack package structure and workspace organization
The rspack directory is an independent workspace with its own Cargo.toml, rust-toolchain.toml, and package.json. It contains lib/ with index.js (exports @rspack/core plus custom plugins) and index.d.ts (type definitions), and crates/binding/ with Cargo.toml (Rust crate dependencies) and package.json (@next/rspack-binding package definition). The rspack/ directory is separate from the root pnpm-workspace.
Rspack dependency chain from packages/next-rspack
packages/next-rspack depends on @next/rspack-core (rspack/package.json), which depends on @rspack/core (npm dependency) and @next/rspack-binding (rspack/crates/binding). The @next/rspack-binding in turn depends on rspack_* crates defined in Cargo.toml dependencies.
Rspack version mapping: npm to crate versions
The version mapping between @rspack/core npm versions and rspack crate versions follows this rule: npm major.minor maps to crate version 0.(major*50+minor). Examples: @rspack/core 2.0.0-rc.0 maps to rspack crate 0.100.0-rc.0; @rspack/core 1.3.x maps to rspack crate 0.53.x; @rspack/core 1.2.x maps to rspack crate 0.52.x.
Upgrading @rspack/core npm package
To upgrade @rspack/core, edit rspack/package.json and update the @rspack/core dependency version. The @next/rspack-binding dependency should remain as workspace:* in the same file.
Upgrading rspack crate versions in Cargo.toml
When upgrading rspack crates, edit rspack/crates/binding/Cargo.toml and update all rspack crate versions using exact pinning (=<version>). The crates to update include: rspack_binding_builder, rspack_binding_builder_macros, rspack_core, rspack_error, rspack_hook, rspack_plugin_externals, rspack_regex, rspack_binding_builder (in target-specific dependencies with plugin feature), and rspack_binding_build (in build-dependencies). Note that rspack_sources version is managed separately and may not follow the main version.
Upgrading Rust toolchain for rspack
Edit rspack/rust-toolchain.toml to update the Rust nightly version. The file should contain: [toolchain] section with profile = "default", components = ["rust-src"], and channel = "<nightly version matching upstream rspack>". This applies only to rspack/rust-toolchain.toml, not the root repository rust-toolchain.toml.
Building and verifying Rspack changes
To verify Rspack changes, execute from the rspack directory: run cargo check to check Rust code, then run pnpm build to build the binding (requires Rust installed).
Linking @next/rspack-core to packages/next-rspack
The rspack/ directory is an independent workspace not included in the root pnpm-workspace, so manual linking is required. Execute from the repository root: cd packages/next-rspack, then run pnpm link ../../rspack to link locally built @next/rspack-core. Alternatively, modify packages/next-rspack/package.json to use "@next/rspack-core": "link:../../rspack" for local testing only (do not commit this change). After linking, run pnpm install from the root directory to update dependency relationships.
Files to modify during Rspack upgrade
During a Rspack upgrade, check and modify these files: rspack/package.json (update @rspack/core version and package version), rspack/crates/binding/Cargo.toml (update rspack_* crate versions), rspack/crates/binding/package.json (update binding package version), rspack/rust-toolchain.toml (update Rust nightly version), and packages/next-rspack/package.json (update @next/rspack-core version reference on release; use link for local testing).
Pre-requisites for local Rspack testing
Before running pnpm test-rspack, you must build and link @next/rspack-core: (1) cd rspack, run pnpm install, then pnpm build; (2) cd ../packages/next-rspack, run pnpm link ../../rspack; (3) cd back to root and run pnpm install; (4) run pnpm test-rspack. After modifying Rust code under rspack/, you need to re-run pnpm build from step 1.
Rspack test commands and environment variables
Test commands for Rspack: pnpm test-rspack runs the full test suite (using Rspack compiler), pnpm test-dev-rspack runs development mode tests, pnpm test-start-rspack runs production mode tests, and pnpm run with-rspack pnpm testonly -- <test-pattern> runs specific tests. All test commands set environment variables via with-rspack: cross-env NEXT_RSPACK=1 NEXT_TEST_USE_RSPACK=1.
Using NEXT_RSPACK environment variable for compiler differentiation
Use the NEXT_RSPACK environment variable to differentiate between compilers in packages/next/ code. Check with Boolean(process.env.NEXT_RSPACK) or if (process.env.NEXT_RSPACK) to execute Rspack-specific logic, with webpack logic in the else branch.
Common Rspack code locations in Next.js
Compiler selection logic is in packages/next/src/lib/bundler.ts. Webpack configuration is in packages/next/src/build/webpack-config.ts. Loader adaptations are in packages/next/src/build/webpack/loaders/.
@next/rspack-core exports @rspack/core plus custom plugins
@next/rspack-core exports @rspack/core plus custom plugins. The custom plugin NextExternalsPlugin is for externals handling and is implemented in Rust.
Rspack release process via GitHub Actions
Rspack packages are released via the GitHub Actions workflow at .github/workflows/release-next-rspack.yml. The workflow supports dry-run mode and supports multiple npm tags (latest, alpha, beta, canary).