@ytspar/devbar

v1.18.1

Published

an hour ago

Development toolbar and utilities with Sweetlink integration - pure vanilla JS, no framework dependencies

Downloads

3,275

0High
0Medium
0Low

ytspar

development debug devbar sweetlink vanilla-js

@ytspar/devbar

Development toolbar with Sweetlink integration for browser-based development tools.

Features

Breakpoint indicator: Shows current Tailwind breakpoint and viewport dimensions
Performance metrics: FCP, LCP, and total page size
Console badges: Error and warning counts with click-to-view logs
Screenshot capture: Save to file or copy to clipboard
AI Design Review: Send screenshots to Claude for design analysis
Document Outline: View and export page heading structure
Page Schema: View JSON-LD, Open Graph, and meta tag data
Sweetlink integration: Real-time connection to dev server

Requirements

This package is ESM-only. It requires "type": "module" in your package.json or an ESM-capable bundler (Vite, webpack, esbuild, etc.).

Installation

pnpm add @ytspar/devbar

# Or install canary (latest from main)
pnpm add @ytspar/devbar@canary

Usage

Basic Setup (Vanilla JS)

import { initGlobalDevBar } from '@ytspar/devbar';

// Initialize with default options
initGlobalDevBar();

// Or with custom options
initGlobalDevBar({
  position: 'bottom-left',
  accentColor: '#10b981',
});

In a Vite/React Project

// main.ts or App.tsx
if (import.meta.env.DEV) {
  import('@ytspar/devbar').then(({ initGlobalDevBar }) => {
    initGlobalDevBar({
      position: 'bottom-center',
      showTooltips: true,
    });
  });
}

In a Next.js Project

Create a client component that dynamically imports the devbar:

// src/providers/DevBar.tsx
'use client';

import { useEffect } from 'react';

export function DevBar() {
  useEffect(() => {
    if (process.env.NODE_ENV === 'development') {
      import('@ytspar/devbar').then(({ initGlobalDevBar }) => {
        initGlobalDevBar();
      });
    }
  }, []);

  return null;
}

Add it to your root layout, outside the provider tree:

// src/app/layout.tsx
import { DevBar } from '@/providers/DevBar';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <DevBar />
      </body>
    </html>
  );
}

The dynamic import ensures the devbar is fully tree-shaken from production builds.

Positions

The devbar can be placed in five positions:

| Position | Description | |----------|-------------| | bottom-left | Bottom left corner (default) - leaves room for other dev tools on the right | | bottom-right | Bottom right corner | | top-left | Top left corner | | top-right | Top right corner | | bottom-center | Centered at bottom - ideal for focused development, responsive at mobile sizes |

// Example: Center the devbar at the bottom
initGlobalDevBar({ position: 'bottom-center' });

On mobile viewports (<640px), all positions automatically center and the action buttons wrap to a second row.

Configuration Options

interface GlobalDevBarOptions {
  /** Position of the devbar. Default: 'bottom-left' */
  position?: 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right' | 'bottom-center';

  /** Primary accent color (CSS color). Default: '#10b981' (emerald) */
  accentColor?: string;

  /** First-run/reset theme mode when no saved preference exists. Default: 'system' */
  defaultThemeMode?: 'dark' | 'light' | 'system';

  /** Force a theme mode for host apps that do not support every DevBar theme */
  themeMode?: 'dark' | 'light' | 'system';

  /** Which metrics to show. Default: all enabled */
  showMetrics?: {
    breakpoint?: boolean;  // Tailwind breakpoint indicator
    fcp?: boolean;         // First Contentful Paint
    lcp?: boolean;         // Largest Contentful Paint
    pageSize?: boolean;    // Total transfer size
  };

  /** Whether to show the screenshot button. Default: true */
  showScreenshot?: boolean;

  /** Whether to show console error/warning badges. Default: true */
  showConsoleBadges?: boolean;

  /** Whether to show tooltips on hover. Default: true */
  showTooltips?: boolean;

  /** Size overrides for special layouts */
  sizeOverrides?: {
    width?: string;
    maxWidth?: string;
    minWidth?: string;
  };
}

Example: Minimal DevBar

initGlobalDevBar({
  showMetrics: {
    breakpoint: true,
    fcp: false,
    lcp: false,
    pageSize: false,
  },
  showScreenshot: false,
  showConsoleBadges: true,
  showTooltips: false,  // Disable tooltips
});

Custom Controls

import { GlobalDevBar } from '@ytspar/devbar';

// Register a custom control
GlobalDevBar.registerControl({
  id: 'my-control',
  label: 'Reset State',
  tooltip: 'Clears localStorage and reloads the current page',
  onClick: () => {
    localStorage.clear();
    location.reload();
  },
  variant: 'warning',  // 'default' | 'warning'
});

// Unregister when done
GlobalDevBar.unregisterControl('my-control');

Release Info Plugin

Show release metadata without taking over the toolbar:

import { releaseInfoPlugin } from '@ytspar/devbar/plugins/release-info';

const cleanupRelease = releaseInfoPlugin({
  version: '1.4.2',
  releasedAt: '2026-05-06T06:21:23Z',
  changelog: [
    'Show DevBar on staging deploys',
    'Expose release timestamp, version, and changelog metadata',
  ],
});

// Unregister when done
cleanupRelease();

The badge displays the version and formatted release timestamp. Hovering the badge shows the exact release time and changelog lines.

Cleanup

import { destroyGlobalDevBar } from '@ytspar/devbar';

// Remove the devbar and cleanup listeners
destroyGlobalDevBar();

Keyboard Shortcuts

Cmd/Ctrl + Shift + S: Save screenshot to file
Cmd/Ctrl + Shift + C: Copy screenshot to clipboard
Escape: Close any open modal/popup

Integration with Sweetlink

The devbar automatically connects to the Sweetlink WebSocket server (port 9223) for:

Screenshot saving to the project directory
AI-powered design review via Claude
Document outline and schema export

For proxied local URLs such as Portless (https://myapp.localhost), use the Sweetlink Vite or Next integration so the real internal app/WebSocket ports are injected automatically. If you run Sweetlink manually behind a proxy, pass both the internal app port and WebSocket port:

initGlobalDevBar({
  sweetlink: { appPort: 4123, wsPort: 10346 }
});

For screenshot evidence where the toolbar should not appear, use Sweetlink's capture flag:

pnpm sweetlink screenshot --hide-devbar
pnpm sweetlink screenshot --hifi --hide-devbar

When Sweetlink is not running, the devbar still functions but file-saving features are disabled.

Early Console Capture

Console logs are captured from the moment the devbar module loads, before your app initializes. This catches:

All console.log/error/warn/info calls
Errors that occur during hydration
Early initialization issues

Dependencies

html2canvas-pro - Screenshot capture

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@ytspar/devbar

Features

Requirements

Installation

Usage

Basic Setup (Vanilla JS)

In a Vite/React Project

In a Next.js Project

Positions

Configuration Options

Example: Minimal DevBar

Custom Controls

Release Info Plugin

Cleanup

Keyboard Shortcuts

Integration with Sweetlink

Early Console Capture

Dependencies

License