Skip to content
Sightmap

@sightmap/react

@sightmap/react is the framework adapter — the bootstrap path for any React app using React Router 7. Mount one provider, decorate selectors in source, and the codegen produces a .sightmap/ directory derived from your router and your JSX.

Mount the provider once. An agent does the rest.

Install

Section titled “Install”
Terminal window
pnpm add @sightmap/react @sightmap/sightmap

@sightmap/sightmap is a peer dep — installed alongside.

Bootstrap

Section titled “Bootstrap”

Run the codegen against an empty .sightmap/:

Terminal window
npx sightmap-react gen

gen AST-scans your source for data-sightmap attributes, reads your React Router config to discover routes, and writes one feature-scoped YAML file per top-level route. Each file is seeded with:

  • Structural fields the codegen owns — name, route, selector, children. Refreshed from source on every run.
  • Commented TODO blocks for agent-authored fields — memory, intent, requests. Valid YAML (the comments parse cleanly until you uncomment them) and emitted only on first generation.

After the first run, the CLI prints a list of files written and which to open first.

Decorate

Section titled “Decorate”

Mark the elements an agent needs to find with a data-sightmap attribute:

<button data-sightmap="LoginButton" onClick={signIn}>
  Sign in
</button>


<form data-sightmap="LoginForm">
  {/* ... */}
</form>

The string is the canonical component name. The codegen reads it, generates a stable selector ([data-sightmap="LoginButton"]), and emits an entry under the appropriate view’s components:.

You don’t author selectors. You name components, and the codegen handles the rest.

Mount the provider

Section titled “Mount the provider”
import { SightmapProvider } from "@sightmap/react";


export function App() {
  return (
    <SightmapProvider runtimeIntrospection="dev">
      <YourApp />
    </SightmapProvider>
  );
}

The provider:

  • Loads the merged sightmap (from /__sightmap__/sightmap.json in dev, or a static /sightmap.json in prod).
  • Installs window.__SIGHTMAP__ so an agent can introspect the running app: walkTree, inspectAt, getCurrentView, match, findByDataSightmap.

runtimeIntrospection="dev" exposes the API in development only. Pass "always" to opt in for production builds.

Vite plugin

Section titled “Vite plugin”
vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { sightmap } from "@sightmap/react/vite";


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

The plugin registers a /__sightmap__/sightmap.json endpoint in dev so the runtime provider can fetch the merged sightmap. It does not write to .sightmap/ — generation is always explicit, via sightmap-react gen.

Maintain

Section titled “Maintain”

Re-run gen whenever routes or data-sightmap props change:

Terminal window
sightmap-react gen

Idempotent. Structural fields refresh from source; agent-authored fields, comments, and ordering survive untouched. Running against an unchanged repo writes nothing and prints sightmap: up to date.

In CI:

Terminal window
sightmap-react gen --check

Dry-run. Exits 1 if .sightmap/ is out of date — i.e. if a route or selector landed in source but nobody re-ran gen. Pair with sightmap check --strict for full schema + drift coverage.

Terminal window
sightmap-react gen --diff

Prints a unified diff of would-be changes; writes nothing.

File layout

Section titled “File layout”
.sightmap/
  login.yaml          # codegen-scaffolded, agent-curated: view + components for /login
  dashboard.yaml      # codegen-scaffolded, agent-curated
  shared.yaml         # codegen-scaffolded: cross-route components
  extras.yaml         # agent-only: non-derivable additions

The codegen owns one file per top-level route group, plus shared.yaml for cross-route components. Agents are free to add more files (e.g. extras.yaml) for things that aren’t derivable from source — those are never touched by gen.

--live runtime discovery (optional)

Section titled “--live runtime discovery (optional)”

If the Vite plugin is running, pass --live <url>:

Terminal window
npx sightmap-react gen --live http://localhost:5173

gen additionally fetches the runtime snapshot. Views present at runtime but not discovered by the static AST scan surface as react.live-only-view info diagnostics. gen does not auto-emit YAML for them — the curator hand-authors a file per the diagnostic’s hint. The static path remains the source of truth; --live is a discovery aid.

See @sightmap/react on npm for the full v0.1 surface and the v0.2 roadmap (Next.js, Remix, TanStack Router adapters).