# Next.js

One install for error tracking across the browser, Server Components, route handlers, and server actions.


`@everock/next` connects your Next.js app to Everock. Install the browser and server entries to capture supported errors from client code, Server Components, route handlers, and server actions. Coverage depends on where those entries run and your capture settings.

## Prerequisites

- Next.js 15+ (App Router)
- React 18+, Node.js 20+


  You'll need a **surface public key** (`pk_…`) from your project's Keys tab. Set it as `EVEROCK_PUBLIC_KEY`. For source-map upload you'll also want a secret key (`ik_…`) as `EVEROCK_API_KEY` — server and CI only.


## Quick start



### Install the package

This adapter is available from the source checkout. Build its archive with `node scripts/pack-public-packages.mjs dist/npm 0.1.0-beta.1` at the repository root, then install the archive in your app using its actual path.

```bash
npm install /path/to/everock/dist/npm/everock-next-0.1.0-beta.1.tgz
```

### Wrap your Next.js config

Bakes your public key into the client bundle and lets the SDK transpile from source.

```ts title="next.config.ts" {6}
import { withEverock } from '@everock/next/config';
import type { NextConfig } from 'next';

const config: NextConfig = {};

export default withEverock(config);
```

### Wire server instrumentation

So server-side errors get captured too — Server Components, route handlers, actions.

```ts title="instrumentation.ts" {4}
import { init } from '@everock/next/server';

export function register() {
  init();
}

export { onRequestError } from '@everock/next/server';
```

### Mount the ingest route

The ingest route forwards browser telemetry through your own domain, reducing cross-origin setup. Network failures, blocking rules, proxy configuration, and deployment limits can still prevent delivery. The path must match your prefix (default `/api/everock`).

```ts title="app/api/everock/[[...path]]/route.ts"
export * from '@everock/next/route-handler';
```

### Add the provider

Starts the SDK in the browser. Wrap your app once, at the root layout.

```tsx title="app/layout.tsx" {7}
import { EverockProvider } from '@everock/next/provider';

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




  That's the whole install. Deploy, trigger an error, and it shows up in your dashboard within seconds — already grouped and triaged.


## Environment variables

```bash title=".env"
EVEROCK_PUBLIC_KEY=pk_your_key      # required — safe to expose
EVEROCK_API_KEY=ik_your_secret      # for source-map upload (server/CI only)
EVEROCK_ENVIRONMENT=production       # optional label
EVEROCK_ENDPOINT=https://collector.everock.example  # optional
```


  `EVEROCK_API_KEY` is a secret. Keep it in server and CI environments only. The public key is the only one that reaches the browser.


## Report a handled error

Everock captures uncaught errors for you. When you catch one yourself but still want it reported, call `capture` on the client or `captureError` on the server.

```tsx title="client component"
'use client';
import { useEverock } from '@everock/next/provider';

function SaveButton() {
  const { capture } = useEverock();
  async function onSave() {
    try {
      await saveDraft();
    } catch (error) {
      capture(error);
    }
  }
}
```

```ts title="server action"
import { captureError } from '@everock/next/server';

export async function placeOrder() {
  try {
    await chargeCard();
  } catch (error) {
    captureError(error);
    throw error;
  }
}
```

## Source maps

The configured Next.js build hook can register the release and upload emitted maps after a successful build. Provide `EVEROCK_API_KEY` only in the build/server environment and use the same release identity in the build and runtime. Do not add a second manual upload step unless you deliberately need a custom pipeline.

See [Source maps](/docs/features/source-maps) for the standalone uploader, asset URL matching, and symbolication limits.