building/build-process

105 notes in this subject, read out of this brain and free to use. This is page 2 of 2.

React 19.2 features in Next.js 16 App Router

The App Router in Next.js 16 uses React 19.2 with new features including View Transitions (animate elements that update inside a Transition or navigation), useEffectEvent (extract non-reactive logic from Effects into reusable Effect Event functions), and Activity (render 'background activity' by hiding UI with display: none while maintaining state and cleaning up Effects).

React Compiler now stable in Next.js 16

Built-in support for the React Compiler is now stable in Next.js 16 following React Compiler's 1.0 release. The reactCompiler configuration option has been promoted from experimental to stable. It is not enabled by default. To enable it, set reactCompiler: true in next.config.ts. Install the latest version of babel-plugin-react-compiler. Expect higher compile times in development and during builds when enabling this option.

Local images with query strings require configuration in Next.js 16

Local image sources with query strings now require images.localPatterns.search configuration to prevent enumeration attacks. Example: images: { localPatterns: [{ pathname: '/assets/**', search: '?v=1' }] }

images.minimumCacheTTL default changed from 60 seconds to 4 hours

The default value for images.minimumCacheTTL has changed from 60 seconds to 4 hours (14400 seconds). This reduces revalidation cost for images without cache-control headers. If you need the previous behavior, set images.minimumCacheTTL to 60.

images.imageSizes default removed value 16 in Next.js 16

The value 16 has been removed from the default images.imageSizes array. This reduces the size of the srcset attribute shipped to the browser. If you need to support 16px images, set images.imageSizes to [16, 32, 48, 64, 96, 128, 256, 384].

TypeScript 5.1.0 minimum in Next.js 16

Next.js 16 requires TypeScript 5.1.0 as the minimum version.

Local IP restriction for image optimization in Next.js 16

A new security restriction blocks local IP optimization by default. Set images.dangerouslyAllowLocalIP to true only for private networks. This might be necessary when hosting Next.js in a VPC with split-horizon DNS, but only enable once you understand the SSRF risk.

images.maximumRedirects default changed from unlimited to 3 in Next.js 16

The default for images.maximumRedirects has changed from unlimited to 3 redirects maximum. Set it to 0 to disable redirects or increase it like 5 for edge cases.

next/legacy/image component is deprecated in Next.js 16

The next/legacy/image component is deprecated. Use next/image instead. Change from: import Image from 'next/legacy/image' to: import Image from 'next/image'

images.domains configuration deprecated in Next.js 16

The images.domains config is deprecated. Use images.remotePatterns instead for improved security. Change from: { images: { domains: ['example.com'] } } to: { images: { remotePatterns: [{ protocol: 'https', hostname: 'example.com' }] } }

Concurrent dev and build with separate output directories in Next.js 16

Next.js 16 enables concurrent execution of 'next dev' and 'next build' by using separate output directories. The 'next dev' command outputs to .next/dev instead of .next. A lockfile mechanism prevents multiple 'next dev' or 'next build' instances on the same project.

ESLint Flat Config default in Next.js 16

@next/eslint-plugin-next now defaults to ESLint Flat Config format, aligning with ESLint v10 which drops legacy config support. If using legacy .eslintrc format, consider migrating to flat config format per ESLint migration guide.

Scroll behavior override changed in Next.js 16

In previous Next.js versions, if 'scroll-behavior: smooth' was set globally on html element, Next.js would override it during SPA route transitions. In Next.js 16, Next.js no longer overrides your scroll-behavior setting by default. If you want Next.js to perform the override (previous default behavior), add the 'data-scroll-behavior="smooth"' attribute to your html element.

Size and First Load JS metrics removed from next build output

Next.js 16 removes the 'size' and 'First Load JS' metrics from the 'next build' output. These metrics were found to be inaccurate in server-driven architectures using React Server Components. The most effective way to measure route performance is through tools like Chrome Lighthouse or Vercel Analytics, which focus on Core Web Vitals and downloaded resource sizes.

next dev config load optimization in Next.js 16

In Next.js 16, the Next config file is loaded only once when running 'next dev' command, not twice as in previous versions. A consequence is that checking if 'process.argv' includes 'dev' in your Next.js config file will return false. The typegen and build commands are still visible in process.argv. This is important for plugins that trigger side-effects on 'next dev'; check if NODE_ENV is set to 'development' instead, or use the phase in which configuration is loaded.

Build Adapters API alpha in Next.js 16

Following the Build Adapters RFC, the first alpha version of the Build Adapters API is now available. Build Adapters allow creating custom adapters that hook into the build process, enabling deployment platforms and custom build integrations to modify Next.js configuration or process build output. Use: experimental: { adapterPath: require.resolve('./my-adapter.js') }. The adapterPath was promoted to stable, top-level option in 16.2.0.

Modern Sass API with sass-loader v16 in Next.js 16

sass-loader has been bumped to v16 in Next.js 16, which supports modern Sass syntax and new features.

AMP support removed in Next.js 16

All AMP APIs and configurations have been removed from Next.js 16 due to declining AMP adoption. Removed features include: 'amp' configuration from next config, 'next/amp' hook imports and usage (useAmp), and 'export const config = { amp: true }' from pages. Evaluate if AMP is still necessary; most performance benefits can now be achieved through Next.js's built-in optimizations and modern web standards.

next lint command removed in Next.js 16

The 'next lint' command has been removed in Next.js 16. Use Biome or ESLint directly. 'next build' no longer runs linting. The 'eslint' option in the Next.js config file is also removed. A codemod is available: 'npx @next/codemod@canary next-lint-to-eslint-cli .'

serverRuntimeConfig and publicRuntimeConfig removed in Next.js 16

serverRuntimeConfig and publicRuntimeConfig have been removed in Next.js 16. Use environment variables instead. For server-only values, access environment variables directly in Server Components. For client-accessible values, use the NEXT_PUBLIC_ prefix. To ensure environment variables are read at runtime, use the connection() function before reading from process.env.

connection() function for runtime environment variable access

To ensure environment variables are read at runtime (not bundled at build time), use the connection() function from 'next/server' before reading from process.env. Example: import { connection } from 'next/server'; export default async function Page() { await connection(); const config = process.env.RUNTIME_CONFIG; return <p>{config}</p>; }

devIndicators options removed in Next.js 16

The following options have been removed from devIndicators in Next.js 16: appIsrStatus, buildActivity, buildActivityPosition. The indicator itself remains available.

unstable_rootParams removed in Next.js 16

The unstable_rootParams function has been removed in Next.js 16. Use 'next/root-params' instead.

Codemod to update packages for Next.js 16 upgrade

To upgrade to Next.js 16, use the upgrade codemod: 'npx @next/codemod@canary upgrade latest'. The codemod can: update next.config.js to use the new turbopack configuration, migrate from 'next lint' to ESLint CLI, migrate from deprecated 'middleware' convention to 'proxy', remove 'unstable_' prefix from stabilized APIs, and remove 'experimental_ppr' Route Segment Config from pages and layouts.

Async Request APIs codemod for Next.js 16

If your app still uses synchronous params, searchParams, cookies(), headers(), or draftMode() from the Next.js 15 compatibility period, also run the async Request APIs codemod: 'npx @next/codemod@canary next-async-request-api .'

Verify rspack build process

To verify a build, execute cargo check in the rspack directory to check Rust code, then run pnpm build to build the binding.

next-rspack skill applies only to rspack/ directory

The next-rspack skill applies to code and configuration under the rspack/ directory. The rust-toolchain.toml in the repository root is for Turbopack and is outside the scope of this skill.

rspack workspace structure

The rspack directory is an independent workspace containing: Cargo.toml (Rust workspace configuration), rust-toolchain.toml (Rust version configuration), package.json (@next/rspack-core package definition), lib/ directory with index.js exporting @rspack/core and custom plugins, and crates/binding/ with Cargo.toml (rspack crate dependencies) and package.json (@next/rspack-binding package definition).

rspack dependency graph

packages/next-rspack depends on @next/rspack-core (from rspack/package.json), which depends on @rspack/core npm package and @next/rspack-binding (from rspack/crates/binding), which in turn depends on rspack_* crates defined in Cargo.toml.

rspack version mapping rules

The version mapping between @rspack/core npm version and rspack crate version follows these rules: @rspack/core 2.0.0-rc.0 maps to crate version 0.100.0-rc.0 (npm major.minor maps to crate 0.(major*50+minor)); @rspack/core 1.3.x maps to crate 0.53.x; @rspack/core 1.2.x maps to crate 0.52.x.

rspack package.json upgrade format

When upgrading rspack/package.json, update the dependencies field with @rspack/core set to the new version and @next/rspack-binding set to workspace:*.

rspack Cargo.toml crates to update

When upgrading rspack/crates/binding/Cargo.toml, update all rspack crate versions: rspack_binding_builder, rspack_binding_builder_macros, rspack_core, rspack_error, rspack_hook, rspack_plugin_externals, rspack_regex in dependencies section; rspack_binding_builder with features ["plugin"] in target-specific dependencies; rspack_binding_build in build-dependencies. The rspack_sources version is managed separately and may not follow the main version.

rspack rust-toolchain.toml format

When upgrading rspack/rust-toolchain.toml, set the profile to default, include rust-src in components, and set the channel to the nightly version matching upstream rspack.

rspack manual linking to packages/next-rspack

The rspack/ directory is an independent workspace not included in the root pnpm-workspace, so manual linking is required. Link locally built @next/rspack-core by executing pnpm link ../../rspack from packages/next-rspack directory. Alternatively, modify packages/next-rspack/package.json to use "@next/rspack-core": "link:../../rspack" for local testing only (do not commit). After linking, run pnpm install in the root directory to update dependency relationships.

Files to check during rspack upgrade

During rspack upgrade, check and modify: rspack/package.json (@rspack/core version and package version), rspack/crates/binding/Cargo.toml (rspack_* crate versions), rspack/crates/binding/package.json (binding package version), rspack/rust-toolchain.toml (Rust nightly version), packages/next-rspack/package.json (@next/rspack-core version reference, use link for local testing).

NEXT_RSPACK environment variable usage

Use the NEXT_RSPACK environment variable to differentiate compilers in packages/next/ code. Check process.env.NEXT_RSPACK to determine if using Rspack, and conditionally execute Rspack-specific logic versus Webpack logic.

Common rspack code locations

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

@next/rspack-core exports @rspack/core plus custom plugins. The NextExternalsPlugin is a custom plugin for externals handling implemented in Rust.

Bundler: Turbopack default in Next.js dev

Next.js now defaults to Turbopack for faster local development when running next dev. To use Webpack instead (similar to CRA), run next dev --webpack. Custom webpack configuration can still be provided if needed.

next-build-test binary purpose

The next-build-test binary lets you sidestep node bundling and run a turbo build against a raw rust binary. It does not do everything nextjs does, but it is an approximation for testing builds.

next-build-test requires project_options file

To use next-build-test, you need a project_options file that points to a nextjs repo with its dependencies installed. The project_options file requires fs-specific paths and env vars, so it cannot be bundled in the repo and must be generated or created manually.

next-build-test generate command

You can run 'cargo run -- generate /path/to/project > project_options.json' to generate a project_options file automatically.

next-build-test run command flags

The run command supports 4 flags: 'strategy' (can be sequential, concurrent, or parallel, defines how work is structured), 'factor' (defines how many pages should be built at once, defaults to num_cpus), 'limit' (defines the highest number of pages to build with deterministic shuffling, defaults to 1 page), and 'pages' (a comma separated list of routes to run in the order specified).

Two-pass build process for error codes

The build process uses two passes: First pass extracts new errors and temporarily stores them in packages/next/.errors/*.json; in CI, a build with new errors will fail. Second pass updates packages/next/errors.json and reruns the build step to confirm no further new errors are introduced. The two-pass system ensures reliable ordering of inserted error codes during concurrent builds.

WASM rebuild required after plugin modification

After modifying the error code SWC plugin, rebuild the WASM file via 'pnpm build-error-code-plugin' and commit it to the repository. Pre-built artifacts simplify the build process so 'pnpm build' runs without requiring 'cargo'.

Give your agent this brain