DevTools

The Unhead integration adds a panel to Vite DevTools showing active head tags, entries, SEO data, plugins, and source locations. Unhead registers the integration by default, but the panel activates only when Vite DevTools is enabled or already installed as a Vite plugin.

Panel data

The devtools plugin provides a real-time view of your head state during development:

• Entries: Active head entries, with source locations when the transform can inject them
• Tags: All resolved tags with their props, position, priority, and dedupe keys
• SEO overview: Title, description, canonical, robots, and Open Graph fields
• Scripts: Tracked useScript() instances and their load status
• Plugins: Active Unhead plugins
• Template params: Current template parameter values and separator
• Validation: Warnings from the Validate plugin, when enabled

Source Tracing

The plugin injects _source metadata (file path and line number) into useHead(), useSeoMeta(), useHeadSafe(), and useScript() calls whose arguments it can augment. This lets you click through from a tag in the DevTools panel to the line that created it.

Setup

Install Vite DevTools and its integration kit:

pnpm add -D @vitejs/devtools @vitejs/devtools-kit

npm install -D @vitejs/devtools @vitejs/devtools-kit

yarn add -D @vitejs/devtools @vitejs/devtools-kit

bun add -D @vitejs/devtools @vitejs/devtools-kit

The Unhead integration is included by default when using the unified Vite plugin. It only runs in vite dev, and only when Vite DevTools is active. Enable it in Vite's configuration:

export default defineConfig({
  devtools: { enabled: true },
})

import { Unhead } from '@unhead/vue/vite'
import vue from '@vitejs/plugin-vue'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [vue(), Unhead()],
})

Disable

Unhead({
  devtools: false,
})

Requirements

@vitejs/devtools and @vitejs/devtools-kit are optional development dependencies. Projects that do not enable Vite DevTools do not need to install them. The panel UI ships pre-built with @unhead/bundler.

How It Works

The panel is a Devframe devtool. Unhead mounts it into Vite DevTools with createPluginFromDevframe(). The integration has three parts:

1. Vite transform: Injects _source metadata into composable calls and wraps createHead() to expose the instance on window.__unhead_devtools__
2. Page script: Runs in your app's page as the dock's client script. It reads the head instance, serializes its state, and shares it with the panel over the Devframe in-page channel.
3. DevTools panel: Serves the app bundled in @unhead/bundler/dist at /__unhead/ as a dock panel. It calls the dev server over Devframe RPC for the Unhead version and the source audit.

The page script syncs state on every dom:rendered hook, so the panel updates in real time as head tags change. Head state stays in the browser tab. Open the panel from the dock in your app's page; the standalone /__devtools/ page has no page script to read from.

See Also

• Build Plugins Overview: All build-time optimizations
• Validate Plugin: Catch SEO and head tag issues shown in DevTools