dev-console/README.md

@lilith/dev-console

Development console helpers for Lilith Platform frontends. A Vite plugin that auto-injects debugging utilities to window.dev in development mode.

Features

• Zero-config: Works out of the box with sensible defaults
• Auto-injection: Automatically injects helpers via Vite plugin
• Storage management: Clear/inspect localStorage and sessionStorage
• App reset: Nuclear option to clear all data and reload
• State inspection: View TanStack Query cache, Redux, and Zustand stores
• Network debugging: Log and track fetch requests in real-time
• TypeScript support: Full type definitions included

Installation

pnpm add @lilith/dev-console

Quick Start

1. Add the Vite Plugin

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { devConsolePlugin } from '@lilith/dev-console';

export default defineConfig({
  plugins: [
    react(),
    devConsolePlugin(),
  ],
});

2. Add TypeScript Support (Optional)

// src/vite-env.d.ts or any .d.ts file
/// <reference types="@lilith/dev-console/global" />

Or add to tsconfig.json:

{
  "compilerOptions": {
    "types": ["@lilith/dev-console/global"]
  }
}

3. Use in Browser Console

Open your browser's developer console and type:

dev.help()  // Show all available commands

Available Commands

Storage

Command	Description
dev.clearStorage()	Clear both localStorage and sessionStorage
dev.clearLocalStorage()	Clear localStorage only
dev.clearSessionStorage()	Clear sessionStorage only
dev.dumpStorage()	Display all storage contents in a table

App Reset

Command	Description
dev.resetApp()	Clear all storage, IndexedDB, caches, service workers, then reload

State Inspection

Command	Description
dev.showQueryCache()	Display TanStack Query cache contents
dev.showAppState()	Display combined app state (Query cache + Redux + Zustand)

Network Debugging

Command	Description
dev.logRequests()	Start logging all fetch requests (returns cleanup function)
dev.showPendingRequests()	Show currently in-flight requests

Usage Examples

Debugging Storage Issues

// See what's in storage
dev.dumpStorage()

// Clear everything and start fresh
dev.clearStorage()

Debugging API Requests

// Start logging requests
const stop = dev.logRequests()

// ... trigger some API calls ...

// Stop logging when done
stop()

Debugging Query Cache

First, expose your QueryClient in your app:

// In your app initialization
import { QueryClient } from '@tanstack/react-query';

const queryClient = new QueryClient();

// Expose for dev-console
if (import.meta.env.DEV) {
  (window as any).__TANSTACK_QUERY_CLIENT__ = queryClient;
}

Then in the console:

dev.showQueryCache()

Full App Reset

When everything is broken and you need a fresh start:

dev.resetApp()
// Clears: localStorage, sessionStorage, IndexedDB, caches, service workers
// Then reloads the page

Plugin Options

devConsolePlugin({
  // Enable/disable the plugin (default: true in dev, false in prod)
  enabled: true,

  // Namespace on window object (default: 'dev')
  namespace: 'dev',
})

Custom Namespace

// vite.config.ts
devConsolePlugin({ namespace: 'debug' })

// In console
debug.help()
debug.clearStorage()

Force Enable in Production

// Not recommended, but possible
devConsolePlugin({ enabled: true })

API Reference

DevConsoleOptions

interface DevConsoleOptions {
  /**
   * Enable/disable the plugin
   * @default true in development, false in production
   */
  enabled?: boolean;

  /**
   * Namespace on window object
   * @default 'dev'
   */
  namespace?: string;
}

DevConsoleHelpers

The interface for window.dev:

interface DevConsoleHelpers {
  // Storage
  clearStorage(): void;
  clearLocalStorage(): void;
  clearSessionStorage(): void;
  dumpStorage(): { localStorage: Record<string, string>; sessionStorage: Record<string, string> };

  // App Reset
  resetApp(): Promise<void>;

  // State
  showQueryCache(): void;
  showAppState(): void;

  // Network
  logRequests(): () => void;
  showPendingRequests(): void;

  // Help
  help(): void;
}

State Integration

TanStack Query

Expose your QueryClient:

window.__TANSTACK_QUERY_CLIENT__ = queryClient;
// or
window.__REACT_QUERY_CLIENT__ = queryClient;

Redux

Expose your store:

window.__REDUX_STORE__ = store;

Zustand

Expose your stores:

window.__ZUSTAND_STORES__ = {
  user: useUserStore,
  settings: useSettingsStore,
};

How It Works

The plugin injects a self-contained script into your HTML during development. This script:

1. Attaches helper functions to window.dev (or your custom namespace)
2. Logs a message indicating helpers are available
3. Is completely removed in production builds (unless explicitly enabled)

Browser Compatibility

• Modern browsers with ES6+ support
• Requires localStorage, sessionStorage, fetch, performance.getEntriesByType
• Optional features: indexedDB.databases(), caches, navigator.serviceWorker

License

MIT