Devtools
Inspect tours, check target health, jump between steps and watch events while developing.
pnpm add -D @awesome-tour/devtoolsimport { TourDevtools } from '@awesome-tour/devtools';
<TourProvider tours={[onboarding]}> <App /> {import.meta.env.DEV && <TourDevtools checklists={[gettingStarted]} />}</TourProvider>;- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
Beat A
16 steps · drumsMixer
4 channelsimport { TourDevtools } from '@awesome-tour/devtools';import { createTour, Tour } from '@awesome-tour/react';import { LoopworkApp, parts } from '@loopwork';import { Wrench } from 'lucide-react';import { useState } from 'react';import { TourPopover } from '@/components/awesome-tour/tour';import { DemoFrame, StartButton, worldButton } from './ui';
const $ = parts('inspect');
const tour = createTour({ id: 'docs-devtools', data: { plan: 'free' }, steps: [ { id: 'welcome', title: 'What’s new in 2.4', description: 'Open the devtools panel (bottom right) while this runs.', }, { id: 'sequencer', target: $('sequencer'), title: 'Swing per row', description: 'Each drum row now has its own swing.', }, { // Not shipped to this build yet: devtools flags the missing target. id: 'stems', target: $('stems-export'), title: 'Stems export', description: 'One file per channel.', }, { // Pro only: `when` hides it on the free plan, and devtools says so. id: 'mastering', target: $('export'), when: (ctx) => ctx.data.plan === 'pro', title: 'Mastering presets', description: 'Loudness targets for every platform.', }, { id: 'mixer', target: $('mixer'), side: 'left', title: 'Wider meters', description: 'Easier to read while you mix.', }, ],});
export function DevtoolsDemo() { const [show, setShow] = useState(false); return ( <Tour.Root tour={tour}> <DemoFrame title="Devtools" actions={ <> <button type="button" className={worldButton.secondary} aria-pressed={show} onClick={() => setShow((s) => !s)} > <Wrench /> {show ? 'Hide devtools' : 'Show devtools'} </button> <StartButton /> </> } footer={ <> <kbd className="rounded border bg-background px-1 font-mono">Alt+Shift+T</kbd> toggles the panel. Hover a step to highlight its target, click to jump to it. </> } > <LoopworkApp scope="inspect" /> </DemoFrame> <TourPopover /> {show && <TourDevtools tours={[tour]} defaultOpen position="bottom-right" />} </Tour.Root> );}What you get
- Tours — every tour registered on the
TourProvider(plus any passed intours), with status, phase, version and progress. Buttons to restart, go back and forth, pause, resume, complete and close. - Steps — each step’s target health: centered, found, missing, on /route (lives on
another page) or hidden (
whenis false). Hover a step to highlight its target on the page; click it to jump there (navigating if needed). - Data — the tour’s
dataand its last error. - Events — a live timeline of every tour event.
- Checklists — progress per checklist; click an item to toggle it.
Toggle the panel with Alt+Shift+T (shortcut prop, false to
disable). It renders inside a shadow root, so your CSS and its CSS never mix (isolate={false} to
opt out), and it remembers whether it was open.
Rules
The Rules tab answers “why didn’t my tour show?”: for every tour on the provider it lists each display rule — audience, schedule, once, max shows, cooldown, snooze — with whether it passes and why, plus buttons to start a tour if eligible and to reset impressions.
Element picker
Pick element, then click anything on the page: devtools suggests the most stable way to target
it — an existing anchor(), a data-tour / data-testid, a meaningful id or accessible name,
and only then a structural path — and gives you a step snippet to copy. Picking never triggers the
element (links don’t navigate, buttons don’t fire). Esc cancels.
Export
Export JSON downloads a snapshot of every tour’s state, the manager’s queue and the event log — attach it to a bug report.
Funnel
The Funnel tab counts this session’s runs of each tour: how many reached each step, where they dropped off, how they ended, and how many reached the tour’s goal. Click through a tour a few times, closing it at different steps, and you see the drop-off before any analytics is wired up.
Recorder
The Record tab builds a tour by clicking through your app:
- + Element, then click the thing the step should point at. The picker keeps the most stable
target it can find (
anchor,byTour,byRoleand name, then an id or selector) and the page you were on. Navigate between picks as you like; the recording survives reloads. - Type a title and description, pick a side, reorder or remove steps. + Centered adds a step without a target.
- Play runs it right away, as a preview (nothing saved or tracked).
- Copy JSON for your CMS, or Copy code for a
createTourcall — routes are written where the page changes.
Then put the result through the health check in CI.
Usable during modal tours
The panel carries the data-tour-keep attribute: modal tours don’t make it inert, and tour
keyboard shortcuts ignore keys pressed inside it. Use the same attribute for your own toasts or
support widgets.
Keep it out of production
Render it behind a development check so bundlers drop it:
{process.env.NODE_ENV !== 'production' && <TourDevtools />}Or lazy-load it only for internal users:
const TourDevtools = lazy(() => import('@awesome-tour/devtools').then((m) => ({ default: m.TourDevtools })),);Full API in the devtools reference.