@flight-framework/devtools

Developer tools for Flight Framework. Inspect routes, debug server actions, and monitor performance.

Table of Contents

• Installation
• Quick Start
• Features
• Configuration
• Browser Extension
• API
• License

Installation

npm install -D @flight-framework/devtools

Quick Start

// flight.config.ts
import { defineConfig } from '@flight-framework/core';
import { devtools } from '@flight-framework/devtools';

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

Access the devtools panel at /__devtools in development mode.

Features

Route Inspector

• View all registered routes
• See route parameters and patterns
• Test route matching

Component Tree

• Visualize component hierarchy
• Inspect props and state
• Highlight rendering

Server Actions

• Log all server action calls
• View request/response payloads
• Measure execution time

Cache Inspector

• View cached entries
• Inspect TTL and hit rates
• Manually invalidate entries

Network Monitor

• Track API requests
• View request/response headers
• Measure response times

Performance

• Core Web Vitals (LCP, FID, CLS)
• Hydration timing
• Bundle size analysis

Contributing

See the main CONTRIBUTING.md for guidelines.

New in V2: Enhanced Panels

Hydration Panel

Track island hydration timing and status:

import { subscribeToHydration, setupHydrationTracking } from '@flight-framework/devtools/hydration';

// Auto-track hydration events
setupHydrationTracking();

// Subscribe to updates
subscribeToHydration((islands, metrics) => {
    console.log(`Hydrated: ${metrics.hydratedCount}/${metrics.totalIslands}`);
    console.log(`Avg time: ${metrics.averageHydrationTime}ms`);
});

Bundle Panel

Monitor chunk loading and sizes:

import { subscribeToBundles, setupBundleTracking } from '@flight-framework/devtools/bundle';

// Auto-track via Performance API
setupBundleTracking();

// Subscribe to updates
subscribeToBundles((chunks, metrics) => {
    console.log(`Total size: ${metrics.totalSize} bytes`);
    console.log(`Loaded: ${metrics.loadedChunks} chunks`);
});

Enhanced Cache Panel

Advanced cache inspection with tag support:

import { subscribeToCache, invalidateByTag } from '@flight-framework/devtools/cache';

// Subscribe to cache updates
subscribeToCache((entries, metrics) => {
    console.log(`Hit rate: ${metrics.hitRate}%`);
    console.log(`Tags: ${metrics.uniqueTags.join(', ')}`);
});

// Invalidate by tag
invalidateByTag('user-data');

Configuration

devtools({
    // Enable in development only (default)
    enabled: process.env.NODE_ENV !== 'production',
    
    // Devtools server port
    port: 9229,
    
    // Open devtools automatically
    open: false,
    
    // Features to enable
    features: {
        routes: true,
        components: true,
        actions: true,
        cache: true,
        network: true,
        performance: true,
    },
    
    // Overlay position
    position: 'bottom-right',
});

Browser Extension

Install the Flight DevTools browser extension for an integrated debugging experience:

• Chrome: Flight DevTools
• Firefox: Flight DevTools

The extension adds a "Flight" panel to your browser's developer tools.

API

Programmatic Access

import { getDevtools } from '@flight-framework/devtools';

const devtools = getDevtools();

// Log custom event
devtools.log('custom', { message: 'Hello' });

// Add custom panel
devtools.addPanel('my-panel', {
    title: 'My Panel',
    render: () => '<div>Custom content</div>',
});

React Hook

import { useDevtools } from '@flight-framework/devtools/react';

function MyComponent() {
    const { log, measure } = useDevtools();
    
    const handleClick = () => {
        const end = measure('click-handler');
        // ... do work
        end();
    };
    
    return <button onClick={handleClick}>Click</button>;
}

License

MIT