@ui-annotate/react-vite

Annotate React UI issues directly in a Vite dev server and hand the captured UI targets to a coding agent.

@ui-annotate/react-vite is a development-only Vite plugin for React apps. It injects inspector metadata, mounts the UI Annotate Runtime into your running page, lets you select real UI targets, records comments, and writes an agent-readable ui.annotate.json file.

Install

npm install -D @ui-annotate/react-vite

With pnpm:

pnpm add -D @ui-annotate/react-vite

Add the Vite plugin

import react from "@vitejs/plugin-react";
import { uiAnnotate } from "@ui-annotate/react-vite";
import { defineConfig } from "vite";

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

Start your Vite dev server as usual:

npm run dev

The plugin only runs during Vite development. Production builds do not include the UI Annotate Runtime.

Use Annotate Mode

When the dev server page loads, UI Annotate adds a floating toolbar to the page.

• Press D or click the toolbar Annotate button to enter annotate mode.
• Hover the host page to highlight selectable UI targets.
• Click a target to add it to the annotate task.
• Add comments in the Annotate window.
• Use Cmd/Ctrl + click on a target or trace node to open the source location in VS Code.
• Use Cmd/Ctrl + S to save immediately.
• Press Escape to leave annotate mode.

While annotate mode is active, UI Annotate intercepts host-page clicks, form submissions, drag starts, focus changes, and related interactions so selecting UI does not trigger real app behavior. When annotate mode is off, the host page works normally.

Agent Handoff

UI Annotate writes the selected targets and comments to ui.annotate.json in your project root.

After recording the UI issue, hand that file to your coding agent. A typical prompt is:

Read ui.annotate.json and update the referenced React UI according to the comments.

The task file is the handoff artifact. It records the selected UI targets, trace information, source locations, dimensions, style details, and user comments that the agent should use while editing the code.

Options

uiAnnotate({
  enabled: true,
  root: process.cwd()
});

• enabled: Set to false to disable both inspector transforms and runtime injection.
• root: Project root used for source paths and ui.annotate.json. Defaults to the Vite config root.

Runtime Boundaries

• Supported host apps: React 18 or 19 with Vite 7 or 8.
• The runtime is development-only and is injected by the Vite dev server.
• The runtime creates #__ui_annotate_root__ under document.body; your app does not need to provide a mount point.
• The UI is isolated in a shadow root.
• Highlights and overlays are drawn outside the host app and do not directly mutate host DOM classes, styles, or structure.
• Component trace depends on React Fiber plus inspector metadata injected by the plugin.
• The package is for React + Vite apps; it is not a production feedback widget, Next.js plugin, or Webpack plugin.