Next.js SDK

Use @squasher-ai/nextjs for errors on the server and @squasher-ai/browser for errors and Web Vitals in the browser. This page is tested with both packages at version 0.4.0 on Next.js 15.5 with the App Router.

What the SDK captures

Code	Captured
Route handlers	Yes, when you wrap them in `squasherApiHandler`.
Middleware	Yes, when you wrap it in `withSquasher` and it runs on Node.js.
Server Components and Server Actions	Only when you catch the error and call `captureError`.
Code on the Edge runtime	No. The SDK needs Node.js APIs.
Browser errors and React errors	Yes, with `@squasher-ai/browser` and `SquasherErrorBoundary`.
Web Vitals	Yes, with `SquasherNextWebVitals`: LCP, CLS, INP, FCP, and TTFB.

Install the SDKs

npm install @squasher-ai/nextjs @squasher-ai/browser

Add your ingest key and project ID to .env.local. The browser needs its own copies with the NEXT_PUBLIC_ prefix.

.env.local

SQUASHER_API_KEY=sq_pk_...
SQUASHER_PROJECT_ID=...
NEXT_PUBLIC_SQUASHER_API_KEY=sq_pk_...
NEXT_PUBLIC_SQUASHER_PROJECT_ID=...

To get both values, see Create an ingest key.

Initialize the SDK on the server

Create instrumentation.ts in your project root, or in src/ if you use a src folder. Load the SDK only when NEXT_RUNTIME is nodejs. Without this check, an app with Edge code does not build.

instrumentation.ts

export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    const { init } = await import("@squasher-ai/nextjs");
    init({
      apiKey: process.env.SQUASHER_API_KEY!,
      projectId: process.env.SQUASHER_PROJECT_ID!,
      environment: process.env.NODE_ENV,
      resourceAttributes: { "service.name": "storefront" },
    });
  }
}

resourceAttributes is optional. Set service.name when one project gets data from more than one service. On Next.js 14, also turn on experimental.instrumentationHook in next.config.js.

Capture route handler errors

Wrap each route handler in squasherApiHandler. When the handler throws, the wrapper sends the error with the request URL and method, then throws it again, so Next.js still returns its error response.

app/api/checkout/route.ts

import { squasherApiHandler } from "@squasher-ai/nextjs";

export const POST = squasherApiHandler(async (request) => {
  const cart = await request.json();
  const total = priceCart(cart); // If this throws, Squasher captures it.
  return Response.json({ total });
});

Capture middleware errors

Wrap the middleware in withSquasher, and run it on the Node.js runtime (Next.js 15.5 and later). Middleware on the Edge runtime is not captured.

middleware.ts

import { NextResponse } from "next/server";
import { withSquasher } from "@squasher-ai/nextjs";

export default withSquasher(async () => NextResponse.next());

export const config = { runtime: "nodejs" };

Capture Server Component errors

Squasher does not capture errors in Server Components and Server Actions on its own. Catch the error, call captureError, and throw it again:

app/orders/page.tsx

import { captureError } from "@squasher-ai/nextjs";

export default async function OrdersPage() {
  try {
    return <Orders orders={await loadOrders()} />;
  } catch (error) {
    await captureError(error as Error, { page: "orders" });
    throw error;
  }
}

The second argument is optional. It adds your own fields to the event.

Capture browser errors and Web Vitals

Use @squasher-ai/browser in client code. Do not use @squasher-ai/nextjs/client: it does not build in a client bundle today.

Create a client provider

app/squasher-provider.tsx

"use client";

import { useEffect, type ReactNode } from "react";
import { init } from "@squasher-ai/browser";
import { SquasherErrorBoundary } from "@squasher-ai/browser/react";
import { SquasherNextWebVitals } from "@squasher-ai/browser/next";

let started = false;

export function SquasherProvider({ children }: { children: ReactNode }) {
  useEffect(() => {
    if (started) return;
    started = true;
    init({
      apiKey: process.env.NEXT_PUBLIC_SQUASHER_API_KEY!,
      projectId: process.env.NEXT_PUBLIC_SQUASHER_PROJECT_ID!,
      environment: process.env.NODE_ENV,
      release: process.env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA,
    });
  }, []);
  return (
    <SquasherErrorBoundary fallback={<p>Something went wrong.</p>}>
      <SquasherNextWebVitals />
      {children}
    </SquasherErrorBoundary>
  );
}

Add the provider to the root layout

app/layout.tsx

import { SquasherProvider } from "./squasher-provider";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <SquasherProvider>{children}</SquasherProvider>
      </body>
    </html>
  );
}

The browser SDK captures uncaught errors and unhandled promise rejections. SquasherErrorBoundary captures React render errors and shows the fallback. SquasherNextWebVitals sends LCP, CLS, INP, FCP, and TTFB, each with the current pathname. Session replay is on by default. To turn it off, add replay: { enabled: false } to init. See the Browser SDK for all options.

Read stack traces

Server stack traces point at the compiled files in .next/server, and browser stack traces are minified. Upload source maps for each release, and the issue page shows the original files, lines, and functions.

Give the setup to a coding agent

Copy this prompt into your coding agent to install the SDK the same way:

Install @squasher-ai/nextjs and @squasher-ai/browser in this Next.js App Router project.
In instrumentation.ts, import and init @squasher-ai/nextjs only when process.env.NEXT_RUNTIME === "nodejs".
Wrap route handlers with squasherApiHandler. Wrap middleware with withSquasher only if it runs on the
Node.js runtime (export const config = { runtime: "nodejs" }). Nothing is captured on the Edge runtime.
In Server Components and Server Actions, catch the error, await captureError(error), and throw it again.
In client code, use init and SquasherErrorBoundary from @squasher-ai/browser (not @squasher-ai/nextjs/client).
Keep all keys in environment variables, run next build, and verify with one error from a route handler.

Next steps

Browser SDK

Set sampling, session replay, and privacy options.

Upload source maps

Store source maps for each release.

Vercel log drain

Send Vercel logs and traces to the same project.

Read AI triage

Learn what the triage summary tells you.

Get started

Guides

What the SDK captures

Install the SDKs

Initialize the SDK on the server

Capture route handler errors

Capture middleware errors

Capture Server Component errors

Capture browser errors and Web Vitals

Read stack traces

Give the setup to a coding agent

Next steps

Browser SDK

Upload source maps

Vercel log drain

Read AI triage

​What the SDK captures

​Install the SDKs

​Initialize the SDK on the server

​Capture route handler errors

​Capture middleware errors

​Capture Server Component errors

​Capture browser errors and Web Vitals

​Read stack traces

​Give the setup to a coding agent

​Next steps

Browser SDK

Upload source maps

Vercel log drain

Read AI triage

What the SDK captures

Install the SDKs

Initialize the SDK on the server

Capture route handler errors

Capture middleware errors

Capture Server Component errors

Capture browser errors and Web Vitals

Read stack traces

Give the setup to a coding agent

Next steps