tessl/npm-astro

Astro is a modern site builder with web best practices, performance, and DX front-of-mind.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Dev Toolbar

Name: tessl/npm-astro
Author: tessl

The Dev Toolbar provides an extensible development interface for adding custom debugging and development tools.

Capabilities

Define Toolbar App

Defines a custom dev toolbar application.

/**
 * Defines a dev toolbar app
 */
function defineToolbarApp(app: DevToolbarApp): DevToolbarApp;

interface DevToolbarApp {
  init?(
    canvas: ShadowRoot,
    app: ToolbarAppEventTarget,
    server: ToolbarServerHelpers
  ): void | Promise<void>;

  beforeTogglingOff?(canvas: ShadowRoot): boolean | Promise<boolean>;
}

import { defineToolbarApp } from 'astro/toolbar';

export default defineToolbarApp({
  init(canvas, app, server) {
    const button = document.createElement('button');
    button.textContent = 'My Tool';
    button.onclick = async () => {
      const result = await server.send('my-action', { data: 'value' });
      console.log(result);
    };

    canvas.appendChild(button);

    app.addEventListener('app-toggled', (event) => {
      console.log('App toggled:', event.detail.state);
    });
  },

  beforeTogglingOff(canvas) {
    return confirm('Close this tool?');
  },
});

Adding to Integration:

// integration.ts
import { defineIntegration } from 'astro-integration-kit';

export default defineIntegration({
  name: 'my-integration',
  hooks: {
    'astro:config:setup': ({ addDevToolbarApp }) => {
      addDevToolbarApp({
        id: 'my-tool',
        name: 'My Tool',
        icon: '<svg>...</svg>',
        entrypoint: './my-toolbar-app.ts',
      });
    },
  },
});

Types

Dev Toolbar App

interface DevToolbarApp {
  init?(
    canvas: ShadowRoot,
    app: ToolbarAppEventTarget,
    server: ToolbarServerHelpers
  ): void | Promise<void>;

  beforeTogglingOff?(canvas: ShadowRoot): boolean | Promise<boolean>;
}

Toolbar Server Helpers

interface ToolbarServerHelpers {
  send: <T>(event: string, payload: T) => void;
  on: <T>(event: string, callback: (data: T) => void) => void;
}

Toolbar App Event Target

interface ToolbarAppEventTarget extends EventTarget {
  addEventListener(
    type: 'app-toggled',
    listener: (event: CustomEvent<{ state: 'enabled' | 'disabled' }>) => void
  ): void;

  addEventListener(
    type: 'plugin-notification',
    listener: (event: CustomEvent<{ notification: Notification }>) => void
  ): void;

  toggleNotification(options: NotificationPayload): void;
  toggleState(options: AppStatePayload): void;
  onToggled(callback: AppToggledEvent): void;
  onToolbarPlacementUpdated(callback: ToolbarPlacementUpdatedEvent): void;
}

interface NotificationPayload {
  level?: 'error' | 'warning' | 'info';
  message: string;
}

interface AppStatePayload {
  state: boolean;
}

type AppToggledEvent = (event: CustomEvent) => void;
type ToolbarPlacementUpdatedEvent = (event: CustomEvent) => void;

UI Components

The Dev Toolbar provides built-in UI components accessible via custom elements:

interface HTMLElementTagNameMap {
  'astro-dev-toolbar-window': DevToolbarWindow;
  'astro-dev-toolbar-button': DevToolbarButton;
  'astro-dev-toolbar-badge': DevToolbarBadge;
  'astro-dev-toolbar-card': DevToolbarCard;
  'astro-dev-toolbar-toggle': DevToolbarToggle;
  'astro-dev-toolbar-icon': DevToolbarIcon;
  'astro-dev-toolbar-tooltip': DevToolbarTooltip;
  'astro-dev-toolbar-highlight': DevToolbarHighlight;
  'astro-dev-toolbar-select': DevToolbarSelect;
  'astro-dev-toolbar-radio-checkbox': DevToolbarRadioCheckbox;
}

export default defineToolbarApp({
  init(canvas) {
    const window = document.createElement('astro-dev-toolbar-window');

    const card = document.createElement('astro-dev-toolbar-card');
    card.textContent = 'Status: Active';
    window.appendChild(card);

    const toggle = document.createElement('astro-dev-toolbar-toggle');
    toggle.addEventListener('change', (e) => {
      console.log('Toggle:', e.target.checked);
    });
    window.appendChild(toggle);

    canvas.appendChild(window);
  },
});

Integration Hook

Dev toolbar apps are added via the addDevToolbarApp function in the astro:config:setup integration hook:

/**
 * Add a dev toolbar app (from integration hook)
 */
function addDevToolbarApp(entry: DevToolbarAppEntry): void;

interface DevToolbarAppEntry {
  id: string;
  name: string;
  icon?: Icon;
  entrypoint: string | URL;
}

Module

Dev toolbar APIs are available from the astro/toolbar module:

import { defineToolbarApp } from 'astro/toolbar';
import type { DevToolbarApp, ToolbarServerHelpers, ToolbarAppEventTarget } from 'astro/toolbar';

Common Issues

Shadow DOM styling: Styles inside the toolbar app are scoped to the shadow DOM. Use standard CSS or inline styles.
Communication: Use the server helper to communicate between the toolbar app and server, not direct fetch calls.
Lifecycle: The beforeTogglingOff hook can prevent the app from closing by returning false.