@domscribe/transform

March 26, 2026 · View on GitHub

AST injection of stable element IDs and bundler plugins for Domscribe.

Install

npm install -D @domscribe/transform

Note: You probably want a framework adapter instead (@domscribe/react, @domscribe/vue, @domscribe/next, @domscribe/nuxt). Those packages wrap this one and handle framework-specific wiring automatically.

Bundler Support

Bundler	Plugin	Parser
Vite 5-7	`@domscribe/transform/plugins/vite`	Acorn (JS/JSX) or VueSFC
Webpack 5	`@domscribe/transform/plugins/webpack`	Babel (TS/JSX) or VueSFC
Turbopack	Self-initializing loader	Babel (TS/JSX)

Configuration

Shared Options — Relay

These options apply to the relay field across all bundler plugins.

Option	Type	Default	Description
`autoStart`	`boolean`	`true`	Auto-start the relay daemon if not running
`port`	`number`	`0` (dynamic)	Relay server port (only used when starting)
`host`	`string`	`'127.0.0.1'`	Relay server host (only used when starting)
`bodyLimit`	`number`	`10485760` (10MB)	Max request body size in bytes (only used when starting)

Shared Options — Overlay

These options apply when overlay is set to an object instead of a boolean.

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

Vite Plugin

import { domscribe } from '@domscribe/transform/plugins/vite';

domscribe({
  include: /\.(jsx|tsx|vue)$/i,
  exclude: /node_modules|\.test\.|\.spec\./i,
  debug: false,
  relay: { autoStart: true, port: 0, host: '127.0.0.1', bodyLimit: 10485760 },
  overlay: true,
  rootDir: undefined, // Override root directory for .domscribe/ artifacts
});

Option	Type	Default	Description
`include`	`RegExp`	`/\.(jsx\|tsx\|vue)$/i`	File pattern to include
`exclude`	`RegExp`	`/node_modules\|\.test\.\|\.spec\./i`	File pattern to exclude
`debug`	`boolean`	`false`	Enable debug logging
`relay`	`RelayPluginOptions`	See shared	Relay server config
`overlay`	`boolean \| OverlayPluginOptions`	`true`	Overlay UI config
`rootDir`	`string`	Vite's `config.root`	Override root directory for `.domscribe/` artifacts. Needed when Vite root differs from project root (e.g., Nuxt with a custom `srcDir`).

Webpack Plugin

import { DomscribeWebpackPlugin } from '@domscribe/transform/plugins/webpack';

new DomscribeWebpackPlugin({
  enabled: true,
  debug: false,
  relay: { autoStart: true, port: 0, host: '127.0.0.1' },
  overlay: true,
});

Option	Type	Default	Description
`enabled`	`boolean`	`true` in dev, `false` in production	Enable the plugin
`debug`	`boolean`	`false`	Enable debug logging
`relay`	`RelayPluginOptions`	See shared	Relay server config
`overlay`	`boolean \| OverlayPluginOptions`	`true`	Overlay UI config

Webpack Loader Options

The webpack loader is managed internally by DomscribeWebpackPlugin. If you need to configure it directly via @domscribe/transform/webpack-loader:

Option	Type	Default	Description
`debug`	`boolean`	`false`	Enable debug logging
`enabled`	`boolean`	`true`	Enable transformation

Turbopack Loader

Turbopack has no plugin system, so the loader is self-initializing — it manages relay lifecycle and overlay injection directly.

// next.config.ts (turbopack)
{
  turbopack: {
    rules: {
      '*.{tsx,jsx}': {
        loaders: [{
          loader: '@domscribe/transform/turbopack-loader',
          options: {
            enabled: true,
            debug: false,
            relay: { autoStart: true, port: 0, host: '127.0.0.1' },
            overlay: false,
            autoInitPath: undefined,
          },
        }],
      },
    },
  },
}

Option	Type	Default	Description
`enabled`	`boolean`	`true`	Enable transformation
`debug`	`boolean`	`false`	Enable debug logging
`relay`	`RelayPluginOptions`	See shared	Relay server config
`overlay`	`boolean \| OverlayPluginOptions`	`false`	Overlay UI config. Defaults to `false` unlike Vite/Webpack — overlay injection must be handled by the meta-framework wrapper.
`autoInitPath`	`string`	`undefined` (falls back to `@domscribe/next/auto-init`)	Absolute filesystem path to the auto-init module. Used in pnpm monorepos where transformed files don't directly depend on the auto-init package. Meta-framework wrappers should resolve this via `require.resolve()`.

`getInitResult()`

import { getInitResult } from '@domscribe/transform/plugins/turbopack';

const result = getInitResult();
// { relayHost: string | undefined, relayPort: number | undefined }

Returns the relay host and port detected during loader initialization. Available after the first file is processed. Used by meta-framework wrappers (e.g., @domscribe/next) to read relay connection info after the loader has initialized.

Subpath Exports

Subpath	Description
`@domscribe/transform/plugins/vite`	Vite plugin (`domscribe`)
`@domscribe/transform/plugins/webpack`	Webpack plugin (`DomscribeWebpackPlugin`)
`@domscribe/transform/webpack-loader`	Webpack loader path (string, for direct use)
`@domscribe/transform/plugins/turbopack`	Turbopack exports (`getInitResult`)
`@domscribe/transform/turbopack-loader`	Turbopack loader path (string, for direct use)

Links

Part of Domscribe.

License

MIT