Skip to content

README.md

Latest commit

 

History

History
165 lines (123 loc) · 9.54 KB

README.md

File metadata and controls

165 lines (123 loc) · 9.54 KB

@domscribe/transform

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