Ecopages0.2.0-rc.1

Getting Started

Core Concepts

Server

Integrations

Ecosystem

Extending

Reference

Dev toolbar

The Ecopages dev toolbar is a development-only browser inspector. It mounts during ecopages dev and does not ship to production builds.

Use it to answer three common questions while building:

  1. How did this page render? (Integration, route timing)
  2. What browser assets does this page load? (Page Browser Graph entries, chunks, vendors)
  3. What interactive islands are on the page? (island hosts)

Enable the toolbar

Install the reference package in your app and opt in from config:

pnpm add -D @ecopages/dev-toolbar
import { ConfigBuilder } from '@ecopages/core/config-builder';
import { ecopagesJsxPlugin } from '@ecopages/ecopages-jsx';
import { devToolbar } from '@ecopages/dev-toolbar/config';
 
export default new ConfigBuilder()
  .setRootDir(import.meta.dirname)
  .setDevToolbar(devToolbar())
  .setIntegrations([ecopagesJsxPlugin()])
  .build();

Disable per project with devToolbar({ enabled: false }), or per process with ECOPAGES_DEV_TOOLBAR=false.

Optional dependency

You do not need @ecopages/dev-toolbar unless you opt in with devToolbar.package. Core ships the dev manifest contract; the reference toolbar package is only required when you install and enable it.

Restart the dev server after toolbar client changes.

Built-in apps

AppWhat it shows
NavigationURL route, owning Integration, HMR status, and client navigation timings
DepsPage Browser Graph entry/chunk assets, vendor URLs, and dev-transform URLs from #__ECO_DEV_MANIFEST__
IslandsLive island hosts stamped with data-eco-island; click a row to highlight the DOM node
A11yaxe-core audit (with built-in fallback checks) and in-page highlights
SettingsDock placement, stealth mode, and documentation link

Dev manifest

Each dev HTML response includes a JSON script tag:

<script type="application/json" id="__ECO_DEV_MANIFEST__">…</script>

The toolbar reads this manifest client-side. Important fields:

FieldMeaning
routeAbsolute filesystem path of the page file that rendered this response
integrationOwning Integration plugin name for that page file (for example react, kitajs, lit)
pageBrowserGraphEntry and chunk assets for the current route
vendorUrlsVendor asset URLs referenced by the page package
devTransformUrlsDev-transform module URLs under /assets/__eco_dev__/

Import the manifest types and element id from core when building a custom toolbar client:

import {
  DEV_MANIFEST_ELEMENT_ID,
  type EcoDevManifest,
} from '@ecopages/core/dev-toolbar/dev-toolbar-manifest-contract';

Machine-readable navigation history is written to #__ECO_DEV_NAV_TELEMETRY__ in document.head (with data-eco-persist so SPA re-renders do not drop it) and exposed on window.__ECO_DEV_NAV_TELEMETRY__.getSnapshot() for agents and debugging.

Island discovery

Hydratable components stamp island host attributes. The Islands app reads data-eco-island, data-eco-island-integration, and related markers — not integration-specific selectors.

Bring your own toolbar

Core delivers /_dev_toolbar.js and injects #__ECO_DEV_MANIFEST__ on each dev HTML response. To customize the inspector, set devToolbar.package to your own client package and export a browser bootstrap module that mounts your toolbar UI.

Integrations do not register dock apps. Fork @ecopages/dev-toolbar for a working reference layout.

import { defineDevTool } from '@ecopages/core/dev-toolbar/define-dev-tool';
 
.setDevToolbar(defineDevTool('@acme/my-dev-toolbar'))

Related docs