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.
Beat A
16 steps · drumsMixer
4 channelsimport { 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 computednext({ "action": "pick" }),rules.audienceandgoal.when— are action names resolved fromactions.
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 }).