react-vendoring_skill

Overview

This skill documents React vendoring and react-server layer boundaries for changes that touch vendored React, react-server-dom-webpack/*, or entry points like entry-base.ts. It explains the App Router vendoring channels, the strict entry-base.ts boundary, type declaration requirements, guarded runtime requires, and Turbopack remapping. Use it to avoid runtime failures and to keep runtime-only APIs and types correctly wired.

How this skill works

The App Router uses vendored React under packages/next/src/compiled/ with two channels (stable and experimental) chosen via build aliases. Only entry-base.ts is compiled into the react-server layer; all react-server-dom-webpack/* imports must be exposed through that module. Runtime-only Node APIs are conditionally required inside entry-base.ts behind env guards and then exposed through the ComponentMod parameter for other files to consume. Type declarations for vendored specifiers live in packages/next/types/$$compiled.internal.d.ts and must be updated when adding APIs.

When to use it

• Editing entry-base.ts or any file that touches react-server-dom-webpack APIs
• Adding or exposing node-only React APIs (e.g., stream APIs) to the server layer
• Updating or adding vendored React packages under packages/next/src/compiled/
• Modifying taskfile.js copy_vendor_react() or build aliases that choose stable/experimental channels
• Fixing runtime errors like 'The react-server condition must be enabled' in production workers

Best practices

• Keep all direct imports of react-server-dom-webpack/* inside entry-base.ts only
• Expose runtime-only APIs via guarded require() in entry-base.ts and forward via ComponentMod
• Add corresponding declare module blocks to $$compiled.internal.d.ts for any new specifier
• Scope ESLint import/no-extraneous-dependencies disables to the exact guarded require line
• Remember Turbopack remaps webpack specifiers to react-server-dom-turbopack at runtime

Example use cases

• Adding renderToPipeableStream: declare types, require it in entry-base.ts under an env guard, then call via ComponentMod
• Switching a page to experimental React channel: update makeAppAliases({ experimental }) and ensure compiled/react-experimental is populated
• Fixing a production worker crash by moving a direct react-server-dom-webpack import into entry-base.ts
• Adding a new vendored package: add files under compiled/, add declare module entries, and wire exports through entry-base.ts