The in-app widget

1. Write the manifest

next build
npx crust manifest --out public/crust-manifest.json

This file lists every route, source path and component name in your app. Generate it in analyze builds only — never in the build you deploy.

2. Mount it

components/CrustDevtools.tsx

'use client'

import { useEffect } from 'react'

export function CrustDevtools() {
  useEffect(() => {
    if (!process.env.NEXT_PUBLIC_CRUST) return

    const disposers: (() => void)[] = []
    void import('crust/collector').then((m) => disposers.push(m.startCollector()))
    void import('crust/widget').then((m) => disposers.push(m.mountCrustWidget()))

    return () => {
      for (const dispose of disposers) dispose()
    }
  }, [])

  return null
}

Render it in your root layout, then build with the gate on:

NEXT_PUBLIC_CRUST=1 next build && next start

A crust pill appears in the corner.

Why it is built this way

The gate is checked before the import, not inside the module

With the variable unset, the bundler eliminates both dynamic imports entirely — neither the widget nor the collector reaches your production bundle. A runtime if inside the module would still ship the code and the manifest.

It renders in a shadow root

Your CSS cannot break the panel and the panel’s CSS cannot leak into your app. A devtool that restyles the page it is measuring is worse than no devtool.

It uses no UI framework

Plain DOM. This ships into your page, and coupling it to a React version would make it a support burden and drag a second renderer into the bundle.

It fetches lazily

The manifest loads only when the panel is first opened. The widget must not move the numbers it exists to report.

Options

mountCrustWidget({
  manifestUrl: '/crust-manifest.json',
  position: 'bottom-right', // or bottom-left, top-right, top-left
})

Both calls return a disposer.

Without any integration

If you would rather not touch the app at all:

npx crust report --open

Same data, same design, as one self-contained HTML file.

CI and pull requests Runtime collector

⌘I

Getting started

Concepts

Guides

Reference

The in-app widget

1. Write the manifest

2. Mount it

Why it is built this way

Options

Without any integration

​1. Write the manifest

​2. Mount it

​Why it is built this way

​Options

​Without any integration

1. Write the manifest

2. Mount it

Why it is built this way

Options

Without any integration