Skip to content
forms

Devtools

Inspect live form values, errors, writes, and plugins in an on-page panel built entirely as a plugin.

Have you noticed that dashed line around every form in these docs so far?

That isn’t a custom docs widget or a special hook baked into React or Solid. It’s @lunarhue/forms-devtools, an on-page inspector built as a regular @lunarhue/forms-core plugin. Click any form’s name tag (or the dock in the corner) on a wider screen to poke around, or toggle it from the header.

Installing devtools()

Install @lunarhue/forms-devtools alongside your adapter:

bun add @lunarhue/forms-devtoolsnpm install @lunarhue/forms-devtoolspnpm add @lunarhue/forms-devtoolsyarn add @lunarhue/forms-devtools

Then add devtools() to your shared createForms plugins (or to a single form definition). Because devtools() never checks NODE_ENV on its own, gate it with your bundler’s dev flag so the entire package tree-shakes out of production builds:

import { createForms } from "@lunarhue/forms-solid";
import { devtools } from "@lunarhue/forms-devtools";

const dev = import.meta.env.DEV;

export const forms = createForms({
  plugins: [dev && devtools()],
});

Plugin arrays ignore false, null, and undefined, so in production devtools is dropped completely. Even when installed, the panel UI itself lives in a separate lazy-loaded chunk that only downloads the first time a form’s enabled option reads true.

What you can inspect

Once a form mounts with devtools(), it registers with the page until it unmounts:

  • Form outlines and tags: every mounted form gets a dashed outline labeled with its id (or form 1, form 2 when the adapter generated the ID). Click any tag to select that form in the panel.
  • Fields tab: shows the full value tree with icon flags for each field (hover a flag to see its details, like active errors, baseline vs. current value, or the last write). Filter by field name or toggle errors-only, hover a row to outline its DOM elements on the page, click the pointer icon to scroll an element into view, or click a row to inspect its value, baseline, and write history.
  • Inspect mode: turn on the inspect button, or hold Alt while moving the pointer. Hovering any input (or its <label>) opens a live card for that field; clicking pins it and selects its row in the panel.
  • Log tab: lists the form’s last 500 writes and submissions newest first, showing each write’s cause (user, reset, rebase, or plugin name) and submissions aborted by a reset.
  • Plugins tab: lists every installed plugin in hook execution order alongside its form meta and exposed API.

On narrow viewports (640px wide and below), the panel unmounts automatically so phones never get a dock, outlines, or hover inspection.

Toggling the panel at runtime

If you want a toggle in your app (like the switch in this site’s header, or a hidden flag for staging builds), pass enabled as a function and call syncDevtools() whenever that flag changes:

import { devtools, syncDevtools } from "@lunarhue/forms-devtools";

let showPanel = true;

export const toggleDevtools = (on: boolean) => {
  showPanel = on;
  syncDevtools();
};

export const devPlugin = devtools({
  enabled: () => showPanel,
  onDisable: () => {
    showPanel = false;
  },
});

When onDisable is provided, the panel adds a Turn off devtools action that calls it. Turning the panel off unmounts the UI and clears the buffered write and submission logs.

Yes, the whole panel is just a plugin

One reason @lunarhue/forms-devtools exists is to show how far the plugin API goes. Nothing in @lunarhue/forms-core, @lunarhue/forms-react, or @lunarhue/forms-solid has special devtools hooks.

Under the hood, devtools() is built with the exact same primitives documented in Writing plugins:

  • onActive registers and unregisters the store as the form mounts and unmounts.
  • onWrite and onSubmitted feed the ring buffer behind the Log tab.
  • ctx.installed supplies the plugin list, hook order, and metadata for the Plugins tab.
  • trackElements() listens to element registrations from any adapter so inspect mode and row highlights work across React and Solid alike.
  • The panel itself is a standalone Preact UI rendered inside a Shadow DOM (so your app’s CSS never collides with it), reading snapshots on animation frames while open without ever subscribing to your store.

If a full interactive inspector can live outside core as a plain plugin, your own app-specific plugins (analytics, autosave banners, audit logs, custom inspectors) can build on the exact same foundation.

Last updated