@sdaitzman/prototype-devbar

A dark, sticky-bottom dev bar for React prototypes — with a nutrition label dialog (owner, coverage scope, fidelity, data source), a live performance popover (FPS + page-load timings), a git-branch popover (last 10 commits), and a Configure popover whose settings persist to localStorage keyed by the prototype's version.

Framework-agnostic: works in Next.js (App Router) and Vite out of the box, and in any other React host that supports Tailwind v4. Drop one <PrototypeDevBar /> into your prototype and stakeholders always know what they're looking at.

Install

npm install @sdaitzman/prototype-devbar @base-ui/react lucide-react

Peers: React 19+, Tailwind v4 (@import "tailwindcss"). No Next-specific runtime APIs.

Use

Full step-by-step guide: INTEGRATING.md. TL;DR:

// app/globals.css (Next)  OR  src/index.css (Vite)
@import "tailwindcss";
@import "@sdaitzman/prototype-devbar/styles.css";

// Wrap your root once
import { PrototypeConfigProvider } from "@sdaitzman/prototype-devbar";
import pkg from "../package.json";

<PrototypeConfigProvider version={pkg.version} owner="Your team">
  {children}
</PrototypeConfigProvider>

// Mount the bar somewhere top-level
import {
  PrototypeDevBar,
  getGitInfo,
  getEnableMode,
} from "@sdaitzman/prototype-devbar";
import snapshot from "../prototype-devbar.snapshot.json"; // tracked file
import pkg from "../package.json";

<PrototypeDevBar
  git={getGitInfo(snapshot)}
  enabled={getEnableMode(snapshot)}
  appName={pkg.name}
  version={pkg.version}
/>

// package.json — refresh the snapshot before each build
"scripts": {
  "prebuild": "schema-capture-git-info --out ./prototype-devbar.snapshot.json",
  "predev":   "schema-capture-git-info --out ./prototype-devbar.snapshot.json"
}

Commit prototype-devbar.snapshot.json to your repo. It holds the build-time-resolved enable flag and the branch/commit list, so cloning without git history (zip downloads, shallow CI clones) still yields an accurate bar. The file is regenerated automatically before each dev/build run.

Enable flag

PrototypeDevBar is off by default. Set PROTOTYPE_DEVBAR_ENABLED in your .env (or in your host's deploy-env settings) before running npm run dev / npm run build:

| Value | Behavior | | ---------- | ----------------------------------------------------------------------- | | true | Always render the bar. | | URLPARAM | Render only when ?PROTOTYPE_DEVBAR_ENABLED=true is in the page URL. | | (unset) | Never render the bar. |

The flag name is the same across every framework — Next, Vite, plain React, anywhere else. The capture bin runs in Node during predev / prebuild, reads process.env.PROTOTYPE_DEVBAR_ENABLED, and bakes the resolved value into prototype-devbar.snapshot.json. The runtime imports the snapshot and reads the mode from it — never touching process.env or import.meta.env. So there's no VITE_ / NEXT_PUBLIC_ prefix to remember, and disabled builds tree-shake cleanly because the resolved mode is a string constant inside a statically-imported JSON.

For non-env gating (feature flag service, user role, URL-based override), pass the enabled prop directly: <PrototypeDevBar enabled="url-param" ... />. The prop takes precedence over whatever the snapshot says.

URLPARAM is the right pick for shareable demo deploys: the bar stays out of the rendered HTML for normal visitors, but anyone who appends ?PROTOTYPE_DEVBAR_ENABLED=true gets it back. Useful when sharing a prototype URL with a stakeholder where the bar is for you and not them.

Features

• Nutrition label — the five transparency fields (Owner / Coverage scope / Fidelity / Data source / Last updated) surface as a dialog, ensuring every prototype has them.
• Configure popover — your registered extraFields={[…]} (toggles, text, color, select, checkbox-group) plus an "Open nutrition label on load" toggle. Per-field reset dots; versioned localStorage persistence.
• Performance — live FPS/jank chart (60s rolling window, configurable timescale), TTFB/FCP/LCP/DCL/Load timings.
• Branch popover — HEAD SHA and last 10 commits captured at build time via the schema-capture-git-info bin. Only absolute ISO timestamps are stored; "9 days ago" is computed at runtime so a built-and-deployed snapshot stays accurate as time passes.
• Extras API — register consumer-specific settings that appear in the Configure popover and read back with useExtraField(key).

License

MIT © Sam Daitzman