Skip to content
awesome-tour

Type to search every page.

    BDevtoolsContents

    Devtools

    Inspect tours, check target health, jump between steps and watch events while developing.

    Terminal window
    pnpm add -D @awesome-tour/devtools
    import { TourDevtools } from '@awesome-tour/devtools';
    <TourProvider tours={[onboarding]}>
    <App />
    {import.meta.env.DEV && <TourDevtools checklists={[gettingStarted]} />}
    </TourProvider>;
    Devtools
    Loopworknight-drive.lwp
    001.1.1
    1. 1
    2. 2
    3. 3
    4. 4
    5. 5
    6. 6
    7. 7
    8. 8
    Drums
    Beat A
    Beat B
    Bass
    Sub line
    Keys
    Rhodes
    Vox
    Hook (dry)

    Beat A

    16 steps · drums
    Kick
    Snare
    Hat
    Clap

    Mixer

    4 channels
    Drums
    80%
    Bass
    35%
    Keys
    60%
    Vox
    50%
    Alt+Shift+T toggles the panel. Hover a step to highlight its target, click to jump to it.
    DevtoolsDemo.tsx
    import { 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 in tours), 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 (when is false). Hover a step to highlight its target on the page; click it to jump there (navigating if needed).
    • Data — the tour’s data and 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:

    1. + Element, then click the thing the step should point at. The picker keeps the most stable target it can find (anchor, byTour, byRole and name, then an id or selector) and the page you were on. Navigate between picks as you like; the recording survives reloads.
    2. Type a title and description, pick a side, reorder or remove steps. + Centered adds a step without a target.
    3. Play runs it right away, as a preview (nothing saved or tracked).
    4. Copy JSON for your CMS, or Copy code for a createTour call — 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.