@smoothglue/dev-console

v1.0.1

Published

7 days ago

A powerful 💪, draggable 🖱️ developer console for React applications ⚛️. This tool provides an in-app overlay to inspect network traffic 🚦, view console logs 📜, and execute custom commands ⚡ without needing to open the browser's developer tools 🛠️.

0High
0Medium
0Low

braingu-matt

wade.tait

brentgu

🛠️ Smoothglue Dev Console

Table of Contents 📑

✨ Features

🌐 Network Console: Intercept and inspect fetch requests and responses using a dedicated Service Worker.
- View JSON {} and HTML <html> responses directly in the UI.
- Filter by content type (JSON , JS , Image, CSS, HTML).
- Monitor request status and timing.
📝 Log Console: Captures and displays standard console logs (log, debug, warn, info , error).
- Preserves logs within the app context.
- Search and filter logs.
⏱️ Performance Monitor: Granularly track the execution time of specific functions and components.
- View real-time statistics (Min, Max, Average) for your operations.
- Visualize execution history.
- Supports synchronous functions, promises, and React component renders.
🚀 System Health: Monitor real-time application and system performance.
- System: Track Frames Per Second (FPS), CPU concurrency, and Memory usage.
- Network: Inspect connection type (4g, wifi), downlink speed, and RTT.
- Load: Analyze critical loading timings including FCP, TTFB, and DOM load times.
⌨️ Command Console: Register and execute custom commands directly from the UI.
- Trigger specific app states or utility functions.
🖱️ Draggable & Resizable: Built on react-rnd, the console floats over your app and can be moved or resized to fit your workflow.
🎨 Theming: Comes with a dark mode developer theme (devConsoleTheme) using Material UI.

🚀 Getting Started

📦 Installation

Install the package using npm or yarn:

npm install smoothglue-dev-console

Copy the service worker 👷

This package uses a service worker to gather console and network logs. This service worker must be added to your applications' public folder so that it can be accessed by the browser.

The file can be copied manually by using the following command after installation:

cp node_modules/smoothglue-dev-console/dist/devConsoleServiceWorker.js public/

Alternatively, you can run the command npx copy-dev-console-sw after installation to copy the file to your public folder.

Peer Dependencies 🤝

This library relies on several peer dependencies that must be installed in your project 🔗. It supports both React 18 and React 19.

Ensure you have the core React and Material UI packages installed:

npm install react react-dom @mui/material @mui/icons-material

This library also utilizes MUI components. You must install the following packages:

npm install @mui/x-data-grid @mui/x-date-pickers

Or their pro versions:

npm install @mui/x-data-grid-pro @mui/x-date-pickers-pro

Note: @mui/x-data-grid-pro and @mui/x-date-pickers-pro are commercial packages that require a valid license key from MUI.

Usage 🎮

DevConsoleProvider

To use the console, wrap your application with the DevConsoleProvider. This context handles the state for logs, network traffic, and visibility. You can also inject custom panes (tabs) for app-specific tools, such as feature flags.

<ThemeProvider theme={theme}>
  <DevConsoleProvider
    customPanes={[
      {
        label: "Feature Flags 🚩",
        component: () => <DevFlagsConsole />,
      },
    ]}
  >
    <App />
  </DevConsoleProvider>
</ThemeProvider>

DevConsoleProvider Props ⚙️

Recipes 👩‍🍳

Using a Dynamic Shortcut Key Combination

A dynamic hotkey combination can be provided as seen in this example. This example also disables hotkey activation until a hotkey combination is provided.

export const App=()=>{

  // wrap in other providers
    <DevConsoleWrapper>
      <App/>
    </DevConsoleWrapper>
}

export const DevConsoleWrapper =(children)=>{

    const hotkeys = getHotKeys() // a function that provides either a falsy value of a hotkey combination

    <DevConsoleProvider
      hotkeys={hotKeys ?? 'NONE'} // pass NONE to deactivate hotkeys until the hotkey state has a valid value
      customPanes={[
        {
          label: "Feature Flags 🚩",
          component: () => <DevFlagsConsole />,
        },
      ]}
    >
      {children}
    </DevConsoleProvider>

}

useDevConsole Hook 🪝

The useDevConsole hook allows you to access the console state and controls from anywhere within the provider.

import { useDevConsole } from "smoothglue-dev-console";

const Header = () => {
  const { isVisible, setEnabled } = useDevConsole();

  return <button onClick={() => setEnabled(!isVisible)}>Toggle Console</button>;
};

Adding Custom Commands ⚡

You can register commands that appear in the Command Console tab ⌨️.

import { useDevConsole } from "smoothglue-dev-console";
import { useEffect } from "react";

const MyComponent = () => {
  const { registerCommand } = useDevConsole();

  useEffect(() => {
    // 🔔 Register a new command
    const unregister = registerCommand({
      command: "clear-cache",
      description: "Clears local storage and reloads ♻️",
      callback: () => {
        localStorage.clear();
        window.location.reload();
      },
    });

    return unregister;
  }, []);

  return <div>App Content</div>;
};

Performance Monitoring Utilities ⏱️

The Dev Console provides several utilities to help you measure the execution time of functions and components. These metrics appear in the Performance tab.

`measureSync` & `measurePromise`

Wrap your functions to automatically log their duration.

import { measureSync, measurePromise } from "smoothglue-dev-console";

// Measure a synchronous function
const heavyCalculation = () => {
  measureSync("Data Processing", () => {
    // ... complex logic ...
  });
};

// Measure an asynchronous function
const fetchData = async () => {
  const result = await measurePromise("API Fetch", async () => {
    const response = await fetch("/api/data");
    return response.json();
  });
};

`usePerformanceLogger`

A hook for measuring operations within a component manually.

import { usePerformanceLogger } from "smoothglue-dev-console";

const DataGrid = () => {
  const { start, end } = usePerformanceLogger("DataGrid");

  const processRow = () => {
    start("Process Row");
    // ... logic ...
    end("Process Row");
  };

  return <button onClick={processRow}>Process</button>;
};

`PerformanceProfiler`

A component wrapper that logs the render duration of its children using the React Profiler.

import { PerformanceProfiler } from "smoothglue-dev-console";

const Dashboard = () => (
  <PerformanceProfiler id="DashboardWidget">
    <ComplexWidget />
  </PerformanceProfiler>
);

Note: If you are using libraries that rely on React Context (like resium for Cesium maps), wrapping them directly with PerformanceProfiler may break context propagation if your package dependencies are not perfectly aligned. In those cases, consider passing the necessary context (like the viewer instance) manually as props or using usePerformanceLogger within the component instead.

logDev Utility 🛠️

The logDev function is a helper utility that allows you to log messages directly to the Log Console tab with a specific "dev" type. These logs appear with distinct styling ✨.

import { logDev } from "smoothglue-dev-console";

const performAction = () => {
  // Log a specific development message
  logDev("Action triggered successfully");
};

Capturing Logs from Workers 👷

The Dev Console Service Worker can automatically intercept and display logs generated from Web Workers or Shared Workers.

To enable this:

Import and enable logging in your worker: You must import enableWorkerLogging from the package and call it at the top of your worker script.
```
import { enableWorkerLogging } from "@smoothglue/dev-console";

enableWorkerLogging();
```
Scope: Ensure your worker is running within the scope of the devConsoleServiceWorker (usually the root /).
Log: Use standard console methods (console.log, console.warn, console.error) within your worker script.

These logs will be forwarded to the Log Console and appear alongside your main thread logs.

📚 Running Storybook

This project uses Storybook to develop and test UI components in isolation.

Install dependencies:
```
npm install
```
Start the Storybook server:
```
npm run storybook
```
Open your browser: Navigate to http://localhost:6006 to view the DevConsole stories.

Contributing 🤲

📂 Project Structure

src/lib/DevConsole: The main container component.
src/lib/networkConsole: Components and logic for the network logger.
src/lib/logEntries: Components for the console log viewer.
src/lib/commandConsole: The autocomplete input for executing commands.
src/lib/performanceMonitoringConsole: Logic for measuring execution times and the UI for displaying them.
src/devConsoleServiceWorker.ts: The service worker script for intercepting fetch requests.

Available Scripts 📜

In the project directory, you can run:

npm run dev: Starts the Vite development server ⚡.
npm run build: Runs TypeScript type checking (tsc) and builds the library for production using Vite.
npm test: Runs the test suite using Vitest 🧪.
npm run lint: Runs ESLint to analyze the code for quality issues 🧹.
npm run tsc: Runs Typescript checking 🔍.
npm run storybook: Starts the Storybook development server at http://localhost:6006.
npm run build-storybook: Builds the static Storybook documentation for deployment.