Site DevTools Overview

Site DevTools is the runtime diagnostics surface for @docs-islands/vitepress. Use it after the base integration is already working and you need page-level render state, bundle composition, HMR timing, or optional build reports.

When to Open It

Open it when a component flickers during navigation, when page cost suddenly grows, when HMR becomes slow, or when you need a runtime snapshot you can share in an issue, PR, or teammate handoff.

Entry and Surfaces

Entry and surfaces

Open Site DevTools and choose the right surface

Site DevTools works best when it reads like documentation: start from the question you have, then move to the surface that answers it.

How to Enter

Turn on Site DevTools with the query entry or the docs logo shortcut, then stay in the same mode while you move through different kinds of questions.

The choice is usually simple: use Page Overlay for the active component, Debug Logs for page runtime state, and Build Reports for build-time evidence.

Query: ?site-devtools=1. Shortcut: top-left logo x3. Feedback: top toast.

Query: ?site-devtools=1

Shortcut: Top-left logo x3

Feedback: Top toast

Page Overlay

Page Overlay keeps the explanation close to the component itself. It is the first place to look when you need the resolved render mode, current stage, timing, or the latest HMR movement.

It also helps answer whether the active container is mostly paying for total bundle cost, JavaScript, CSS, or asset weight before you jump into deeper debugging.

Debug Logs

Debug Logs is the runtime-facing surface. Use it when the question is no longer "what happened on the page?" but "what does the page runtime currently know?"

It is the right place to inspect injected globals, render metrics, HMR metrics, and snapshotRuntime() output when you need something you can copy into an issue, PR, or teammate handoff.

Build Reports

Build Reports becomes useful when runtime symptoms are not enough and you need a build-time explanation for page cost or regressions.

When analysis is enabled, this view gives you a page-level report and lets you continue that explanation through chunks and modules without switching to a different mental model.

Start with the entry card, then move to the surface that matches the question you need to answer. In practice that usually means component state in the overlay, runtime truth in Debug Logs, or build evidence in reports.

Core Capabilities

Core capabilities

Three views, three kinds of explanation

Each surface is best understood as a different kind of explanation rather than a different visual panel.

Component-first diagnosis

Page Overlay

What it shows

Page Overlay explains the current container in place, including resolved mode, stage, timing, and the latest HMR activity.

It also gives you the fastest path to bundle composition filters when you want to see whether the current cost is mainly JS, CSS, assets, or total bundle weight.

Best for

Use it when the symptom is visible during navigation, hydration, or interaction startup and you want to localize the issue before reading runtime state.

Primary output

The output is a component-scoped explanation: what mode ran, what stage it reached, and where the cost is most likely coming from.

Runtime-first diagnosis

Debug Logs

What it shows

Debug Logs exposes the page-level runtime state, including injected globals, render metrics, HMR metrics, and collected runtime entries.

It also keeps snapshotRuntime() close at hand when you need a shareable record rather than an on-screen observation.

Best for

Use it when you already know which page or component is involved and now need evidence you can inspect, compare, or share with someone else.

Primary output

The output is a runtime snapshot you can reason about outside the UI, especially in issues, PR reviews, and debugging handoffs.

Build-time explanation

Build Reports

What it shows

Build Reports reads page-level analysis generated during docs build and keeps that explanation connected to chunk and module evidence.

Best for

Use it when page cost changes need a build-time explanation, or when runtime symptoms alone are too indirect to explain a regression.

Primary output

The output is one page-centered explanation that ties together page cost, chunk evidence, and module evidence.

This surface only appears when build-time analysis is enabled.

These three views cover most of the day-to-day work in Site DevTools. They are meant to reduce the "where should I look first?" guesswork rather than mirror every panel one by one in prose.

Browser Console Helper

The browser console also exposes a helper object when you need to inspect or export runtime state directly:

globalThis.__DOCS_ISLANDS_SITE_DEVTOOLS__;

Common methods:

Method	Purpose
getEntries()	Read the current debug log list.
getGlobal(path?)	Read a runtime global object. The default is __COMPONENT_MANAGER__.
getRenderMetrics()	Read the page's collected render metrics.
getHmrMetrics()	Read the page's collected HMR metrics.
logRuntime(reason?)	Write the current runtime snapshot into the debug logs.
snapshotRuntime()	Return the current runtime snapshot object directly for copy/paste or sharing.

Optional UI Dependencies

These packages only improve presentation. The core diagnostics workflow still works without them.

Dependency	Enhancement	Fallback when missing
vue-json-pretty	Tree-view browsing for Injected Globals and runtime snapshots	Falls back to readable plain JSON.
prettier	Formatting before source preview	Shows the original source text directly.
shiki	Syntax highlighting and better source preview	Keeps a plain-text preview.