v0.12.1 · MIT · 0 runtime deps

A bottom bar that hosts your tools.

An extensible, low-overhead in-app developer toolbar for React. The package is chrome plus hosting — metrics, flags, overlays and diagnostics are opt-in extensions, each on its own subpath with its own bundle.

Get started Read the docs

React 18 / 19peerLight DOMtailwind & css-in-js workSSR-safeclient-only bar⌘⇧.show / hide on Mac

the bar

env stagingcmds aggregated◆ UI Facelift 2026flags6theme 14mem23 MBdelay—jank0.0%net0hydrNAtailwind

⌘Kuser internal⋮

At real size, with the run of chips clipping into ⋮ exactly as the shell collapses overflow on a narrow viewport. The shell sorts and collapses the items you give it, hosts one panel at a time, remembers preferences and isolates failures. A compact or panel slot that throws becomes a retry chip; an overlay that throws is reported without one.

zero runtime deps

React and react-dom are peers; package runtime adds nothing. ext/a11y uses optional axe-core.

restyleable, no !important

Core CSS lives in @layer dev-toolbar, so unlayered author CSS wins at any specificity.

failure-isolated

One extension throwing never takes the bar down — and the rest keeps working.

light DOM

No shadow root, so Tailwind, CSS-in-JS and your design system work inside extensions.

logical properties

dir="rtl" mirrors the bar, the ⋮ popup and every first-party extension.

ssr-safe

Children server-render untouched; the bar is client-only, so nothing can mismatch.

install

$ npm install @nejcm/dev-toolbar# react & react-dom 18 or 19 are required peers# axe-core (ext/a11y) and @testing-library/react (/testing)# are optional peers — install them only if you use those

import { DevToolbar } from "@nejcm/dev-toolbar";import { environment } from "@nejcm/dev-toolbar/ext/environment";import { metrics } from "@nejcm/dev-toolbar/ext/metrics"; // Built once, at module scope — never inside render.const extensions = [environment({ context: { environment: "staging" } }), metrics()]; export function Root() {  return (    <DevToolbar extensions={extensions}>      <App />    </DevToolbar>  );}

// Pad your content out of the way…import { DevToolbarInset } from "@nejcm/dev-toolbar"; <DevToolbarInset><App /></DevToolbarInset>; /* …or by hand. The shell publishes bar + open panel height on <html>. */.my-layout { padding-bottom: var(--dev-toolbar-height, 0px); }

// Gate on the value that names the deployment, not NODE_ENV:// a staging build IS a production build.const Toolbar = import.meta.env.VITE_ENV === "production"  ? null  : lazy(() => import("./DevTools")); // The dynamic import folds away, so the code leaves the prod bundle.// Caveat: the chunk is not there at boot — nothing in it runs// before the app's first render.

nine first-party extensions

Each one an opt-in subpath with its own bundle. Import none and the bar hosts only your tools.

ext/metrics

Memory, interaction delay, jank and in-flight network, plus your own collectors. Each built-in degrades on its own where a browser API is missing.

docs →

ext/environment

Environment, release, commit and actor context — all supplied by you, all redacted, with production coloured like production.

docs →

ext/flags

Your feature flags, with local overrides that survive a reload and a ?dtb-flags=reset kill switch.

docs →

ext/command-menu

A ⌘K palette over every command the toolbar has aggregated. Leave it out and build your own with useDevToolbar().getCommands().

docs →

ext/overlays

Layout boxes, a column grid, an element inspector and focus order — drawn over your page, never intercepting a click.

docs →

ext/diagnostics

One snapshot for a bug report: the page, long tasks, a tail of console errors and every other extension's diagnostics.

docs →

ext/theme-editor

Live design-token editing, with the app's own value next to your edit, and CSS, a recipe or a design-tokens export on the way out.

docs →

ext/a11y

axe-core violations grouped by impact, on demand and never on a timer, with click-to-highlight. Its axe-core integration is an optional peer.

docs →

ext/agent

The bar's state and commands on a global, for an in-page agent to read rather than scrape. Running commands is a second opt-in.

docs →

/kit

types, helpers, data-dtb-kind CSS, native-looking controls

/runtime

event bus, ring buffers, throttled store, redact()

/testing

renderWithToolbar, fake layout, mock bus — needs the optional @testing-library/react peer

/styles.css

the shell stylesheet, if you would rather import it

write your own

// An extension is a plain object.// No registry, no class, no plugin API.const build: DevToolbarExtension = {  id: "build-info",  label: "Build",  align: "end",  compact: ({ openPanel }) => (    <button data-dtb-part="trigger" onClick={openPanel}>      {import.meta.env.VITE_COMMIT?.slice(0, 7) ?? "dev"}    </button>  ),  panel: () => <BuildDetails />,};

commands

Add them and the extension appears in the ⌘K palette. Contract v2 commands may declare an input schema and resolve a result.

diagnostics()

What you return lands in somebody's bug report — and they read the exact text first.

start(api)

Background work with an AbortSignal that fires on teardown.

two rules that save an afternoon

Build the object once, at module scope. And treat hidden as does not exist here, not unpainted.

documentation

api.md

The root entry: every <DevToolbar> prop, the toggle shortcut, the ⋮ menu, the escape hatches and every published type

extension-contract.md

The object you write, the slot props, start(api), and the two lifecycle rules that bite

kit.md

The severity vocabulary, storage/poll/style helpers, data-dtb-kind, the React controls and the presentation vocabulary

runtime.md

Event bus, ring buffers, throttled store, redact() anchored and redactText() scanning

embedding.md

A third-party devtool on the bar: the four-line recipe, the CSS rule, embed(), and one chip for a whole devtools shell

styling.md

Tokens, the data-dtb-part list, classNames — and why none of it needs !important

testing.md

renderWithToolbar, makeExtension(), the fake layout, the mock bus and the Jest caveats

ssr.md

Why the bar cannot mismatch on hydration, and the one Next.js app-router rule

architecture.md

What the shell guarantees, why the boundaries sit where they do, and the known gaps

adr/

Decision records: plain-object extensions, light DOM, contract-version policy, per-extension bar presentation

Every extension directory carries a README too — the developer's view of the same nine: the files in it, what it owns, and the decisions that bite.

contributing

the one command that matters

$ bun run verify

format:check → typecheck → lint → knip → build → check:package → test. If it passes locally it passes in CI.

try a change for real

$ bun run playground

A Vite app on :5273 consuming the built dist through file:../.. exactly as a published consumer does.

house rules

Bun, not npm. Zero runtime dependencies is a rule. Core never imports runtime/ or ext/. Conventional Commits, enforced — the PR title is the message that lands.

Put your own devtools where you already look.

$ npm install @nejcm/dev-toolbarRead the README