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

npm install -D @domscribe/next

Basic Setup

// 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

// 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:

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).
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:

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

const nextConfig = {};

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