mITway Tagger

Vite plugin suite for Mesh IT Midway integration. Provides everything needed for the mITway-Starter template to communicate with mITway-App.

Features

| Feature | Description | |---------|-------------| | JSX Source Tracking | Injects source location metadata into React components for visual editing | | Virtual Overrides | Temporary file modifications with HMR support (no disk writes) | | Visual Editor | Element selection and live style preview via postMessage | | Iframe Navigation | Notifies parent window of navigation changes | | Theme Bridge | Real-time theme preview from mITway-App | | Server Config | Pre-configured CORS and CSP settings for iframe integration |

Installation

pnpm add -D mitway-tagger

Usage

Basic (all features enabled)

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react-swc';
import { mitwayTagger } from 'mitway-tagger';

export default defineConfig({
  plugins: [
    react(),
    ...mitwayTagger()
  ]
});

With options

import { mitwayTagger } from 'mitway-tagger';

export default defineConfig({
  plugins: [
    react(),
    ...mitwayTagger({
      jsxSource: true,        // JSX source tracking (default: true)
      virtualOverrides: true, // Virtual file overrides (default: true)
      visualEditor: true,     // Visual editor support (default: true)
      iframeNavigation: true, // Iframe navigation events (default: true)
      themeBridge: true,      // Theme preview bridge (default: true)
    })
  ]
});

Individual plugins

import {
  createJsxSourcePlugin,
  createVirtualOverridesPlugin,
  createVisualEditorPlugin,
  createIframeNavigationPlugin,
  createThemeBridgePlugin
} from 'mitway-tagger';

export default defineConfig({
  plugins: [
    react(),
    createJsxSourcePlugin({ extensions: ['.tsx'], exclude: ['node_modules'] }),
    createVisualEditorPlugin(),
    createThemeBridgePlugin(),
    // ... only the plugins you need
  ]
});

Features Detail

1. JSX Source Tracking

Intercepts react/jsx-dev-runtime to attach source location metadata to DOM nodes via a Symbol. This enables the Visual Editor to map selected elements back to their source code.

// How it works:
// Every React element gets a Symbol attached with source info
element[Symbol.for('__mitwaySource__')] = {
  fileName: '/src/components/Button.tsx',
  lineNumber: 42,
  columnNumber: 8
};

2. Virtual Overrides

Allows mITway-App to send temporary file modifications via WebSocket. Changes are applied in-memory and trigger HMR without writing to disk.

WebSocket events:

• mitway:override - Apply temporary file override
• mitway:clear-override - Clear override for a file
• mitway:clear-all-overrides - Clear all overrides

3. Visual Editor

Injects a script that enables:

• Element highlighting on hover
• Element selection with visual overlay
• Live style preview via inline styles
• Communication with parent window via postMessage

Message types (to parent):

• VISUAL_EDITOR_ELEMENT_SELECTED - Element was selected
• VISUAL_EDITOR_ELEMENT_DESELECTED - Selection cleared
• VISUAL_EDITOR_HOVER - Element being hovered

Message types (from parent):

• VISUAL_EDITOR_ACTIVATE - Enable selection mode
• VISUAL_EDITOR_DEACTIVATE - Disable selection mode
• VISUAL_EDITOR_PREVIEW_STYLE - Preview styles on element
• VISUAL_EDITOR_RESTORE_STYLE - Restore original styles

4. Iframe Navigation

Notifies mITway-App when navigation occurs within the iframe:

• Intercepts history.pushState and history.replaceState
• Listens for popstate events
• Sends IFRAME_NAVIGATION messages to parent
• Receives NAVIGATE_TO commands from parent

5. Theme Bridge

Enables real-time theme preview:

• Captures original CSS variable values
• Applies theme colors with proper HSL wrapping
• Supports both base (--background) and color-prefixed (--color-background) variables
• Handles radius variables separately

Message types (from parent):

• PREVIEW_THEME - Preview theme without persisting
• RESTORE_THEME - Restore original CSS variables
• APPLY_THEME - Apply and persist theme

Message types (to parent):

• THEME_BRIDGE_READY - Bridge initialized
• THEME_APPLIED - Theme was applied

Server Configuration

Mesh IT Midway requires specific CORS and CSP settings to work properly inside iframes. The package exports pre-configured server settings:

Using mitwayServerConfig

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react-swc';
import path from 'path';
import { mitwayTagger, mitwayServerConfig } from 'mitway-tagger';

export default defineConfig({
  plugins: [
    react(),
    ...mitwayTagger()
  ],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
  server: mitwayServerConfig,
  preview: mitwayServerConfig,
});

With custom domains

If you need to add custom domains to the allowed origins:

import { mitwayTagger, createmITwayServerConfig } from 'mitway-tagger';

const serverConfig = createmITwayServerConfig({
  additionalOrigins: ['https://my-custom-domain.com'],
  additionalHosts: ['.my-custom-domain.com'],
  port: 3000, // optional, defaults to 80
});

export default defineConfig({
  plugins: [react(), ...mitwayTagger()],
  server: serverConfig,
  preview: serverConfig,
});

What's included in mitwayServerConfig

| Setting | Value | |---------|-------| | Host | 0.0.0.0 | | Port | 80 | | CORS Origins | app.nttmitway.com, app.dev.nttmitway.com, app.mitway.local, localhost:* | | CORS Methods | GET, POST, PUT, DELETE, OPTIONS | | CORS Headers | Content-Type, Authorization | | CSP frame-ancestors | Same as CORS origins | | Allowed Hosts | .azurecontainerapps.io, .nttmitway.com |

mITway-Starter Integration

With mitway-tagger, your vite.config.ts becomes minimal:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react-swc';
import path from 'path';
import { mitwayTagger, mitwayServerConfig } from 'mitway-tagger';

export default defineConfig({
  plugins: [react(), ...mitwayTagger()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
  server: mitwayServerConfig,
  preview: mitwayServerConfig,
});

No need for separate plugin files or manual CORS/CSP configuration - everything is included in mitway-tagger.

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Watch mode
pnpm dev

Publishing

# Build and publish
pnpm build
npm publish

License

MIT