Getting started

uidex is a static-analysis + runtime tracking system for UIs. The CLI scans your source for data-uidex* attributes and export const uidex = {...} declarations and emits a typed registry (src/uidex.gen.ts) that the runtime SDK consumes to power overlays, the command palette, and acceptance-driven tooling.

This page walks through installing the package, generating the registry, and mounting the SDK in a Next.js or Vite app.

Install

pnpm add uidex

Generate the registry

npx uidex scan

The scanner writes src/uidex.gen.ts (configurable via .uidex.json) — commit this file. Consumers import types from it directly.

A minimal .uidex.json:

{
  "sources": [{ "rootDir": "src" }],
  "output": "src/uidex.gen.ts",
  "flows": ["e2e/**/*.spec.ts"],
  "typeMode": "strict"
}

Mount the SDK

In your app's root layout, render <UidexDevtools>. It handles instance creation, registry loading, and the overlay shell in a single component.

import { UidexDevtools } from "uidex/react";
import { loadRegistry } from "@/uidex.gen";
 
export default function RootLayout({ children }) {
  return (
    <>
      {children}
      <UidexDevtools loadRegistry={loadRegistry} />
    </>
  );
}

uidex is fully client-side: inspecting an element lets you copy its source path, a screenshot, or a markdown snapshot to paste into your own tracker. There is no project key, endpoint, or account. UidexDevtools takes loadRegistry plus an optional config (CreateUidexOptions) and nothing else.

Verify

Annotate one element and one page:

import type { Uidex } from "@/uidex.gen";
 
export const uidex = {
  page: "home",
  acceptance: ["User can navigate to settings"],
} as const satisfies Uidex.Page;
 
export default function HomePage() {
  return (
    <main>
      <button data-uidex="settings-link">Settings</button>
    </main>
  );
}

Re-run the scanner:

npx uidex scan

Open your app and press ⌘K (or Ctrl+K) — the command palette lists every registered entity, including the new home page and settings-link element.

Next steps

• Entity model — the eight kinds and how each is discovered.
• DOM annotations — data-uidex* attributes and authoring rules.
• export const uidex — the module-scoped authoring surface.
• Playwright flows — wire end-to-end tests into the registry.
• uidex scan — full CLI reference.