@unplatform/unui (0.1.0)

Published 2026-02-28 20:30:56 +00:00 by bidi

Setup this registry in your project .npmrc file:

@unplatform:registry=

To install the package using npm, run the following command:

npm install @unplatform/unui@0.1.0

or add it to the package.json file:

"@unplatform/unui": "0.1.0"

For more information on the npm registry, see the documentation.

unui

Browser devtools overlay for any webapp — element inspector, dev tagging, floating terminal, screenshot capture with annotations.

Install

npm install @unplatform/unui

Quick Start

import { initUnui } from "@unplatform/unui";

initUnui({ enabled: true });
// Press Ctrl+Shift+D to activate

With Vite Plugin

The Vite plugin adds server-side features: persistent PTY terminal (with tmux session persistence), tag storage to disk, and screenshot capture saving.

// vite.config.ts
import { unusePlugin } from "@unplatform/unui/vite";

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

Plugin Options

unusePlugin({
  command: "claude",        // CLI command to spawn in terminal (default: "claude")
  initialPrompt: "...",     // Override the initial prompt sent to the CLI
  idleTimeoutMs: 1800000,   // Tmux session idle timeout in ms (default: 30min)
});

The plugin also looks for a prompt template file at .unui/prompt.txt (or .devtools/prompt.txt for backward compat) in your workspace root.

With Svelte

Inject data-component, data-file, and data-line attributes on HTML elements for enhanced inspector metadata:

// svelte.config.js
import { componentMetadataPreprocessor } from "@unplatform/unui/svelte";

export default {
  preprocess: [
    componentMetadataPreprocessor({ monorepoRoot: process.cwd() }),
  ],
};

Configuration

initUnui({
  // Activation
  enabled: true,                    // boolean or () => boolean
  shortcut: "ctrl+shift+d",        // keyboard shortcut to toggle

  // Theme
  theme: "auto",                    // "auto" | UnuiTheme object
  // "auto" inherits from host CSS vars with fallback defaults.
  // Provide an object to override specific tokens:
  // theme: { bg: "#1a1a2e", accent: "#6366f1", ... }

  // Features (all default to true except banner)
  features: {
    terminal: true,
    chat: true,
    capture: true,
    tagging: true,
    banner: false,
  },

  // Tag storage
  tagStorage: "server",            // "server" | "localStorage" | TagStorageAdapter
  // "server" persists tags via the Vite plugin with localStorage fallback.
  // "localStorage" is client-only, no server calls.
  // Pass a custom TagStorageAdapter for your own backend.

  // Dev statuses (shown in banner when features.banner = true)
  devStatuses: {
    "mock-data": { label: "Mock Data", color: "#f59e0b", description: "Using mock API" },
  },

  // Paths (for Vite plugin integration)
  tagsPath: "/__unui-tags",
  wsPath: "/__terminal",
  capturePath: "/__save-capture",

  // Class filtering in inspector
  classFilterPatterns: [/^s-/, /^svelte-/],  // auto-detected for Svelte
});

Theme Customization

unui uses CSS custom properties prefixed with --unui-. When theme: "auto" (the default), it maps from common host app variables with sensible fallbacks:

Token	CSS Variable	Fallback
Background	`--unui-bg`	`#1a1a2e`
Background Hover	`--unui-bg-hover`	`#222240`
Input Background	`--unui-bg-input`	`#16162a`
Text	`--unui-text`	`#e0e0e0`
Text Dim	`--unui-text-dim`	`#888`
Accent	`--unui-accent`	`#6366f1`
Border	`--unui-border`	`#333`
Error	`--unui-error`	`#ef4444`
Success	`--unui-success`	`#22c55e`
Mono Font	`--unui-font-mono`	system monospace stack

Override any token in your app's CSS:

:root {
  --unui-accent: #10b981;
  --unui-bg: #0f172a;
}

Or pass a theme object:

initUnui({
  theme: {
    bg: "#0f172a",
    accent: "#10b981",
    // ... other tokens
  },
});

Custom Tag Storage

Implement the TagStorageAdapter interface for custom persistence:

import type { TagStorageAdapter, DevTag } from "@unplatform/unui";

const myAdapter: TagStorageAdapter = {
  async load(): Promise<DevTag[]> {
    const res = await fetch("/api/tags");
    return res.json();
  },
  async save(tags: DevTag[]): Promise<void> {
    await fetch("/api/tags", {
      method: "POST",
      body: JSON.stringify(tags),
    });
  },
};

initUnui({ tagStorage: myAdapter });

Keyboard Shortcuts

Shortcut	Action
`Ctrl+Shift+D`	Toggle inspector overlay
`Escape`	Close inspector / cancel selection

Exports

Entry Point	Description
`@unplatform/unui`	Browser-side devtools (framework-agnostic)
`@unplatform/unui/vite`	Vite plugin (terminal server, tag persistence, capture)
`@unplatform/unui/svelte`	Svelte preprocessor (component metadata injection)

License

MIT

Dependencies

ID	Version
html-to-image	^1.11.13

Development dependencies

ID	Version
@biomejs/biome	^2.0.0
@types/ws	^8.18.1
@xterm/addon-fit	^0.11.0
@xterm/addon-web-links	^0.12.0
@xterm/xterm	^6.0.0
node-pty	^1.1.0
svelte	^5.51.0
tsup	^8.4.0
typescript	^5.9.0
vite	^7.3.1
ws	^8.19.0

Peer dependencies

ID	Version
@xterm/addon-fit	^0.11.0
@xterm/addon-web-links	^0.12.0
@xterm/xterm	^6.0.0
node-pty	^1.0.0
svelte	>=4.0.0
vite	>=6.0.0
ws	^8.0.0

Details

npm

2026-02-28 20:30:56 +00:00

MIT

latest

59 KiB

Assets (1)

unui-0.1.0.tgz 59 KiB

Versions (1) View all

0.1.0

2026-02-28