Waylume SDK (npm) Quick Start

This guide shows the basic setup for a web app using the npm package @gitsbt/waylume-sdk. For a PHP application, see the Waylume SDK for PHP (Composer) Quick Start.

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

次へWaylume SDK for PHP (Composer) Quick Start

最終更新 27 日前

役に立ちましたか？