> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Next.js

> Next.js setup and configuration for ClickHouse Observability and self-managed deployments.

Choose the server-side instrumentation for your Next.js deployment:

* **Self-hosted, Node.js runtime:** use the ClickStack Node.js SDK.
* **Vercel or the Edge runtime:** use `@vercel/otel`.

For browser telemetry and session replay, use the [Browser SDK guide](https://clickhouse.com/docs/clickstack/observability/ingesting-data/sdks/browser.md).

This guide integrates:

## Self-hosted Next.js

Use Node.js 22.15 or later and install the SDK:

```shell theme={null}
npm install @clickhouse/clickstack-node
```

Create `instrumentation.ts` in your project root, or in `src` if your application uses that directory. Initialize the SDK only in the Node.js runtime:

```typescript theme={null}
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const { init } = await import('@clickhouse/clickstack-node');
    init();
  }
}
```

Add the SDK to `serverExternalPackages` in your existing Next.js configuration so it is loaded outside the server bundle:

```javascript theme={null}
// next.config.mjs
export default {
  serverExternalPackages: ['@clickhouse/clickstack-node'],
};
```

Configure the destination below and set `OTEL_SERVICE_NAME` to identify your application. Do not also preload the SDK or initialize another OpenTelemetry SDK. For additional options, see the [Node.js guide](https://clickhouse.com/docs/clickstack/observability/ingesting-data/sdks/nodejs.md).

For termination and deployment considerations, see the [SDK's Next.js guidance](https://github.com/ClickHouse/clickstack-node#nextjs).

## Vercel and Edge runtime

Use `@vercel/otel` following the [Next.js OpenTelemetry setup instructions](https://nextjs.org/docs/app/guides/open-telemetry). Use this setup instead of the ClickStack Node.js SDK initialization above.

Configure [OTLP export](https://github.com/vercel/otel/tree/main/packages/otel#registerotelconfig-configuration) using the connection settings below. Replace any example destinations and signal-specific endpoint overrides, and set the variables in your deployment configuration.

If your Vercel deployment already uses a tracing integration, configure a [custom exporter](https://nextjs.org/docs/app/guides/open-telemetry#custom-exporters) for this destination; endpoint environment variables alone do not override that integration.

## Configure your destination

Set a service name for either instrumentation option:

```shell theme={null}
export OTEL_SERVICE_NAME='my-nextjs-app'
```

> [tab] Fully managed
>
> [Beta offering](https://clickhouse.com/docs/reference/settings/beta-and-experimental-features.md#beta-features)
>
> Open **Team Settings → Data → Managed Telemetry** in your service and copy the **OTLP HTTP endpoint** and **API key**. Use the complete HTTPS endpoint, including its port:
>
> ```shell theme={null}
> export OTEL_EXPORTER_OTLP_ENDPOINT='https://YOUR_OTEL_ENDPOINT:4318'
> export OTEL_EXPORTER_OTLP_HEADERS='authorization=Bearer%20YOUR_INGESTION_API_KEY'
> export OTEL_EXPORTER_OTLP_PROTOCOL='http/protobuf'
> ```

> [tab] Self-managed
>
> Use your collector's OTLP HTTP endpoint and ingestion key. Use `http://` instead of `https://` if your collector does not have TLS configured. For collector setup, see [Ingesting with OpenTelemetry](https://clickhouse.com/docs/clickstack/observability/ingesting-data/opentelemetry.md#self-managed).
>
> ```shell theme={null}
> export OTEL_EXPORTER_OTLP_ENDPOINT='https://YOUR_COLLECTOR_HOST:4318'
> export OTEL_EXPORTER_OTLP_HEADERS='authorization=YOUR_INGESTION_API_KEY'
> export OTEL_EXPORTER_OTLP_PROTOCOL='http/protobuf'
> ```

## Verify ingestion

Start your application and make requests to a server-rendered page or API route. In ClickHouse Observability, select a recent time range and find your application's service name in Traces.