Next.js

webDeveloper

Wire ScaleBun into the Next.js App Router — client bootstrap, automatic route tracking, error.tsx capture, and server, RSC and edge errors via instrumentation.ts.

Updated August 12, 2026Reviewed August 7, 2026

Install#

Terminal

npm i @scalebun/web @scalebun/web-next

Peers: next >=14, react >=18. The package re-exports everything from @scalebun/web-react, so you do not need both.

Setup#

One component, dropped straight into your root layout. It carries its own 'use client', so the layout stays a Server Component:

app/layout.tsxTSX

import { ScaleBunProvider } from '@scalebun/web-next';
export default function RootLayout({ children }: { children: React.ReactNode }) {  return (    <html>      <body>        <ScaleBunProvider          config={{            clientKey: process.env.NEXT_PUBLIC_SCALEBUN_CLIENT_KEY!,            apiBaseUrl: process.env.NEXT_PUBLIC_SCALEBUN_API_BASE_URL!,          }}        >          {children}        </ScaleBunProvider>      </body>    </html>  );}

That initializes the SDK, tracks routes, installs the render-error boundary and provides the in-app client. Same props as React minus routeName — which is automatic here — plus trackRoutes (default true).

The granular exports are all still available — initScaleBun, <ScaleBunNavigation /> and the React boundary — if you would rather assemble the pieces.

Client render errors#

Next's error.tsx convention is the error boundary — this is the one-liner that forwards it.

app/error.tsxTSX

'use client';import { reportNextError } from '@scalebun/web-next';
export default function Error({ error }: { error: Error }) {  reportNextError(error);  return <p>Something broke.</p>;}

Add app/global-error.tsx the same way to catch errors in the root layout.

Server, RSC and edge errors#

The browser SDK covers the browser. Everything that throws on the server — React Server Components, route handlers, server actions, SSR, middleware — is captured by a separate, dependency-free reporter.

instrumentation.tsTypeScript

export { register, onRequestError } from '@scalebun/web-next/server';

onRequestError fires for every server-side error on both the Node and edge runtimes. register() additionally installs process-level handlers on Node.

Configure it with server-only environment variables — never the NEXT_PUBLIC_ ones, which are shipped to the browser:

Variable	Purpose
`SCALEBUN_CLIENT_KEY`	Required.
`SCALEBUN_API_BASE_URL`	Required.
`SCALEBUN_RELEASE`	Optional; groups errors by release.
`SCALEBUN_ENV`	Optional; e.g. `production`.

Or set them in code when env vars are not an option:

instrumentation.tsTypeScript

import { configureServer } from '@scalebun/web-next/server';
configureServer({ clientKey: '…', apiBaseUrl: '…', release: '1.4.2' });export { register, onRequestError } from '@scalebun/web-next/server';

The reporter is a plain fetch POST: no session manager, no IndexedDB, no observers. It scrubs emails and secret-like tokens out of the message and stack, times out, and never throws into your response.

Everything else#

Feature flags, coachmarks, in-app slots and the error boundary all come from the React adapter and are re-exported here:

TSX

import { useFlag, ScaleBunErrorBoundary, ScaleBunAnchor } from '@scalebun/web-next';

See React for those, including the whenReady() pattern for component code that reaches for a feature controller.

Next#

SSR & edge runtimes — what runs where.
Privacy & consent — CSP for the Next dev overlay and CDN.