@yarlisai/guides

プロダクト非依存のガイドツアーエンジン — 宣言的なステップ、オーディエンスターゲティング、ライフサイクルイベント。

プロダクト非依存のガイドツアーエンジン — 宣言的なステップ、プラン/ロールによるオーディエンスターゲティング、ライフサイクルイベントを備え、driver.js とヘッドレスアダプターに対応しています。

@yarlisai/guides はポート/アダプターの規約に従っています。コンシューマーは GuideEngine ポートに依存し、実行時にアダプターをインスタンス化します。エンジンは React、i18n、プラン、アナリティクスについて一切関知しません。コピー（テキスト）はリゾルバーを通じて解決済みの状態で渡され、オーディエンスターゲティングは宣言的なデータとして定義され、すべてのライフサイクル遷移（started、step_viewed、cta_clicked、completed、skipped）はホスト側が永続化またはトラッキングするための GuideEvent として発行されます。

v1 では 2 つのアダプターが同梱されています：

headless — DOM を持たないエンジン（メインバレルからエクスポート）。テスト、CLI ウォークスルー、またはサーバー主導のツアーに適しています。
driverjs — driver.js を使ったブラウザポップオーバー。driver.js は オプション のピア依存であり、アダプターは @yarlisai/guides/adapters/driverjs サブパス経由でのみ公開されるため、使用しないバンドルには含まれません。CSS はホスト側で管理します（import 'driver.js/dist/driver.css'）。設定可能な popoverClass でテーマをカスタマイズできます。

使い方

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),
})

このパッケージの README には完全なクイックスタートが含まれています。mybotbox-platform 自体がリファレンスコンシューマーです。apps/sat/lib/guides/ では薄いシムパターンを確認でき、apps/sat/components/onboarding/ ではポートを通じてプロダクトツアーを実行しています。

@yarlisai/guides

インストール

背景

使い方

関連リンク

On this page