@plyaz/devtools-extension

Comprehensive developer tools panel for debugging and monitoring Plyaz applications.

Installation

pnpm add @plyaz/devtools-extension

Quick Start

import { PlyazDevtools } from '@plyaz/devtools-extension';
import '@plyaz/devtools-extension/styles.css';

// In your app
<PlyazDevtools
  config={{
    enabled: process.env.NODE_ENV === 'development',
  }}
  plyaz={plyazInstance}  // from usePlyaz()
  intl={{ locale, messages }}  // optional: from next-intl
/>

Toggle with Ctrl+Shift+D or click the floating button.

Configuration

import type { DevtoolsConfig } from '@plyaz/devtools-extension';

const config: DevtoolsConfig = {
  enabled: true,
  position: 'bottom',           // 'bottom' | 'left' | 'right'
  defaultHeight: 400,
  defaultWidth: 400,
  theme: 'dark',                // 'dark' | 'light'

  tabs: {
    enabled: ['*'],             // Enable all, or specific: ['streaming', 'api']
    disabled: [],               // Disable specific tabs
    favorites: ['streaming'],   // Pinned tabs
    defaultTab: 'streaming',
  },

  storage: {
    adapter: 'indexeddb',       // 'indexeddb' | 'memory'
    retentionDays: 1,
    maxItems: 200,
  },

  shortcuts: {
    toggle: 'Ctrl+Shift+D',
    search: 'Ctrl+K',
    close: 'Escape',
  },

  security: {
    readOnly: false,
    sensitiveKeys: ['password', 'token', 'secret', 'key', 'auth'],
  },

  hooks: {
    onOpen: () => {},
    onClose: () => {},
    onTabChange: (tab) => {},
    onError: (error) => {},
  },
};

Keyboard Shortcuts

| Shortcut | Action | |----------|--------| | Ctrl+Shift+D | Toggle devtools panel | | Ctrl+K | Open tab search (command palette) | | Escape | Close panel or search | | 1-9 | Quick switch to tab by number | | [ / ] | Previous / Next tab |

Available Tabs

Data Flow

• Streaming - Real-time SSE message monitoring with channel filtering
• Stores - Zustand store state inspection with time-travel debugging
• Actions - Track store actions/mutations with replay capability
• API - HTTP request/response inspector with cURL export
• Events - Core event system monitoring with re-emit
• Errors - Error tracking with resolution workflow
• Console - Intercepted console output viewer

Infrastructure

• Services - Frontend/backend service status and controls
• Uploads - File upload progress monitoring
• Storage - Browser storage inspection (localStorage, sessionStorage, cookies, IndexedDB)
• Config - Application configuration viewer

Quality

• Security - Security best practices audit
• Compliance - Regulatory compliance status (GDPR, CCPA, SOC2)
• Accessibility - a11y audit with WCAG references

Observability

• Observability - Metrics, traces, and spans viewer

Development

• Playground - API endpoint testing sandbox
• Feature Flags - Live feature flag management
• Mocking - Request mocking and interception
• Explorer - Package exports browser

Framework

• SSR - Server-side rendering and hydration metrics
• Routes - Next.js route inspection
• I18n - Internationalization tools with missing translation detection
• React - Component render tracking and props inspection

Help

• Shortcuts - Keyboard shortcut reference

Programmatic Access

Hooks

import { useDevtools, useDevtoolsAppConfig } from '@plyaz/devtools-extension';

function MyComponent() {
  const {
    isOpen,
    activeTab,
    setActiveTab,
    apiRequests,
    events,
    errors,
    streamMessages,
  } = useDevtools();

  const { frontendConfig, packageExports } = useDevtoolsAppConfig();
}

Data Persistence

DevTools persists data to IndexedDB across page refreshes:

• API requests
• Events
• Stream messages
• Errors
• Actions
• Console logs
• State snapshots

Auto-cleanup based on storage.retentionDays config.

Panel Positions

position: 'bottom' (default)
┌─────────────────────────────────────┐
│           Your App                  │
├─────────────────────────────────────┤
│  Tab Groups  │  Tab Content         │
└─────────────────────────────────────┘

position: 'left'
┌──────────┬──────────────────────────┐
│ Tabs     │       Your App           │
└──────────┴──────────────────────────┘

position: 'right'
┌──────────────────────────┬──────────┐
│       Your App           │    Tabs  │
└──────────────────────────┴──────────┘

Scripts

pnpm build          # Full build: clean + JS + CSS + types
pnpm dev            # Watch mode for development
pnpm lint           # Run ESLint
pnpm lint:fix       # Auto-fix lint issues
pnpm format         # Format with Prettier
pnpm type:check     # TypeScript type checking
pnpm test           # Run tests
pnpm test:watch     # Run tests in watch mode
pnpm example        # Run the example Next.js app

Troubleshooting

DevTools Not Appearing

• Check config.enabled is true
• Verify environment is development
• Try Ctrl+Shift+D to toggle

No Data in Tabs

• Ensure Plyaz Core is initialized
• Check that services are configured and enabled
• Verify streaming endpoint is accessible

Performance Issues

• Reduce storage.maxItems
• Set storage.retentionDays: 1
• Clear old data periodically
• Disable unused tabs in tabs.disabled