DevTools

StateMesh provides an in-app DevTools dock for development and QA. It includes tabs for state, actions, resources, mutations, forms, URL state, components, profiler, diagnostics, and raw events.

Quick Setup

import { StateMeshDevtools } from "statemesh-core/devtools";

function App() {
  return (
    <StateMeshProvider mesh={mesh}>
      <AppContent />
      <StateMeshDevtools
        mesh={mesh}
        mask={["auth.token", "user.email"]}
        previewBytes={2000}
        defaultView="overview"
        theme="light"
      />
    </StateMeshProvider>
  );
}

Props

Prop	Type	Default	Description
mesh	Mesh	Required	The mesh instance
mask	string[]	[]	Paths to mask in the UI
previewBytes	number	2000	Max bytes for value previews
defaultView	DevtoolsView	"overview"	Initial tab
theme	"light" | "dark"	"light"	UI theme
hidden	boolean	false	Start hidden
limit	number	200	Max events in timeline
logActiveMessage	boolean	true	Log activation message to console

Tabs

Tab	Shows
Overview	Health counts, active resources, pending transactions
State	Current state snapshot
Actions	Action and transaction timeline
Resources	Cache entries with refetch/invalidate controls
Mutations	Mutation status and offline queue
Forms	Values, errors, dirty, touched, steps
URL	Current URL state
Components	Tracked React components and their StateMesh usage
Profiler	Performance samples for slow operations
Doctor	Runtime diagnostics
Events	Raw event timeline with search, filters, export

Component Tracking

Wrap UI areas with MeshComponent to track StateMesh usage:

import { MeshComponent } from "statemesh-core";

function ProductScreen() {
  return (
    <MeshComponent name="ProductScreen">
      <ProductFilters />
      <ProductList />
    </MeshComponent>
  );
}

The Components tab shows tracked component names, render counts, and captured StateMesh usages.

Programmatic Access

// Get a safe snapshot
const snapshot = mesh.getDevtoolsSnapshot({
  mask: ["auth.token"],
  previewBytes: 4000
});

// Subscribe to changes
const unsubscribe = mesh.subscribeDevtools(() => {
  console.log(mesh.getDevtoolsSnapshot().summary);
});

Profiler

const slowOps = mesh.getProfilerSamples({
  slowOnly: true,
  minDuration: 16
});

mesh.subscribeProfiler(() => {
  console.table(mesh.getProfilerSamples({ limit: 10 }));
});

Doctor Diagnostics

const report = mesh.doctor({
  stateSizeWarningBytes: 250_000,
  queuedMutationAgeWarning: "5m",
  staleResourceWarning: "5m",
  slowOperationWarningMs: 16
});

Doctor reports: large serialized state, resources without tags, resource errors, stale cache, stuck mutations, unresolved form errors, slow operations.

Logger Plugin

import { loggerPlugin } from "statemesh-core/devtools";

mesh.use(loggerPlugin({
  enabled: process.env.NODE_ENV === "development",
  mask: ["user.email", "auth.token"]
}));

Important Notes

TIP

DevTools is tree-shakeable. Import from statemesh-core/devtools — it's not included in the main bundle.

WARNING

mask is applied before rendering state, forms, URL, resources, mutations, and exports. Sensitive paths are never displayed.

Next Steps

• Performance — Optimization tips
• Dehydrate & Hydrate — SSR patterns