@proyecta-ai/vite

Vite plugin suite for Proyecta applications. Provides component tagging, visual editing, route collection, error handling, and dynamic component creation for the Proyecta builder platform.

Installation

npm install @proyecta-ai/vite

Peer dependencies:

npm install vite oxc-parser

Usage

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import proyecta from '@proyecta-ai/vite';

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

With options:

export default defineConfig({
    plugins: [
        ...proyecta({
            debug: true,
            handleViteErrors: true,
            componentTagger: { enabled: true },
            visualEditor: { enabled: true },
            dynamicComponentCreator: { enabled: true },
        }),
        react(),
    ],
});

Options

The proyecta() function accepts a ProyectaPluginOptions object:

| Option | Type | Default | Description | | ------------------------- | --------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------- | | debug | boolean | false | Enable debug logging | | message | string | 'Proyecta plugin is running!' | Custom message to log during build | | handleViteErrors | boolean | true | Enable Vite error handling and console log forwarding | | componentTagger | object | { enabled: true } | Component tagger options (see below) | | visualEditor | object | { enabled: true } | Visual editor options (see below) | | dynamicComponentCreator | object | { enabled: true } | Dynamic component creator options. Only active when PROYECTA_DEV_MACHINE env var is set or force: true |

Features

Component Tagger

Injects data-ve-file, data-ve-line, data-ve-col, and data-ve-component attributes onto JSX elements during development. These attributes enable the Proyecta visual editor to map rendered DOM elements back to their source file locations.

• Parses JSX/TSX files using oxc-parser
• Skips node_modules, React fragments, and Three.js/R3F elements
• Dev-mode only (apply: 'serve')

Visual Editor

Provides an in-browser visual editing experience when the app runs inside the Proyecta builder iframe. Features include:

• Element hover highlighting and selection
• Inline text editing with contentEditable
• Element analysis, updates, and deletion via AST transformation
• Parent frame communication via postMessage protocol

Route Collector

Scans source files for React Router route definitions and exposes them via a /__proyecta_routes endpoint. Supports both JSX <Route> patterns and createBrowserRouter/createHashRouter config objects. Route changes are detected on HMR updates and forwarded to the parent frame.

Error Handling

Intercepts Vite build errors, HMR errors, runtime exceptions, and unhandled promise rejections. Suppresses the Vite error overlay and forwards structured error data to the parent Proyecta builder frame via postMessage.

Dynamic Component Creator

Automatically creates stub React component files when imported .tsx files don't exist yet. Only active when the PROYECTA_DEV_MACHINE environment variable is set (or force: true). Supports both relative imports and @/ alias imports.

Navigation Tracker

Monitors history.pushState, history.replaceState, and popstate events to notify the parent frame of in-app route changes.

Health Check

Exposes a /proyecta-status endpoint that returns the plugin status as JSON.