Dev toolbar

A floating in-browser tool palette shown in astro dev. It surfaces audits, route info, integration status, and any user-installed toolbar apps.

Purpose

Give developers fast feedback during local development without opening the browser DevTools. Toolbars apps can ship with integrations to expose subsystem state (queues, content collections, db schema) inline.

Key files

File	Purpose
packages/astro/src/runtime/client/dev-toolbar/toolbar.ts	The toolbar custom element (host).
packages/astro/src/runtime/client/dev-toolbar/entrypoint.ts	Browser entrypoint loaded by Vite.
packages/astro/src/runtime/client/dev-toolbar/apps/	Built-in apps (Audits, View Transitions inspector, Settings, …).
packages/astro/src/runtime/client/dev-toolbar/ui-library/	Internal UI primitives (button, panel, tabs) all custom elements.
packages/astro/src/runtime/client/dev-toolbar/helpers.ts	The ToolbarServerHelpers API exposed to apps.
packages/astro/src/runtime/client/dev-toolbar/settings.ts	Persisted user preferences for the toolbar.
packages/astro/src/toolbar/index.ts	Server-side glue (registration, plugin loader).
packages/astro/src/vite-plugin-overlay/	The Vite plugin that mounts the toolbar (and the error overlay).

Toolbar apps

A toolbar app is a small JS module that registers handlers for the toolbar lifecycle:

import { defineToolbarApp } from 'astro/toolbar';

export default defineToolbarApp({
  init(canvas, app, server) {
    app.onToggled(({ state }) => {
      // open / close
    });
  },
});

Integrations register apps via the astro:server:setup hook by calling addDevToolbarApp({ id, name, icon, entrypoint }). The examples/toolbar-app/ example demonstrates this end-to-end.

How it works

graph LR
    A[Vite dev server] -->|inject script| B[browser page]
    B --> C[dev-toolbar entrypoint]
    C --> D[toolbar custom element]
    D --> E[Built-in apps]
    D --> F[User-registered apps]
    E -->|server helpers via WS| A
    F -->|server helpers via WS| A

The bridge between the browser-side toolbar and the dev server uses Vite's WebSocket so apps can request server-side info (resolve a path, read content collections, query Astro config) without bespoke endpoints.

Built-in apps

• Audits — accessibility and performance hints.
• View Transitions inspector — shows astro:before-swap events live.
• Astro DB Studio link — when @astrojs/db is configured.
• Settings — toggles toolbar persistence and verbose mode.

Related pages

• features / view transitions
• packages / astro — astro/toolbar export.