UI Bridge

Documentation

Preferences

Plugin-level

Pass a preferences object to your integration to set defaults for your whole project. These are used as the base layer and can still be overridden by individual users at runtime.

// vite.config.ts

import { defineConfig } from 'vite';
import { uiBridgeVite } from '@ui-bridge/unplugin';

export default defineConfig({
  plugins: [
    ...uiBridgeVite({
      preferences: {
        commentBar: { position: 'bottom-right' },
        visibility: { status: 'always' },
      },
    }),
  ],
});

The same preferences key is available on all integrations (withUiBridge, uiBridge(), @ui-bridge/nuxt).

Browser overrides

Click the gear icon (⚙) in the comment bar to open the preferences dialog. Changes are saved immediately to .ui-bridge/preferences.json and broadcast to all connected browser sessions.

API

interface VisibilityConfig {
  /**
   * Which comments/knobs are visible.
   * 'non-approved' hides threads whose tweaks are all accepted or discarded.
   * @default 'non-approved'
   */
  status?: 'always' | 'non-approved' | 'never';

  /**
   * URL-based filter. All false/unset means show all comments regardless of URL.
   * Bar default: all false (show across all routes — click to navigate).
   * Panel default: { path: true } (current page only).
   */
  route?: {
    /**
     * Only show comments whose pageUrl matches the current origin
     * (protocol + host + port).
     * @default false
     */
    domain?: boolean;

    /**
     * Only show comments whose pageUrl pathname matches the current page.
     * Bar default: false. Panel default: true.
     */
    path?: boolean;

    /**
     * Only show comments whose pageUrl query string matches the current page.
     * @default false
     */
    params?: boolean;
  };
}

interface UserPreferences {
  /**
   * Shared visibility defaults for both the comment bar and the comment panel.
   * Each context can override individually.
   */
  visibility?: VisibilityConfig;

  commentBar?: {
    /**
     * Where the comment bar is pinned on screen.
     * @default 'top-left'
     */
    position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';

    /**
     * Visibility overrides for the comment bar.
     * Merged on top of `visibility`.
     * Bar-specific route default: all false (show comments from all routes
     * so users can click a badge to navigate to a different page).
     */
    visibility?: VisibilityConfig;
  };

  ui?: {
    /**
     * Visibility overrides for the floating comment panel.
     * Merged on top of `visibility`.
     * Panel-specific route default: { path: true } (current page only).
     */
    visibility?: VisibilityConfig;
  };
}

Custom Source Annotation

If possible, UI Bridge automatically detects to which file and even line a comment belongs using code-inspector. If your stack doesn’t support it — or you want to override it — you can read it from HTML comments or data attributes in the rendered markup.

// vite.config.ts

import { defineConfig } from 'vite';
import { uiBridgeVite } from '@ui-bridge/unplugin';

export default defineConfig({
  plugins: [
    ...uiBridgeVite({
      inspector: false,
      sourceAnnotation: {
        // Each entry is a regex. Capture group 1 is the file path.
        // List multiple patterns if you mix frameworks — first match wins.
        htmlComments: [{ pattern: 'Start view: (.+?\\.blade\\.php)' }],
      },
    }),
  ],
});

// vite.config.ts

import { defineConfig } from 'vite';
import { uiBridgeVite } from '@ui-bridge/unplugin';

export default defineConfig({
  plugins: [
    ...uiBridgeVite({
      sourceAnnotation: {
        // Single attribute encoding "file:line:col"
        dataAttributes: [{ pathAttr: 'data-source' }],
        // Or split across two attributes:
        // dataAttributes: [{ fileAttr: 'data-file', locAttr: 'data-loc' }],
      },
    }),
  ],
});

Custom Integrations

// vite.config.ts

import { defineConfig } from 'vite';
import inertia from '@inertiajs/vite';
import laravel from 'laravel-vite-plugin';
import { uiBridgeVite } from '@ui-bridge/unplugin';

export default defineConfig(({ command }) => ({
  plugins: [
    laravel({ input: ['resources/css/app.css', 'resources/js/app.tsx'] }),
    inertia({ ssr: false }),
    // Dev-only tooling: its production build hooks are no-ops but still get
    // invoked for every module in the graph, adding needless build time.
    ...(command === 'serve' ? uiBridgeVite() : []),
  ],
}));

// resources/js/app.tsx

import 'virtual:ui-bridge';

// .storybook/main.ts

import type { StorybookConfig } from '@storybook/react-vite';

const config: StorybookConfig = {
  framework: '@storybook/react-vite',
  viteFinal: async (config) => {
    // uiBridgeVite() from the root vite.config.ts is already merged in here —
    // do NOT add it again. Registering it twice injects the client script
    // (and opens the WebSocket connection) twice, giving you two floating
    // panels.
    return config;
  },
};

export default config;

Monorepos and subdirectories

The MCP server finds its data by looking for a .ui-bridge/ folder, starting from its working directory and walking up. This works automatically when UI Bridge runs at your project root.

If UI Bridge runs in a subdirectory — a docs/ folder, a monorepo package, etc. — set cwd to that directory:

// .vscode/mcp.json

{
  "servers": {
    "ui-bridge": {
      "type": "stdio",
      "command": "npx",
      "args": ["--no", "ui-bridge-mcp"],
      "cwd": "${workspaceFolder}/packages/my-app"
    }
  }
}

Allow tweaks outside the project root

By default, tweaks can only modify files within the Vite/framework project root (the directory containing your vite.config.ts, or your app’s working directory in Next.js). In monorepo setups where tweaks need to target files in sibling packages, enable allowOutsideRoot:

// vite.config.ts

...uiBridgeVite({
  allowOutsideRoot: true,
})

The same option is available on all integrations (withUiBridge, uiBridge(), @ui-bridge/nuxt).

When using the standalone server directly, pass the --allow-outside-root CLI flag:

node node_modules/@ui-bridge/server/index.mjs --root ./packages/my-app --allow-outside-root

Working with Git

UI Bridge stores everything in a .ui-bridge/ folder at your project root. Deciding what to commit — and what to ignore — is a team decision.

What’s in .ui-bridge/

Preferences

There are two ways to share preferences with your team. Usually it’s best to set defaults in the plugin config and let individuals adjust as they like through the browser dialog — those changes are local and won’t affect anyone else.

The simplest way to keep preferences local is to gitignore the whole file:

# .gitignore

.ui-bridge/preferences.json

// vite.config.ts

...uiBridgeVite({
  preferences: {
    commentBar: { position: 'bottom-right' },
    visibility: { route: { path: true } },
  },
})

Comments and Knob scripts

Comment files in comments/ are plain JSON. Commit them and every team member sees the same open threads when they run their dev server. The agent reads them through MCP and can pick up where you left off.

Knob scripts in scripts/ are the transform functions your agent writes when replying with a live tweak. They’re referenced by comment threads, so if you commit comments you should commit their scripts too — otherwise teammates won’t be able to replay the tweaks.

If you prefer to keep the .ui-bridge/ folder entirely local:

# .gitignore

.ui-bridge/

In that case, comments and tweaks are personal and not shared across the team.