@yarlisai/guides

Product-agnostic guided-tour engine — declarative steps, plan/role audience targeting, and lifecycle events, with driver.js + headless adapters.

Install

npm install @yarlisai/guides
# for the driver.js adapter:
npm install driver.js

Why

@yarlisai/guides follows the port/adapter contract: consumers depend on the GuideEngine port and instantiate an adapter at runtime. The engine knows nothing about React, i18n, plans, or analytics — copy arrives resolved via a resolver, audience targeting is declarative data, and every lifecycle transition (started, step_viewed, cta_clicked, completed, skipped) is emitted as a GuideEvent for the host to persist or track.

Two adapters ship at v1:

• headless — no-DOM engine (exported from the main barrel) for tests, CLI walkthroughs, or server-driven tours.
• driverjs — driver.js-backed browser popovers. driver.js is an optional peer dependency, and the adapter is exposed only via the @yarlisai/guides/adapters/driverjs subpath so it never lands in bundles that don't use it. CSS stays host-side (import 'driver.js/dist/driver.css'), themed via the configurable popoverClass.

Usage

import { createGuideEngine, registerGuide, getGuide } from '@yarlisai/guides'

registerGuide({
  id: 'onboarding:build_agent',
  version: '2026.06',
  steps: [
    { id: 'canvas', anchor: 'canvas', i18nKey: 'tour.canvas' },
    {
      id: 'deploy',
      anchor: 'deploy-button',
      i18nKey: 'tour.deploy',
      audience: { roles: ['admin', 'editor'] },
    },
  ],
})

// Adapter selection is config — the chosen module is dynamic-imported.
const engine = await createGuideEngine('driverjs')

engine.start(getGuide('onboarding:build_agent')!, {
  copy: (step) => ({ title: t(`${step.i18nKey}.title`), body: t(`${step.i18nKey}.body`) }),
  labels: { next: t('next'), previous: t('back'), done: t('done'), progress: '{{current}}/{{total}}' },
  context: { plan: 'free', role: 'admin' },
  onEvent: (event) => analytics.track(event),
})

The package's README ships a complete quickstart. mybotbox-platform itself is the reference consumer — apps/sat/lib/guides/ shows the thin-shim pattern and apps/sat/components/onboarding/ drives the product tour through the port.

See also

• Source
• npm
• ADR 0007 — Port/adapter contract