Skip to content

README.md

Latest commit

 

History

History
182 lines (136 loc) · 7.24 KB

README.md

File metadata and controls

182 lines (136 loc) · 7.24 KB
Raw

@localmode/devtools

npm license

Docs UI Components Blocks & Apps

DevTools instrumentation and React hooks for debugging and monitoring LocalMode applications. See model cache, VectorDB stats, inference queue metrics, pipeline traces, and live event streams — all without any telemetry. Works in any browser.

Installation

pnpm add -D @localmode/devtools

Quick Start

Headless (no UI)

import { enableDevTools } from '@localmode/devtools';

if (process.env.NODE_ENV === 'development') {
  enableDevTools();
}

React hooks (recommended React integration)

Subscribe to any bridge data domain from your own components via the @localmode/devtools/react subpath:

import { enableDevTools } from '@localmode/devtools';
import { useDevToolsQueueStats, useDevToolsEvents } from '@localmode/devtools/react';

enableDevTools();

function Observability() {
  const queues = useDevToolsQueueStats();
  const events = useDevToolsEvents({ types: ['vectordb'], limit: 50 });
  // render…
}

Widget (removed in v3.0.0)

Removed: the prebuilt DevToolsWidget overlay and its @localmode/devtools/widget subpath were removed in v3.0.0. Its replacements shipped at localmode.ai:

  • @localmode/devtools/react hooks — subscribe to any bridge data domain and render it in your own UI.
  • ui/devtools registry family — four copy-owned, theme-aware primitives (inference-queue-monitor, event-log-viewer, pipeline-run-inspector, model-cache-table) that render these hooks' output (npx shadcn add @localmode/ui/devtools).
  • ui/blocks/devtools-drawer — the composed six-tab drawer (Queue / Events / Pipeline / Models / Device / VectorDB, off by default and zero-overhead when closed): npx shadcn add @localmode/ui/blocks/devtools-drawer.

The data layer (enableDevTools(), the window.__LOCALMODE_DEVTOOLS__ bridge, and all collectors) is unchanged — only the widget UI was removed.

React Hooks

All hooks ship from @localmode/devtools/react (ESM + CJS). The main entry stays React-free — react/react-dom remain optional peer dependencies needed only for the /react hooks.

Hook Returns Backing data
useDevToolsBridge() DevToolsBridge | null The live bridge object (base hook)
useDevToolsStatus() { available, enabled } Bridge presence + enabled flag
useDevToolsQueueStats() Record<string, QueueStats> registerQueue() stats
useDevToolsEvents(options?) DevToolsEvent[] Event buffer; optional { types, limit } filtering
useDevToolsModelCache() Record<string, ModelCacheInfo> modelLoad/modelLoadError events
useDevToolsPipelineRuns() Record<string, PipelineSnapshot> createDevToolsProgressCallback()
useDevToolsVectorDBs() Record<string, VectorDBSnapshot> VectorDB event aggregates
useDevToolsStorage() StorageQuotaSnapshot | null Storage quota poll
useDevToolsCapabilities() DeviceCapabilitiesSnapshot | null One-shot capability detection

Guarantees:

  • Immutable snapshots — slice hooks return fresh frozen-in-time copies per bridge notification (the bridge mutates its objects in place; snapshots never alias them). useDevToolsBridge() is the one exception: it returns the live bridge object.
  • SSR-safe — no window access during server render; hooks render inert values (null, empty records/arrays, { available: false, enabled: false }) on the server without throwing.
  • Inert when absent, preserved when disabled — with devtools never enabled, hooks return referentially stable frozen inert constants. After disableDevTools(), useDevToolsStatus() reports { available: true, enabled: false } and slice hooks keep returning the last collected snapshots.
  • Late-enable attachment — a hook mounted before enableDevTools() attaches automatically when the bridge appears (package-internal lifecycle signal); no remount needed.
  • Clean lifecycle — subscribe on mount, fully unsubscribe on unmount.

Known limitation: if a duplicate copy of @localmode/devtools (conflicting installs resolving to two module instances) created the bridge, the internal enable signal from the other copy may not reach this copy's hooks immediately; hooks still attach on the next React re-subscribe since they re-check window on every subscription.

Headless API

enableDevTools(options?)

Initialize all collectors and create the window.__LOCALMODE_DEVTOOLS__ bridge.

enableDevTools({
  eventBufferSize: 500,           // Max events in circular buffer (default: 500)
  storagePollingIntervalMs: 5000, // Storage quota poll interval (default: 5000)
});

disableDevTools()

Unsubscribe all collectors, stop polling, preserve last snapshot.

isDevToolsEnabled()

Returns true if DevTools instrumentation is currently active.

registerQueue(name, queue)

Register an InferenceQueue for live monitoring (the useDevToolsQueueStats() hook / the drawer's Queue tab).

import { createInferenceQueue } from '@localmode/core';
import { registerQueue } from '@localmode/devtools';

const queue = createInferenceQueue({ concurrency: 1 });
const unsubscribe = registerQueue('embedding', queue);

createDevToolsProgressCallback(name)

Create a pipeline progress callback (surfaced by the useDevToolsPipelineRuns() hook / the drawer's Pipeline tab).

import { createPipeline } from '@localmode/core';
import { createDevToolsProgressCallback } from '@localmode/devtools';

const pipeline = createPipeline('rag-ingest')
  .step('chunk', chunkFn)
  .step('embed', embedFn)
  .build();

await pipeline.run(input, {
  onProgress: createDevToolsProgressCallback('rag-ingest'),
});

Bridge Data Domains

The bridge collects six data domains — one per /react hook (and one per tab of the composed ui/blocks/devtools-drawer):

Domain Shows Hook Data Source
Models Cached models, load times, status useDevToolsModelCache() globalEventBus modelLoad events
VectorDB Collections, adds, searches, deletes useDevToolsVectorDBs() globalEventBus VectorDB events
Queue Pending, active, completed, latency useDevToolsQueueStats() queue.on('stats')
Pipeline Step progress, timing, status useDevToolsPipelineRuns() onProgress callbacks
Events Live event stream with filtering useDevToolsEvents() globalEventBus
Device WebGPU, WASM, ChromeAI capabilities useDevToolsCapabilities() detectCapabilities()

Documentation

Full documentation at localmode.dev/docs/devtools.

License

MIT