Skip to content
awesome-tour

Type to search every page.

    EPersistenceContents

    Persistence

    Save tour progress with the persist plugin and storage adapters, version it, and sync it across tabs.

    import { createTour, localStorageAdapter, persist } from '@awesome-tour/core';
    const onboarding = createTour({
    id: 'onboarding',
    version: 3,
    steps,
    plugins: [persist(localStorageAdapter(), { persistData: true })],
    });

    persist(adapter, options?)

    A plugin that writes { status, stepId, version } to the adapter whenever the status or step changes, and reads it back in beforeStart. For tours with a goal it also saves when the last run started and whether the goal was reached, and resumes watching it on the next visit (tour.trackGoal).

    Option Type Default Description
    key (tourId: string) => string (id) => id Storage key for a tour (the adapter may add its own prefix).
    resume boolean true Start again from the last saved step.
    once boolean true Don’t start tours saved as completed or skipped. start({ force: true }) / restart() still work.
    persistData boolean false Also save tour.data (on every change) and restore it on start.
    sync boolean true Keep tabs in sync. When the adapter supports subscribe, a tour completed or skipped in another tab finishes here too; and starting (or resuming) the tour in one tab pauses it in the others (BroadcastChannel), so it never runs twice at once.
    onError (error, { key, operation }) => void console warning A failed read, a rejected write, or a malformed saved value. A failed read blocks automatic starts (progress is unknown) but never start({ force: true }).
    migrate Record<number, (saved) => PersistedTourState | null> — Upgrade progress saved by an older version instead of dropping it. migrate[v] turns a v state into a v + 1 one; steps chain up to the current version.

    What happens on start()

    1. The saved value is read (adapter.get(key)). Nothing saved → normal start.
    2. A value that isn’t a saved tour state (hand-edited storage, another app’s key) is reported to onError, removed, and ignored.
    3. Saved version is older than tour.version → it’s upgraded through migrate (and saved back); without a path to the current version, the entry is removed and the tour starts fresh. Saved by a newer version (an older build still running somewhere) → it’s ignored and left untouched: this tour won’t overwrite it.
    4. force: true → normal start (saved progress ignored).
    5. once and the saved status is completed / skipped → the start is blocked (status stays as it was).
    6. Otherwise the tour resumes at the saved stepId (if resume) with the saved data (if persistData).

    States active, paused, closed, completed and skipped are written; idle and starting are not.

    PersistedTourState

    Field Type Description
    status TourStatus Last status.
    stepId string | null Last step.
    version number tour.version when saved.
    data unknown Only with persistData.
    updatedAt number Date.now() when saved.

    Adapters

    PersistenceAdapter

    Any object with this shape — sync or async — works. It’s generic, so checklists reuse it (PersistenceAdapter<ChecklistSnapshot>).

    interface PersistenceAdapter<T = PersistedTourState> {
    get(key: string): T | null | undefined | Promise<T | null | undefined>;
    set(key: string, value: T): void | Promise<void>;
    remove(key: string): void | Promise<void>;
    /** Optional: notify about changes made elsewhere (other tabs, server push). */
    subscribe?(key: string, listener: (value: T | null) => void): () => void;
    }

    localStorageAdapter(options?)

    Stores JSON in localStorage under prefix + key, and implements subscribe with the storage event (cross-tab sync). Fails silently when storage is unavailable (SSR, privacy mode, quota).

    Option Type Default
    prefix string 'awesome-tour:'
    persist(adapter, {
    migrate: {
    // v1 → v2: the "upload" step was renamed "import".
    1: (saved) => ({ ...saved, stepId: saved.stepId === 'upload' ? 'import' : saved.stepId }),
    },
    });

    sessionStorageAdapter(options?)

    Like localStorageAdapter, but progress lives as long as the browser tab (no cross-tab sync).

    memoryStorage()

    In-memory Map. Progress is lost on reload — handy in tests and for “per session” tours.

    httpAdapter(options)

    Progress that follows the user across devices, through your API: GET, PUT and DELETE on ${url}/${key} (a GET answering 404 means “nothing saved”).

    import { httpAdapter, persist } from '@awesome-tour/react';
    const server = httpAdapter({
    url: '/api/tour-progress',
    headers: async () => ({ authorization: `Bearer ${await getToken()}` }),
    });
    createTour({ id: 'onboarding', steps, plugins: [persist(server, { key: (id) => `${userId}:${id}` })] });
    Option Type Default Description
    url string — Base URL; the key is appended.
    headers HeadersInit | () => HeadersInit | Promise — Sent with every request.
    fetch typeof fetch global fetch Custom fetch (tests, SSR, interceptors).
    debounce number 300 Coalesce rapid writes per key (ms).
    retries number 3 Retries for a failed write (network error, 5xx, 429), with exponential backoff.
    retryDelay number 500 First retry delay (ms); doubles each time.
    pollInterval number — Poll subscribed keys (ms), so progress made on another device reaches this one (enables sync).
    readErrors 'empty' | 'throw' 'empty' A failed read: behave like “nothing saved” (not cached, so the next read retries), or reject.
    onError (error, { key, method }) => void — Every request that finally failed.

    Reads hit the network once per key, then a cache. Writes are optimistic (cached immediately), debounced, retried with backoff, and flushed with keepalive when the page is hidden, so closing the tab doesn’t lose the last step. Call adapter.flush() to send pending writes yourself (before a logout, say). A 404 means “nothing saved”; any other failure is never cached.

    Anything else — Supabase, Firebase, your own store — is a PersistenceAdapter: get, set, remove (sync or async) and an optional subscribe.

    readTourProgress(adapter, tourId, options?)

    Reads the saved state, e.g. to show a “Resume tour” button.

    const saved = await readTourProgress(localStorageAdapter(), 'onboarding');
    if (saved?.status === 'closed') showResumeButton();

    If you gave persist a custom key, pass the same function:

    const key = (id: string) => `${user.id}:${id}`;
    persist(adapter, { key });
    await readTourProgress(adapter, 'onboarding', { key });

    See the persistence guide.