react-vendoring

Name: react-vendoring
Author: vercel

141kstars31kforks

How to install react-vendoring?

vercel/next.js/react-vendoring

$npx -y skills add vercel/next.js --skill react-vendoring

Installs into the current project.

Summary

React vendoring and react-server layer boundaries. Use when editing entry-base.ts, $$compiled.internal.d.ts, compiled/react* packages, or taskfile.js copy_vendor_react. Covers the entry-base.ts boundary (all react-server-dom-webpack/* imports must go through it), vendored React c

Files · 1

View on GitHub

SKILL.md

1	# React Vendoring
2
3	Use this skill for changes touching vendored React, `react-server-dom-webpack/*`, or react-server layer boundaries.
4
5	## App Router Vendoring
6
7	React is NOT resolved from `node_modules` for App Router. It's vendored into `packages/next/src/compiled/` during `pnpm build` (task: `copy_vendor_react()` in `taskfile.js`). Pages Router resolves React from `node_modules` normally.
8
9	- Two channels: stable (`compiled/react/`) and experimental (`compiled/react-experimental/`). The runtime bundle webpack config aliases to the correct channel via `makeAppAliases({ experimental })`.
10
11	## `entry-base.ts` Boundary
12
13	Only `entry-base.ts` is compiled in rspack's `(react-server)` layer. ALL imports from `react-server-dom-webpack/*` (Flight server/static APIs) must go through `entry-base.ts`. Other files like `stream-ops.node.ts` or `app-render.tsx` must access Flight APIs via the `ComponentMod` parameter (which is the `entry-base.ts` module exposed through the `app-page.ts` build template).
14
15	Direct imports from `react-server-dom-webpack/server.node` or `react-server-dom-webpack/static` in files outside `entry-base.ts` will fail at runtime with "The react-server condition must be enabled". Dev mode may mask this error, but production workers fail immediately.
16
17	## Type Declarations
18
19	`packages/next/types/$$compiled.internal.d.ts` contains `declare module` blocks for vendored React packages. When adding new APIs (e.g. `renderToPipeableStream`, `prerenderToNodeStream`), you must add type declarations here. The bare specifier types (e.g. `declare module 'react-server-dom-webpack/server'`) are what source code in `src/` imports against.
20
21	## Adding Node.js-Only React APIs
22
23	These exist in `.node` builds but not in the type definitions. Steps:
24
25	1. Add type declarations to `$$compiled.internal.d.ts`.
26	2. Export the API from `entry-base.ts` behind a `process.env` guard.
27	3. Access it via `ComponentMod` in other files.
28
29	```typescript
30	// In entry-base.ts (react-server layer) only:
31	/* eslint-disable import/no-extraneous-dependencies */
32	export let renderToPipeableStream: ... \| undefined
33	if (process.env.__NEXT_USE_NODE_STREAMS) {
34	renderToPipeableStream = (
35	require('react-server-dom-webpack/server.node') as typeof import('react-server-dom-webpack/server.node')
36	).renderToPipeableStream
37	} else {
38	renderToPipeableStream = undefined
39	}
40	/* eslint-enable import/no-extraneous-dependencies */
41
42	// In other files, access via ComponentMod:
43	ComponentMod.renderToPipeableStream!(payload, clientModules, opts)
44	```
45
46	## ESLint Practical Rule
47
48	For guarded runtime `require()` blocks that need `import/no-extraneous-dependencies` suppression, prefer scoped block disable/enable. If using `eslint-disable-next-line`, the comment must be on the line immediately before the `require()` call, NOT before the `const` declaration. When the `const` and `require()` are on different lines, this is error-prone.
49
50	## Turbopack Remap
51
52	`react-server-dom-webpack/` is silently remapped to `react-server-dom-turbopack/` by Turbopack's import map. Code says "webpack" everywhere, but Turbopack gets its own bindings at runtime. This affects debugging: stack traces and error messages will reference the turbopack variant.
53
54	## Related Skills
55
56	- `$flags` - flag wiring (config/schema/define-env/runtime env)
57	- `$dce-edge` - DCE-safe require patterns and edge constraints
58	- `$runtime-debug` - reproduction and verification workflow

People who liked this also viewed

6 picks

Type

react-vendoring

141kstars31kforks

View on GitHub

How to install react-vendoring?

vercel/next.js/react-vendoring

$npx -y skills add vercel/next.js --skill react-vendoring

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# React Vendoring
2
3	Use this skill for changes touching vendored React, `react-server-dom-webpack/*`, or react-server layer boundaries.
4
5	## App Router Vendoring
6
7	React is NOT resolved from `node_modules` for App Router. It's vendored into `packages/next/src/compiled/` during `pnpm build` (task: `copy_vendor_react()` in `taskfile.js`). Pages Router resolves React from `node_modules` normally.
8
9	- Two channels: stable (`compiled/react/`) and experimental (`compiled/react-experimental/`). The runtime bundle webpack config aliases to the correct channel via `makeAppAliases({ experimental })`.
10
11	## `entry-base.ts` Boundary
12
13	Only `entry-base.ts` is compiled in rspack's `(react-server)` layer. ALL imports from `react-server-dom-webpack/*` (Flight server/static APIs) must go through `entry-base.ts`. Other files like `stream-ops.node.ts` or `app-render.tsx` must access Flight APIs via the `ComponentMod` parameter (which is the `entry-base.ts` module exposed through the `app-page.ts` build template).
14
15	Direct imports from `react-server-dom-webpack/server.node` or `react-server-dom-webpack/static` in files outside `entry-base.ts` will fail at runtime with "The react-server condition must be enabled". Dev mode may mask this error, but production workers fail immediately.
16
17	## Type Declarations
18
19	`packages/next/types/$$compiled.internal.d.ts` contains `declare module` blocks for vendored React packages. When adding new APIs (e.g. `renderToPipeableStream`, `prerenderToNodeStream`), you must add type declarations here. The bare specifier types (e.g. `declare module 'react-server-dom-webpack/server'`) are what source code in `src/` imports against.
20
21	## Adding Node.js-Only React APIs
22
23	These exist in `.node` builds but not in the type definitions. Steps:
24
25	1. Add type declarations to `$$compiled.internal.d.ts`.
26	2. Export the API from `entry-base.ts` behind a `process.env` guard.
27	3. Access it via `ComponentMod` in other files.
28
29	```typescript
30	// In entry-base.ts (react-server layer) only:
31	/* eslint-disable import/no-extraneous-dependencies */
32	export let renderToPipeableStream: ... \| undefined
33	if (process.env.__NEXT_USE_NODE_STREAMS) {
34	renderToPipeableStream = (
35	require('react-server-dom-webpack/server.node') as typeof import('react-server-dom-webpack/server.node')
36	).renderToPipeableStream
37	} else {
38	renderToPipeableStream = undefined
39	}
40	/* eslint-enable import/no-extraneous-dependencies */
41
42	// In other files, access via ComponentMod:
43	ComponentMod.renderToPipeableStream!(payload, clientModules, opts)
44	```
45
46	## ESLint Practical Rule
47
48	For guarded runtime `require()` blocks that need `import/no-extraneous-dependencies` suppression, prefer scoped block disable/enable. If using `eslint-disable-next-line`, the comment must be on the line immediately before the `require()` call, NOT before the `const` declaration. When the `const` and `require()` are on different lines, this is error-prone.
49
50	## Turbopack Remap
51
52	`react-server-dom-webpack/` is silently remapped to `react-server-dom-turbopack/` by Turbopack's import map. Code says "webpack" everywhere, but Turbopack gets its own bindings at runtime. This affects debugging: stack traces and error messages will reference the turbopack variant.
53
54	## Related Skills
55
56	- `$flags` - flag wiring (config/schema/define-env/runtime env)
57	- `$dce-edge` - DCE-safe require patterns and edge constraints
58	- `$runtime-debug` - reproduction and verification workflow

People who liked this also viewed

6 picks

Type