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()
- The saved value is read (
adapter.get(key)). Nothing saved → normal start. - A value that isn’t a saved tour state (hand-edited storage, another app’s key) is reported to
onError, removed, and ignored. - Saved
versionis older thantour.version→ it’s upgraded throughmigrate(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. force: true→ normal start (saved progress ignored).onceand the saved status iscompleted/skipped→ the start is blocked (status stays as it was).- Otherwise the tour resumes at the saved
stepId(ifresume) with the saveddata(ifpersistData).
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.