Quick Start

This guide shows the basic Waylume SDK setup for a web app.

1. Install the package

npm install @gitsbt/waylume-sdk

2. Create the SDK files

Create a waylume/ directory at your app root and keep your SDK files there.

Typical structure:

your-app/
  app/
    layout.tsx
    page.tsx
    waylume-setup.tsx
  waylume/
    index.ts
    summary1.json
    summary2.json
    ...

Put each guide definition in waylume/*.json
Register all guides from waylume/index.ts
Mount the global setup once from app/layout.tsx
Render the launcher on the page where you want users to open guides

3. Add stable targets to your UI

<button data-waylume="upgrade-btn">Upgrade to Pro</button>

Use data-waylume on elements that should be referenced by guidance steps.

4. Create a flow definition

// waylume/upgrade-flow.json
{
  "id": "upgrade-flow",
  "defaultLocale": "en",
  "label": "Upgrade to Pro",
  "i18n": {
    "label": {
      "ja": "Pro にアップグレード"
    }
  },
  "steps": [
    {
      "id": "upgrade-btn",
      "summary": "Click Upgrade to Pro",
      "instruction": "Click \"Upgrade to Pro\" to begin.",
      "i18n": {
        "summary": {
          "ja": "Upgrade to Pro をクリック"
        },
        "instruction": {
          "ja": "開始するには「Upgrade to Pro」をクリックしてください。"
        }
      },
      "target": "upgrade-btn",
      "actionType": "click",
      "expectedUrlPattern": "/"
    }
  ]
}

i18n is optional. If it is omitted, the SDK uses the base label, summary, and instruction values as-is.

expectedUrlPattern must be a same-site path that starts with /, such as /login or /dashboard. Do not use absolute URLs such as https://example.com/login; the SDK rejects them to keep flows within the current site.

5. Register the flow

// waylume/index.ts
'use client'

import { registerFlows } from '@gitsbt/waylume-sdk'
import upgradeFlow from './upgrade-flow.json'

export const [UPGRADE_FLOW] = registerFlows([upgradeFlow])

registerFlows() accepts an array. Each item in that array is one imported JSON flow file from waylume/.

import summary1Flow from './summary1.json'
import summary2Flow from './summary2.json'

export const [SUMMARY1_FLOW, SUMMARY2_FLOW] = registerFlows([
  summary1Flow,
  summary2Flow,
])

6. Add a global setup component

// app/waylume-setup.tsx
'use client'

import '@/waylume'
import { useEffect } from 'react'
import { usePathname } from 'next/navigation'
import { scheduleAutoResume } from '@gitsbt/waylume-sdk'

export function WaylumeGlobal() {
  const pathname = usePathname()

  useEffect(() => {
    scheduleAutoResume()
  }, [pathname])

  return null
}

Mount that component once near the root of your app, typically from app/layout.tsx.

// app/layout.tsx
import { WaylumeGlobal } from './waylume-setup'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <WaylumeGlobal />
        {children}
      </body>
    </html>
  )
}

7. Render a launcher

'use client'

import { WaylumeLauncher } from '@gitsbt/waylume-sdk/components'

export function WaylumeGuideButton() {
  return (
    <WaylumeLauncher floating locale="en">
      <button aria-label="Open guides">?</button>
    </WaylumeLauncher>
  )
}

locale is optional. When provided, the launcher panel and flow text use the matching localized strings and fall back to the base fields if a translation is missing.

If your app already has a language state, route locale, or locale cookie, pass that current value to locale instead of hard-coding it.

export function WaylumeGuideButton({ locale }: { locale: 'en' | 'ja' }) {
  return (
    <WaylumeLauncher floating locale={locale}>
      <button aria-label={locale === 'ja' ? 'ガイドを開く' : 'Open guides'}>?</button>
    </WaylumeLauncher>
  )
}

The SDK does not read your app's i18n state automatically. Keep the locale prop in sync with your app if users can switch languages without a full page reload.

Common pitfalls

Mounting the launcher on every page

WaylumeGlobal should be mounted once from the root layout. The launcher only needs to be rendered on pages where you want users to open the guide panel.

app/
  layout.tsx          # <WaylumeGlobal /> once
  page.tsx            # launcher button visible here
  login/page.tsx      # nothing required
  dashboard/page.tsx  # nothing required

Removing `usePathname` from `WaylumeGlobal`

In the Next.js App Router, the root layout is not remounted during client-side <Link> navigation. Keep usePathname and useEffect([pathname]) so scheduleAutoResume() can run after route changes.

For flows that continue across pages, set expectedUrlPattern on the first step and on steps that wait for navigation. Use same-site paths only. Absolute URLs and protocol-relative URLs are not valid.

{
  "target": "login-link",
  "actionType": "click",
  "waitFor": "navigation",
  "expectedUrlPattern": "/login"
}

Mismatched `target` and `data-waylume`

The JSON target value must exactly match the UI element's data-waylume value.

{ "target": "upgrade-btn" }

<button data-waylume="upgrade-btn">Upgrade</button>

Missing `'use client'`

Add 'use client' to files that import the SDK client APIs or render the launcher, such as waylume/index.ts, app/waylume-setup.tsx, and launcher components.

Result

At that point, adding a new guide is mainly:

Add data-waylume targets to the UI
Create a flow JSON file in waylume/
Register the new flow in waylume/index.ts
Keep WaylumeGlobal mounted from app/layout.tsx

前へWaylume SDK 次へProduction Setup

最終更新 2 か月前

役に立ちましたか？

こんにちは

Quick Start

1. Install the package

2. Create the SDK files

3. Add stable targets to your UI

4. Create a flow definition

5. Register the flow

6. Add a global setup component

7. Render a launcher

Common pitfalls

Mounting the launcher on every page

Removing `usePathname` from `WaylumeGlobal`

Missing `expectedUrlPattern` on navigation steps

Mismatched `target` and `data-waylume`

Missing `'use client'`

Result

こんにちは

1. Install the package

2. Create the SDK files

3. Add stable targets to your UI

4. Create a flow definition

5. Register the flow

6. Add a global setup component

7. Render a launcher

Common pitfalls

Mounting the launcher on every page

Removing usePathname from WaylumeGlobal

Missing expectedUrlPattern on navigation steps

Mismatched target and data-waylume

Missing 'use client'

Result

Removing `usePathname` from `WaylumeGlobal`

Missing `expectedUrlPattern` on navigation steps

Mismatched `target` and `data-waylume`

Missing `'use client'`