Skip to content
awesome-tour

Type to search every page.

    BTours as dataContents

    Tours as data

    Keep tours in JSON — in a CMS, a feature-flag service or your API — validate them against a schema and build them at runtime.

    Tours written in code ship with deploys. When product managers or a CMS own the copy — or you want to change a tour without a release — keep it as data. fromJSON turns a document into options for createTour.

    Tours as data
    Loopworknight-drive.lwp
    001.1.1

    Beat A

    16 steps · drums
    Kick
    Snare
    Hat
    Clap

    Mixer

    4 channels
    Drums
    80%
    Bass
    35%
    Keys
    60%
    Vox
    50%
    fromJSON() validates the document and wires the `wide` action into the third step.
    JsonDemo.tsx
    import { fromJSON, type TourJSON } from '@awesome-tour/core/json';
    import { createTour, Tour, type TourInstance } from '@awesome-tour/react';
    import { LoopworkApp } from '@loopwork';
    import { useState } from 'react';
    import { TourPopover } from '@/components/awesome-tour/tour';
    import { DemoFrame, worldButton } from './ui';
    const initial: TourJSON = {
    id: 'docs-json',
    steps: [
    {
    id: 'transport',
    target: '#from-json [data-tour=transport]',
    title: 'Loaded from JSON',
    description: 'This tour came from the document below. Edit it, then build again.',
    },
    {
    id: 'beat',
    target: ['#from-json [data-tour=row-kick]', '#from-json [data-tour=row-snare]'],
    title: 'Kick and snare',
    description: 'Arrays still mean several targets.',
    },
    {
    id: 'mixer',
    target: '#from-json [data-tour=mixer]',
    side: 'left',
    title: 'Mixer',
    when: 'wide',
    description: 'Only on wide screens: `when` names an action.',
    },
    ],
    };
    // Functions can't live in JSON: they're referenced by name.
    const actions = { wide: () => window.innerWidth > 640 };
    export function JsonDemo() {
    const [text, setText] = useState(() => JSON.stringify(initial, null, 2));
    const [error, setError] = useState<string | null>(null);
    const [tour, setTour] = useState<TourInstance<any, any>>(() =>
    createTour(fromJSON(initial, { actions })),
    );
    const start = () => {
    try {
    const next = createTour(fromJSON(JSON.parse(text) as TourJSON, { actions }));
    tour.destroy();
    setTour(next);
    setError(null);
    void next.start();
    } catch (e) {
    setError(e instanceof Error ? e.message : String(e));
    }
    };
    return (
    <Tour.Root tour={tour} key={tour.id + text.length}>
    <DemoFrame
    title="Tours as data"
    actions={
    <button type="button" className={worldButton.primary} onClick={start}>
    Build & start
    </button>
    }
    footer={
    error ? (
    <pre role="alert" className="whitespace-pre-wrap font-mono text-dont">
    {error}
    </pre>
    ) : (
    'fromJSON() validates the document and wires the `wide` action into the third step.'
    )
    }
    >
    <div className="grid gap-3">
    <LoopworkApp scope="from-json" layout="compact" />
    <textarea
    aria-label="Tour JSON"
    value={text}
    onChange={(e) => setText(e.target.value)}
    spellCheck={false}
    className="min-h-64 w-full resize-y rounded-sm border-2 border-ink bg-paper p-3 font-mono text-xs leading-relaxed outline-none focus-visible:ring-2 focus-visible:ring-marker"
    />
    </div>
    </DemoFrame>
    <TourPopover />
    </Tour.Root>
    );
    }
    import { createTour } from '@awesome-tour/react';
    import { fromJSON } from '@awesome-tour/core/json';
    const doc = await fetch('/api/tours/onboarding').then((r) => r.json());
    export const onboarding = createTour(
    fromJSON(doc, {
    actions: { isAdmin: (ctx) => ctx.data.role === 'admin' }, // referenced by name in the JSON
    plugins: [persist(localStorageAdapter())], // anything createTour accepts
    }),
    );

    The document

    {
    "$schema": "https://yorigcs.github.io/awesome-tour/schema/tour.schema.json",
    "id": "first-session",
    "version": 2,
    "rules": { "trigger": { "route": "/studio" }, "frequency": { "maxShows": 2 } },
    "steps": [
    { "id": "welcome", "title": "Your first session" },
    { "id": "mixer", "target": { "anchor": "mixer" }, "side": "left", "title": "Mixer" },
    { "id": "stems", "target": "#format-stems", "when": "isPro", "title": "Stems export" },
    { "id": "play", "target": "#play", "advanceOn": { "event": "click" }, "title": "Now play it" }
    ]
    }

    Everything a step can do is available, with two translations:

    • Targets are selectors or resilient locators as objects — { "anchor": "mixer" }, { "tour": "mixer" } (byTour), { "role": "button", "name": "Export" } (byRole), { "text": "Bounce" } (byText), { "firstOf": [ … ] } — or arrays of them. Content editors can point at what they see instead of writing CSS.
    • Functions — when, canNext, beforeEnter, beforeLeave, afterLeave, advanceOn.when, a computed next ({ "action": "pick" }), rules.audience and goal.when — are action names resolved from actions.

    Validation

    fromJSON validates first and throws one error listing every problem — unknown action names, duplicate ids, next/advanceOn.to pointing at missing steps, values outside an enum (side, onTargetMissing, onTargetLost, layer, rules.frequency.once) and malformed locators. Validate without throwing (e.g. in a CMS preview) with validateTourJSON(doc, actions), which returns the list.

    The JSON Schema ships with the package — point your editor or CMS at it for autocomplete: @awesome-tour/core/schema.json.

    Previewing drafts

    Tours that live in a CMS need a way to try a draft on the real app before publishing it. Open any page with ?tour-preview=<id> and the provider loads the draft and runs it:

    import { fromJSON } from '@awesome-tour/core/json';
    <TourProvider
    tours={publishedTours}
    preview={{
    // Fetch the draft (and check the user may preview it): return tour options, or null.
    load: async (id) => {
    const res = await fetch(`/api/tours/${id}/draft`, { credentials: 'include' });
    return res.ok ? fromJSON(await res.json(), { actions }) : null;
    },
    }}
    >
    …
    </TourProvider>;

    A preview replaces the published tour with the same id while it runs, starts at ?step= if given, and is marked tour.preview: it saves no progress, records no impressions, sends no analytics and ignores display rules — so previewing on production touches nobody’s data. The registry card shows a dashed “Preview” pill (data-preview on Tour.Content). Without React, use previewFromUrl(manager, { load }).