Visual Editor

A visual editor for React components that allows real-time editing of CSS classes and component props directly in the browser.

Architecture Overview

graph TB
    %% Core Components
    TSX[TSX Files]
    BUILD[Build Attributes]
    BROWSER[Browser]
    EDITOR[Visual Editor]
    DOM[DOM Elements]
    API[API Endpoints]
    AST[AST Processing]

    %% Main Flow
    TSX --> BUILD
    BUILD --> |" Ids & props "| BROWSER
    BROWSER --> EDITOR

    %% Editing Flow
    EDITOR --> |"Real-time Optimistic Updates"| DOM
    EDITOR --> |"Save Changes"| API
    API --> AST
    AST --> TSX

    %% Styling
    classDef source fill:#0d1b24,stroke:#0a1929,stroke-width:2px,color:#fff;
    classDef runtime fill:#14221b,stroke:#102317,stroke-width:2px,color:#fff;
    classDef processing fill:#1a1016,stroke:#2d0a1b,stroke-width:2px,color:#fff;

    class TSX,BUILD source
    class BROWSER,EDITOR,DOM runtime
    class API,AST processing

Loading

Key Architecture Components

1. Build Pipeline

• vibeviz Attributes Script: Pre-processes TSX files to add data-vibeviz-* attributes
• AST Parser: Uses Babel to parse and modify React components
• Component Resolver: Resolves component imports and source locations
• Prop Analyzer: Extracts component prop information using TypeScript
• Biome Formatter: Ensures consistent code formatting
• Bun Bundler: Fast bundling with Tailwind CSS support

2. Runtime Environment

• Visual Editor: React-based UI for editing components
• Element Selector: Click-to-select functionality for DOM elements
• CSS Property Editor: Visual controls for layout properties (flex, gap, padding)
• Component Prop Editor: Dynamic form generation for component props
• Optimistic Updates: Immediate UI feedback with rollback capability

3. AST Processing System

• AST Utils: Core utilities for manipulating Abstract Syntax Trees
• Update Handlers: Specialized handlers for text, attributes, and props
• File Writer: Safe file system operations with error handling

4. Real-time Data Flow

• vibeviz IDs: Unique identifiers linking DOM elements to source code
• Component Props: Serialized component prop information
• Class Names: CSS class management with optimistic updates
• Live Preview: Instant visual feedback during editing

Development Workflow

1. Development: Write React components with standard JSX
2. Build: Run build script to add vibeviz attributes automatically
3. Runtime: Use visual editor to modify components in real-time
4. Save: Changes are automatically saved back to source files
5. Format: Code is automatically formatted and linted

Key Features

• Zero Configuration: Works with existing React projects
• Real-time Editing: Instant visual feedback during editing
• Type Safety: Full TypeScript support with prop analysis
• Optimistic Updates: Immediate UI changes with error rollback
• Code Preservation: Maintains code structure and formatting
• Component Awareness: Understands React component architecture

Quick Start

To install dependencies:

bun install

To start a development server:

bun dev

To run for production:

bun start

vibeviz Attributes Script

The vibeviz attributes script automatically adds visual editing attributes to your TSX files, enabling the visual editor to understand and manipulate your components.

Usage

# Process all TSX files in src/ and components/ui/
bun run scripts/add-vibeviz-attributes.ts

# Process a single file
bun run scripts/add-vibeviz-attributes.ts src/App.tsx

# Show help
bun run scripts/add-vibeviz-attributes.ts --help

What it does

The script analyzes your TSX files and adds the following attributes:

• data-vibeviz-type: Identifies element types (text, img, component, div)
• data-vibeviz-id: Unique identifier for each element
• data-vibeviz-component-name: Component name for React components
• data-vibeviz-simple-class: Marks elements with simple className strings
• data-vibeviz-component-props: Serialized component props for editing
• data-vibeviz-source: Source file path for components

Ignored Elements

Elements with these attributes are ignored during processing:

• data-vibeviz-ignore: Explicitly ignore an element and its children
• data-slot: Radix UI slot elements (automatically ignored)

Examples

// Before processing
<div className="container">
  <h1>Hello World</h1>
  <Button variant="default">Click me</Button>
</div>

After processing
<div
  className="container"
  data-vibeviz-type="div"
  data-vibeviz-id="src/App.tsx:5:3"
>
  <h1
    data-vibeviz-type="text"
    data-vibeviz-id="src/App.tsx:6:5"
    data-vibeviz-simple-class="true"
  >
    Hello World
  </h1>
  <Button
    variant="default"
    data-vibeviz-type="component"
    data-vibeviz-id="src/App.tsx:7:5"
    data-vibeviz-component-name="Button"
    data-vibeviz-component-props='[{"name":"className","type":"string","isOptional":true,"selectedValue":"flex-1"},{"name":"variant","type":"string","possibleValues":["default","destructive","outline","secondary","ghost","link"],"isOptional":true,"defaultValue":"default","selectedValue":"outline"},{"name":"size","type":"string","possibleValues":["default","sm","lg","icon"],"isOptional":true,"defaultValue":"default"}]'
    data-vibeviz-source="src/components/ui/button.tsx"
  >
    Click me
  </Button>
</div>

This project was created using bun init in bun v1.2.13. Bun is a fast all-in-one JavaScript runtime.