@sucoza/router-devtools-plugin

Router DevTools Plugin

A comprehensive router debugging plugin for TanStack DevTools with live parameter editing, route tree visualization, and navigation timeline tracking.

Features

• Route Tree Visualization: Interactive hierarchical display of all application routes
• Live Parameter Editing: Real-time editing of route parameters and query strings with instant navigation
• Navigation Timeline: Complete history of all navigation events with detailed information
• React Router v6 Support: Built-in adapter for React Router v6 (extensible to other routers)
• Type-Safe: Full TypeScript support with comprehensive type definitions

Installation

npm install @sucoza/router-devtools-plugin

Quick Start

Basic Usage

import React from 'react';
import { BrowserRouter, Routes, Route } from 'react-router-dom';
import { useRouterDevTools } from '@sucoza/router-devtools-plugin';

function App() {
  // Initialize router DevTools
  useRouterDevTools();

  return (
    <BrowserRouter>
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/users/:id" element={<UserProfile />} />
        <Route path="/products" element={<ProductList />} />
      </Routes>
    </BrowserRouter>
  );
}

Manual Initialization

import { initializeRouterDevTools } from '@sucoza/router-devtools-plugin';

// Initialize manually
const cleanup = initializeRouterDevTools();

// Clean up when needed
cleanup();

Adding to TanStack DevTools

import { TanStackRouterDevtools } from '@tanstack/router-devtools';
import { RouterDevToolsPanel } from '@sucoza/router-devtools-plugin';

function MyDevTools() {
  return (
    <TanStackRouterDevtools>
      <RouterDevToolsPanel />
    </TanStackRouterDevtools>
  );
}

API Reference

Components

RouterDevToolsPanel

Main DevTools panel component with three tabs:

• Route Tree: Interactive route visualization
• Parameters: Live parameter and query string editing
• Timeline: Navigation history with detailed information

RouteTreeView

Displays hierarchical route structure with:

• Active route highlighting
• Parameter display
• Navigation shortcuts
• Expand/collapse functionality

RouteParameterInspector

Live parameter editing interface featuring:

• Route parameter editing with validation
• Query string parameter management
• Raw JSON view toggle
• Apply/reset functionality

NavigationTimeline

Navigation history display with:

• Action type indicators (PUSH/REPLACE/POP)
• Duration tracking
• Detailed route information
• Time-based filtering

Core Classes

RouterStateManager

Central state management for router DevTools.

import { RouterStateManager } from '@sucoza/router-devtools-plugin';

const stateManager = new RouterStateManager({
  maxHistoryEntries: 50,
  autoExpandRoutes: true,
  enableLiveEditing: true
});

ReactRouterAdapter

Adapter for React Router v6 integration.

import { createReactRouterAdapter } from '@sucoza/router-devtools-plugin';

const adapter = createReactRouterAdapter();
stateManager.registerAdapter(adapter);

Types

IRouterAdapter

Interface for creating custom router adapters:

interface IRouterAdapter {
  getCurrentState(): NavigationState | null;
  getRouteTree(): RouteInfo[];
  subscribe(callback: (state: NavigationState) => void): () => void;
  navigate(to: string, options?: NavigationOptions): void;
  updateParams(params: Record<string, string>): void;
  updateSearch(search: string): void;
  getRouterType(): string;
}

RouteInfo

Route definition structure:

interface RouteInfo {
  id: string;
  path: string;
  element?: string;
  index?: boolean;
  caseSensitive?: boolean;
  children?: RouteInfo[];
  loader?: boolean;
  action?: boolean;
  errorElement?: string;
  handle?: Record<string, unknown>;
}

NavigationState

Current navigation state:

interface NavigationState {
  location: {
    pathname: string;
    search: string;
    hash: string;
    state?: unknown;
    key: string;
  };
  matches: RouteMatch[];
  navigation: {
    state: 'idle' | 'loading' | 'submitting';
    // ... additional navigation properties
  };
  actionData?: unknown;
  loaderData: Record<string, unknown>;
  errors?: Record<string, Error>;
}

Configuration

RouterDevToolsConfig

interface RouterDevToolsConfig {
  maxHistoryEntries?: number; // Default: 50
  autoExpandRoutes?: boolean; // Default: true
  enableLiveEditing?: boolean; // Default: true
  routeNameResolver?: (route: RouteInfo) => string;
  paramValidator?: (params: Record<string, string>) => Record<string, string>;
}

Parameter Validation

Custom parameter validators can be provided:

import { commonValidators } from '@sucoza/router-devtools-plugin';

const config = {
  paramValidator: (params) => {
    const errors: Record<string, string> = {};
    
    if (params.id && !commonValidators.uuid(params.id)) {
      errors.id = 'Must be a valid UUID';
    }
    
    return errors;
  }
};

Advanced Usage

Custom Router Adapter

Create adapters for other router libraries:

import { IRouterAdapter, NavigationState } from '@sucoza/router-devtools-plugin';

class MyRouterAdapter implements IRouterAdapter {
  getCurrentState(): NavigationState | null {
    // Implementation for your router
  }
  
  getRouteTree(): RouteInfo[] {
    // Implementation for your router
  }
  
  // ... other interface methods
}

Event Listening

Listen to router events programmatically:

import { routerEventClient } from '@sucoza/router-devtools-plugin';

routerEventClient.on('router-navigation', (event) => {
  console.log('Navigation event:', event.payload);
});

Browser Support

• Chrome/Chromium-based browsers
• Firefox
• Safari
• Edge

TypeScript Support

This package is written in TypeScript and includes comprehensive type definitions. No additional @types packages are required.

Contributing

Contributions are welcome! Please see our contributing guide for details.

License

MIT

Part of the @sucoza TanStack DevTools ecosystem.