@timoconnellaus/ai-ui-annotate-vite

Vite plugin for AI UI Annotate - enables component annotation during development.

Installation

npm install @timoconnellaus/ai-ui-annotate-vite --save-dev
# or
bun add -d @timoconnellaus/ai-ui-annotate-vite
# or
pnpm add -D @timoconnellaus/ai-ui-annotate-vite

Usage

Add the plugin to your vite.config.ts:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { aiUiAnnotate } from '@timoconnellaus/ai-ui-annotate-vite'

export default defineConfig({
  plugins: [
    react(),
    aiUiAnnotate()
  ]
})

Configuration

All configuration options are optional with sensible defaults:

aiUiAnnotate({
  // The hotkey to hold for enabling annotation mode
  // Default: 'alt'
  hotkey: 'alt',

  // WebSocket server port for receiving annotations
  // Default: 8234
  port: 8234,

  // Output directory for storing annotations (future use)
  // Default: '.ai-ui-annotate'
  outputDir: '.ai-ui-annotate'
})

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | hotkey | string | 'alt' | Key to hold for annotation mode. Known values: 'alt', 'option', 'ctrl', 'meta' | | port | number | 8234 | WebSocket server port (must be 1024-65535) | | outputDir | string | '.ai-ui-annotate' | Directory for storing annotations |

How It Works

The plugin automatically:

1. Transforms JSX/TSX files - Injects data-component and data-source attributes to track component locations
2. Starts a WebSocket server - Receives annotation data from the browser runtime
3. Injects the runtime script - Adds the annotation UI to your development build

The plugin only activates during vite dev - production builds are unaffected.

Example

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { aiUiAnnotate } from '@timoconnellaus/ai-ui-annotate-vite'

export default defineConfig({
  plugins: [
    react(),
    aiUiAnnotate({
      hotkey: 'ctrl',
      port: 9000
    })
  ]
})

Then run your dev server:

vite dev

Hold the configured hotkey (default: Alt) and click on any component to add an annotation.

Troubleshooting

Port already in use

If you see an error about the port being in use:

[AI UI Annotate] WebSocket server failed to start: port 8234 is already in use

Either stop the other process using that port, or configure a different port:

aiUiAnnotate({ port: 9000 })

Transform not working

If components aren't being annotated:

1. Ensure the file has a .jsx, .tsx, .js, or .ts extension
2. Check that the file is not in node_modules
3. Verify you're running vite dev, not vite build

Hotkey not responding

• Try a different hotkey: 'ctrl', 'meta', or 'option'
• Check for browser extensions that might intercept the key
• On macOS, 'option' is equivalent to 'alt'

WebSocket connection issues

If annotations aren't being saved:

1. Check the browser console for connection errors
2. Verify the WebSocket server started (look for [AI UI Annotate] WebSocket server started)
3. Ensure no firewall is blocking the configured port

TypeScript

The plugin exports TypeScript types:

import { aiUiAnnotate, type VitePluginConfig } from '@timoconnellaus/ai-ui-annotate-vite'

const config: VitePluginConfig = {
  hotkey: 'ctrl',
  port: 9000
}

export default defineConfig({
  plugins: [aiUiAnnotate(config)]
})

License

MIT