foxted/rsc-boundary/install-next

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/).

1. Import the provider:

``tsx import { RscBoundaryProvider } from "@rsc-boundary/next"; ``

1. 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 labels
• RscDevtoolsNext — advanced mounting without the provider wrapper
• createRscBoundaryProvider — 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.