| name | install-next |
| description | Installs and wires @rsc-boundary/next into a Next.js App Router app (dependencies, root layout provider, optional explicit markers). Use when the user wants to add RSC Boundary, integrate @rsc-boundary/next, or set up server/client boundary devtools in Next.js. The unscoped rsc-boundary package on npm is deprecated — see migration note. |
Install RSC Boundary in a Next.js app
Package: @rsc-boundary/next on npm. The unscoped rsc-boundary package on npm is deprecated — for new projects always install @rsc-boundary/next (it pulls in @rsc-boundary/core automatically).
Prerequisites
- Next.js 16+ with the App Router
- React 19+ and react-dom 19+ (peer dependencies)
If versions are older, say so and recommend upgrading before installing.
1. Install the dependency
Use the project's package manager:
pnpm add @rsc-boundary/next
npm install @rsc-boundary/next
yarn add @rsc-boundary/next
Migrating from rsc-boundary
If the user still has the deprecated unscoped rsc-boundary package installed, the migration is a one-liner:
pnpm remove rsc-boundary && pnpm add @rsc-boundary/next
Then replace the import everywhere (one global find-and-replace):
-import { ... } from "rsc-boundary";
+import { ... } from "@rsc-boundary/next";
The API surface is identical — no other code changes are needed.
Monorepo / local development
If the user is working inside this repository and consuming the package from the workspace, use the workspace protocol:
"@rsc-boundary/next": "workspace:*"
Ensure the packages are built (pnpm --filter @rsc-boundary/next build, which also builds core) before the app typechecks against dist/.
2. Wrap the App Router root layout
Edit app/layout.tsx (or the file that exports the root RootLayout for app/).
-
Import the provider:
import { RscBoundaryProvider } from "@rsc-boundary/next";
-
Wrap {children} (inside <body>) with <RscBoundaryProvider>{children}</RscBoundaryProvider>.
Preserve existing structure: fonts, metadata, other layout UI, and className on <body> / <html> stay as they are—only add the provider around the main content tree as appropriate.
Minimal pattern:
import { RscBoundaryProvider } from "@rsc-boundary/next";
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html lang="en">
<body>
<RscBoundaryProvider>{children}</RscBoundaryProvider>
</body>
</html>
);
}
If the app already wraps children in other providers, nest RscBoundaryProvider in a sensible place (often outermost inside <body> so the whole app is covered).
3. Behavior to set expectations
- Development: A small control (pill) appears; toggling it highlights client vs server regions. No changes are required in individual components for the default experience.
- Production: The provider is a no-op (children only). Devtools never mount in production builds; use static UI or screenshots if you need to illustrate boundaries on a deployed site.
4. Optional API (only if the user asks)
From @rsc-boundary/next the app can also use:
RscServerBoundaryMarker / SERVER_BOUNDARY_DATA_ATTR — explicit server region labelsRscDevtoolsNext — advanced mounting without the provider wrappercreateRscBoundaryProvider — factory for custom wiring (re-exported from @rsc-boundary/core)
Prefer RscBoundaryProvider unless the user's setup requires splitting these.
5. Verify
- Run
pnpm dev (or the app's dev script).
- Open the app in the browser; confirm the RSC Boundary control appears and toggling highlights boundaries.
- Run the project's typecheck/lint if available.
Troubleshooting (brief)
- Peer dependency warnings: Align
react and react-dom to ^19 with the app's Next.js version.
- Types / module not found: Ensure install completed and, for workspace usage, that packages are built.
- Nothing in production: Expected; devtools are development-only.
