@mitway/tagger

Vite plugin suite for MITWAY platform integration. Provides source tracking, live visual editing, virtual file overrides, iframe navigation, and theme bridging for user projects running inside the MITWAY-App editor.

Install

pnpm add -D @mitway/tagger

Usage

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

const isDev = process.env.NODE_ENV !== "production";

export default defineConfig({
  plugins: [
    react(),
    ...(isDev ? mitwayTagger() : mitwayProductionPlugins()),
  ],
  server: mitwayServerConfig,
  preview: mitwayServerConfig,
});

Plugins

The suite contains five plugins, all enabled by default in mitwayTagger():

| Plugin | Dev only | What it does | |---|---|---| | jsxSource | Yes | Injects source file/line metadata into JSX elements for click-to-source in the visual editor | | virtualOverrides | Yes | Allows MITWAY-App to push temporary file modifications with HMR support | | visualEditor | Yes | Enables element selection and live style preview via postMessage to the parent MITWAY-App | | iframeNavigation | No | Notifies the parent window when the user navigates (route changes) inside the iframe | | themeBridge | No | Receives real-time theme changes from MITWAY-App and applies them to CSS variables |

Important: jsxSource forces jsxDEV: true, which breaks production builds with "jsxDEV is not a function". Always use mitwayProductionPlugins() in production, which only includes iframeNavigation and themeBridge.

API

mitwayTagger(options?)

Returns all five plugins. Use in development.

interface mITwayTaggerOptions {
  jsxSource?: boolean;        // default true
  virtualOverrides?: boolean; // default true
  visualEditor?: boolean;     // default true
  iframeNavigation?: boolean; // default true
  themeBridge?: boolean;      // default true
  extensions?: string[];      // default ['.jsx', '.tsx']
  exclude?: string[];         // default ['node_modules', '.git']
}

mitwayProductionPlugins(options?)

Returns only the production-safe plugins (iframeNavigation + themeBridge).

mitwayServerConfig

Pre-configured Vite server settings (CORS, CSP headers, allowed hosts) for embedding in the MITWAY-App iframe. Use directly with Vite's server and preview options.

createmITwayServerConfig(options?)

Creates a customized server config by merging additional origins and hosts into the defaults.

const config = createmITwayServerConfig({
  additionalOrigins: ["https://my-custom-domain.com"],
  additionalHosts: [".my-custom-domain.com"],
  port: 3000,
});

Individual plugin exports

Each plugin is also exported individually for advanced use cases:

import {
  createJsxSourcePlugin,
  createVirtualOverridesPlugin,
  createVisualEditorPlugin,
  createIframeNavigationPlugin,
  createThemeBridgePlugin,
} from "@mitway/tagger";

Releasing a new version

Releases are automated via GitHub Actions.

1. Bump the version:

pnpm version patch   # or minor / major

2. Push the commit and tag:

git push --follow-tags

3. Create a Release on GitHub pointing to the new tag.

The workflow builds and publishes to npm with provenance attestation. Requires an NPM_TOKEN secret configured in the repository.

Requirements

• Vite >= 5.0.0 (peer dependency)