Devtool

The devtool plugin provides a visual debugging panel that shows every request, plugin step, and cached state in your browser's DevTools.

Installation

1. Install the Chrome Extension

Install the Spoosh DevTools extension from the Chrome Web Store.

2. Install the npm package

npm install @spoosh/devtool

Usage

import { Spoosh } from "@spoosh/core";
import { devtool } from "@spoosh/devtool";

const spoosh = new Spoosh<ApiSchema, Error>("/api").use([
  devtool(),
  // other plugins...
]);

Open Chrome DevTools (Cmd+Option+I on Mac, F12 on Windows) and navigate to the Spoosh panel to see your requests.

Features

Feature	Description
Request Timeline	See every request with timing, status, and duration
Plugin Steps	Watch middleware execution order with before/after diffs
State Inspector	Browse cache entries, subscriber counts, refetch or delete
Event Log	View invalidations, refetch triggers, custom plugin events
Status Badges	Pending, success, error, stale, fresh indicators
Filter & Search	Filter by operation type, search by path or query key
Theme Switching	Follows Chrome DevTools theme
Sensitive Headers	Toggle to reveal/hide auth headers with eye icon
Export	Save traces as JSON for analysis
Settings	Max history size, auto-follow, show/hide passed plugins

Options

devtool({
  enabled: true,
  sensitiveHeaders: ["authorization", "cookie", "x-api-key"],
  maxHistory: 50,
  maxMessages: 100,
});

Option	Type	Default	Description
`enabled`	`boolean`	`true`	Enable or disable the devtool
`sensitiveHeaders`	`string[]`	`["authorization", "cookie", "x-api-key", ...]`	Headers to redact in UI and exports
`maxHistory`	`number`	`50`	Maximum number of traces to keep in memory
`maxMessages`	`number`	`100`	Maximum messages per SSE subscription

Production

The plugin automatically disables itself when:

enabled: false is set
Running on server (SSR)

devtool({
  enabled: process.env.NODE_ENV === "development",
});

Plugin Tracing

When devtool is enabled, plugins can emit trace events to show what they're doing. See Tracing for full documentation.

function myPlugin(): SpooshPlugin {
  return {
    name: "my-app:my-plugin",
    operations: ["read"],

    middleware: async (context, next) => {
      const t = context.tracer?.("my-app:my-plugin");

      t?.log("Checking cache");
      t?.return("Cache hit");
      t?.skip("Already in progress");

      return next();
    },

    setup(context) {
      const et = context.eventTracer?.("my-app:my-plugin");

      et?.emit("Plugin initialized");
    },
  };
}

On this page