# Nuxt

The `@domscribe/nuxt` package is a Nuxt 3+ module that handles relay startup, transform registration, and runtime initialization automatically.

## Install

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

## Basic Setup

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@domscribe/nuxt'],
});
```

That is all you need for the default configuration. The module automatically:

- Starts the relay daemon
- Registers Vite and Webpack transform plugins
- Injects relay and overlay globals into the app head
- Installs a client-only runtime plugin that initializes the Vue adapter

## Configuration

Configure Domscribe via the `domscribe` key in your Nuxt config:

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@domscribe/nuxt'],
  domscribe: {
    debug: true,
    overlay: {
      initialMode: 'expanded',
    },
    relay: {
      port: 4400,
    },
  },
});
```

## Configuration Options

The `domscribe` config key accepts a `DomscribeNuxtOptions` object:

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `include` | `RegExp` | `/\.(jsx|tsx|vue)$/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. |
| `relay.bodyLimit` | `number` | `10485760` (10 MB) | Max request body size in bytes. |

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

- **Nuxt 3+** with Vite (default) or Webpack builder

## How It Works

The module orchestrates five steps during Nuxt setup:

1. **Relay startup** -- starts the relay daemon and discovers the actual host and port.
2. **Head script injection** -- injects `window.__DOMSCRIBE_RELAY_PORT__`, `window.__DOMSCRIBE_RELAY_HOST__`, and `window.__DOMSCRIBE_OVERLAY_OPTIONS__` globals via `app.head`. This is necessary because Nuxt bypasses Vite's `transformIndexHtml`, so the Vite plugin's HTML injection does not fire.
3. **Vite plugin registration** -- registers the base `@domscribe/transform` Vite plugin for AST transformation on both server and client builds, with relay auto-start disabled (since the relay is already running).
4. **Webpack fallback** -- registers the webpack loader and plugin as a fallback for projects using the Webpack builder.
5. **Runtime plugin** -- installs a client-only Nuxt plugin that initializes the `RuntimeManager` with the `VueAdapter` and starts the overlay if configured.

The module only activates in development mode. In production builds, it is a no-op.