# Next.js

The `@domscribe/next` package provides a drop-in `withDomscribe()` config wrapper for Next.js 15 and 16. It automatically configures both Turbopack and Webpack bundler paths, so it works regardless of which bundler you use.

## Install

```bash
npm install -D @domscribe/next
```

## Basic Setup

```ts
// next.config.ts
import type { NextConfig } from 'next';
import { withDomscribe } from '@domscribe/next';

const nextConfig: NextConfig = {};

export default withDomscribe()(nextConfig);
```

That is all you need. Domscribe is zero-config by default -- it auto-detects your bundler, starts the relay daemon, and injects `data-ds` attributes into your JSX/TSX files.

## Advanced Configuration

```ts
// next.config.ts
import type { NextConfig } from 'next';
import { withDomscribe } from '@domscribe/next';

const nextConfig: NextConfig = {
  reactStrictMode: true,
};

export default withDomscribe({
  debug: true,
  overlay: {
    initialMode: 'expanded',
    debug: true,
  },
  relay: {
    port: 4400,
    host: '127.0.0.1',
  },
})(nextConfig);
```

## Configuration Options

The `withDomscribe()` function accepts a `DomscribeNextOptions` object:

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `enabled` | `boolean` | `true` | Enable transformation. Automatically disabled in production. |
| `include` | `RegExp` | `/\.(jsx|tsx)$/i` | File pattern to include for transformation. |
| `exclude` | `RegExp` | `/node_modules|\.test\.|\.spec\./i` | File pattern to exclude from transformation. |
| `debug` | `boolean` | `false` | Enable debug logging. |
| `relay` | `object` | `{}` | Relay server configuration (see below). |
| `overlay` | `boolean | object` | `true` | Overlay UI configuration (see below). |

### Relay Options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `relay.autoStart` | `boolean` | `true` | Auto-start the relay daemon if not running. |
| `relay.port` | `number` | `0` (dynamic) | Port for the relay server. |
| `relay.host` | `string` | `'127.0.0.1'` | Host for the relay server. |

### Overlay Options

When `overlay` is an object:

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `overlay.initialMode` | `'collapsed' | 'expanded'` | `'collapsed'` | Initial display mode for the overlay. |
| `overlay.debug` | `boolean` | `false` | Enable debug logging in the overlay. |

## Supported Versions

- **Next.js 15** \-\- Webpack bundler path
- **Next.js 16** \-\- Turbopack bundler path (default in Next.js 16)

Both bundler paths are configured automatically by `withDomscribe()`. You do not need to do anything different for Turbopack vs Webpack.

## How It Works

The `withDomscribe()` wrapper:

1. **In development**, injects a self-initializing loader that transforms JSX/TSX files to add `data-ds` attributes. The loader runs on both server and client compilations so that server-rendered HTML and client hydration produce matching attributes (no hydration mismatches).

2. **In production**, replaces `@domscribe/overlay` imports with a no-op stub as a safety net against accidental imports. All instrumentation is stripped.

The integration uses the same turbopack-compatible loader for both bundler paths, which handles its own singleton management (manifest writer, relay lifecycle) via process exit handlers. This avoids the race conditions that can occur with Next.js's dual server/client compilation model.

## Composing with Other Wrappers

`withDomscribe()` returns a standard Next.js config function, so it composes naturally with other config wrappers:

```ts
import { withDomscribe } from '@domscribe/next';
import { withSentryConfig } from '@sentry/nextjs';

const nextConfig = {};

export default withSentryConfig(
  withDomscribe()(nextConfig),
  { /* sentry options */ }
);
```