@codedesign/vite-live-edit-plugin

A Vite plugin for live editing React components with AST-powered source mapping. Enables precise, character-level updates to your source files directly from the browser.

Features

• 🎯 AST-Powered Source Mapping - Injects precise location data into JSX elements
• 📝 Text Content Editing - Edit text content directly from the browser
• 🖼️ Image Source Editing - Update image sources with validation
• 🎥 Video Source Editing - Update video src attributes with validation
• 🌐 Iframe Support - Edit iframe src and srcDoc attributes
• ✅ Full Validation - Pre and post-update validation with rollback capability
• 🔒 Security - Validates URLs and content before applying changes
• ⚡ HMR Integration - Automatically triggers Vite's Hot Module Reload
• 🔍 Module Graph API - Query dependency relationships to optimize build operations

Installation

Option 1: Private npm Registry

npm install @codedesign/vite-live-edit-plugin --registry=https://registry.npmjs.org/

Option 2: GitHub Packages

npm install @codedesign/vite-live-edit-plugin --registry=https://npm.pkg.github.com

Option 3: Local Installation (Development)

npm install /path/to/codedesign-live-edit-plugin

Or using a git repository:

npm install git+https://github.com/your-org/codedesign-live-edit-plugin.git

Usage

vite.config.js

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { sourceMapperPlugin, enhancedLiveEditPlugin } from '@codedesign/vite-live-edit-plugin';

export default defineConfig({
  plugins: [
    sourceMapperPlugin(), // MUST BE FIRST - before any other transformations
    react(),
    enhancedLiveEditPlugin(), // Includes module graph API automatically
  ],
});

How It Works

1. Source Mapping: The sourceMapperPlugin() injects data-element-id and data-source-loc attributes into JSX elements during development.

2. Live Editing: The enhancedLiveEditPlugin() sets up API endpoints:

   • /api/live-edit - Receives update requests from the browser, validates location data, updates source files, and triggers HMR
   • /__module_graph - Queries Vite's module graph to find which modules import a given file (useful for smart screenshot capture and impact analysis)
   • /__module_errors - Queries all types of errors from Vite's internal state (module errors, transform errors, CSS errors, plugin errors, resolution errors)

Supported Elements

The plugin automatically instruments and enables live editing for:

| Element | Attribute | Type | Description | |---------|-----------|------|-------------| | <img>, <Image> | src | image-src | Image source URLs | | <video> | src | video-src | Video source URLs | | <iframe> | src | iframe-src | Iframe source URLs | | <iframe> | srcDoc | iframe-srcDoc | Inline HTML content (up to 50KB) | | Text elements | (text content) | text-content | Text within JSX elements |

Note: Dynamic expressions (variables, template literals) are skipped. Only static string values are tracked for editing.

API Endpoints

1. Live Edit Endpoint

The plugin exposes a POST endpoint at /api/live-edit:

Example 1: Text Content Update

POST /api/live-edit
Content-Type: application/json

{
  "element": {
    "tagName": "P",
    "elementId": "Home-p-L5-0",
    "sourceLoc": {
      "file": "pages/Home.jsx",
      "start": 123,
      "end": 145,
      "text": "Original text",
      "type": "text-content"
    }
  },
  "content": "New text content"
}

Example 2: Video Source Update

POST /api/live-edit
Content-Type: application/json

{
  "element": {
    "tagName": "VIDEO",
    "elementId": "Hero-video-L20-0",
    "sourceLoc": {
      "file": "components/Hero.jsx",
      "start": 450,
      "end": 475,
      "text": "old-video.mp4",
      "type": "video-src",
      "attributeName": "src"
    }
  },
  "content": "new-video.mp4"
}

Example 3: Iframe srcDoc Update

POST /api/live-edit
Content-Type: application/json

{
  "element": {
    "tagName": "IFRAME",
    "elementId": "Preview-iframe-L15-0",
    "sourceLoc": {
      "file": "components/Preview.jsx",
      "start": 300,
      "end": 350,
      "text": "<h1>Old Content</h1>",
      "type": "iframe-srcDoc",
      "attributeName": "srcDoc"
    }
  },
  "content": "<h1>New Content</h1>"
}

2. Module Graph Endpoint

The enhancedLiveEditPlugin() also exposes a GET endpoint at /__module_graph:

GET /__module_graph?file=/absolute/path/to/file.jsx

# Example Response:
{
  "file": "/root/project/src/components/HeroSection.jsx",
  "moduleId": "/src/components/HeroSection.jsx",
  "url": "/src/components/HeroSection.jsx",
  "dependents": [
    {
      "id": "/src/pages/HomePage.jsx",
      "url": "/src/pages/HomePage.jsx",
      "file": "/root/project/src/pages/HomePage.jsx",
      "type": "js"
    }
  ],
  "totalDependents": 1
}

Use Cases:

• Smart Screenshot Capture - Only capture pages that import an edited component
• Impact Analysis - Understand which parts of your app are affected by changes
• Build Optimization - Target specific modules for rebuild operations

3. Module Errors Endpoint

The enhancedLiveEditPlugin() also exposes a GET endpoint at /__module_errors:

GET /__module_errors

# Example Response:
{
  "errors": [
    {
      "type": "module_error",
      "moduleId": "/src/components/Button.jsx",
      "url": "/src/components/Button.jsx",
      "file": "/root/project/src/components/Button.jsx",
      "error": {
        "message": "Unexpected token",
        "stack": "...",
        "code": "PARSE_ERROR"
      },
      "importers": [
        {
          "id": "/src/pages/HomePage.jsx",
          "url": "/src/pages/HomePage.jsx",
          "file": "/root/project/src/pages/HomePage.jsx"
        }
      ]
    }
  ],
  "errorsByType": {
    "module_error": [...],
    "transform_error": [...],
    "ssr_error": [...],
    "module_resolution_error": [...],
    "plugin_error": [...]
  },
  "totalErrors": 1,
  "timestamp": "2025-12-29T10:00:00.000Z"
}

Error Types:

• module_error - Module loading/parsing errors
• transform_error - JS/TS/CSS transformation errors
• ssr_error - Server-side rendering errors
• ssr_transform_error - SSR transform result errors
• import_error - Client-side import errors
• dependency_error - Errors in module dependencies
• module_resolution_error - Failed module imports
• plugin_error - Vite plugin errors
• http_error - HTTP 4xx/5xx errors (including 500 errors) for any file request

HTTP Error Details: The http_error type includes additional fields:

• statusCode - HTTP status code (400, 404, 500, etc.)
• statusMessage - HTTP status message
• method - HTTP method (GET, POST, etc.)
• timestamp - When the error occurred

Use Cases:

• Error Monitoring - Track all build/dev errors in one place, including HTTP 500 errors
• Impact Analysis - See which modules are affected by errors
• Debugging - Identify error sources and their importers
• HTTP Error Tracking - Monitor failed file requests with status codes

Requirements

• Node.js >= 18.0.0
• Vite >= 4.0.0
• React (for JSX support)

Development

Building

This package uses ES modules and doesn't require a build step. The source code is ready to use.

Testing

1. Install dependencies:

   npm install

2. Link locally for testing:

   npm link

3. In your project:

   npm link @codedesign/vite-live-edit-plugin

Publishing

To Private npm Registry

1. Login to npm:

   npm login --registry=https://registry.npmjs.org/

2. Publish (package.json already has "private": true, so this will fail unless you have a paid npm account):

   npm publish --access restricted

   Note: For truly private packages, you need an npm paid account or use GitHub Packages.

To GitHub Packages

1. Create .npmrc in the package directory:

   @codedesign:registry=https://npm.pkg.github.com
   //npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

2. Login:

   npm login --registry=https://npm.pkg.github.com --scope=@codedesign

3. Publish:

   npm publish

To Git Repository (Private)

1. Remove "private": true from package.json (or keep it, it doesn't affect git installs)

2. Tag and push:

   git tag v1.0.0
   git push origin v1.0.0

3. Install in projects:

   npm install git+https://github.com/your-org/codedesign-live-edit-plugin.git#v1.0.0

Configuration

The plugin automatically:

• Only runs in development mode (NODE_ENV !== 'production')
• Only processes .jsx and .tsx files in the src/ directory
• Injects source mapping data into JSX elements

No additional configuration is required.

License

MIT

Support

For issues and questions, please open an issue in the repository.