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} />
    </>
  );
}

To send feedback to the uidex cloud dashboard, pass a project key:

<UidexDevtools
  loadRegistry={loadRegistry}
  projectKey="ux_proj_..."
  endpoint="https://app.uidex.dev"
/>

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.