Trailguide

Product tours as code. Trailguide is a lightweight, framework-agnostic SDK for building guided onboarding tours directly in your web app. Define tours in JSON, target elements with CSS selectors, and ship them as part of your codebase — not as a third-party script.

npm install @trailguide/core
# or with React:
npm install @trailguide/runtime

import { Trailguide } from '@trailguide/runtime'
import '@trailguide/core/dist/style.css'
 
const tour = {
  id: 'onboarding',
  title: 'Welcome',
  version: '1.0.0',
  steps: [
    {
      id: 'step-1',
      target: '[data-tour="dashboard"]',
      placement: 'bottom',
      title: 'Your Dashboard',
      content: 'Everything you need in one place.',
    },
  ],
}
 
export function App() {
  return <Trailguide trail={tour} onComplete={() => console.log('done')} />
}

Why Trailguide?

Most onboarding tools are third-party scripts — loaded from a CDN, configured in a dashboard, and invisible to your version control. Trailguide is different: tours live in your codebase as JSON, ship with your deploys, and get reviewed in pull requests alongside the features they document.

Packages

Free vs Pro

The SDK is fully open source (MIT). Everything in this documentation works out of the box — build tours in JSON, ship them with your code, no account needed.

Trailguide Pro is the hosted editor at app.gettrailguide.com. It gives your team a permanent home for your trails: a visual dashboard where anyone — not just developers — can open a trail, see a screenshot of what each step was pointing at, and update it when the app changes. Trails sync back to GitHub or GitLab as commits or pull requests, so nothing leaves version control.

What Pro adds:

• Hosted trail storage with screenshots — every trail lives in your dashboard. Each step is stored with a screenshot taken at the time you built it. When your app ships a redesign, open the editor, see exactly what shifted, fix it, and push the update. Non-devs can own this without touching the repo.
• Visual editor — build tours by clicking through your app. No CSS selectors to write. Drag steps to reorder, edit copy inline, and play back the full trail before you ship it. Per-step pass/fail indicators appear after a test run.
• AI-assisted step authoring — click the ✦ Suggest button on any step and Claude generates a title, body copy, and placement from the element’s context. Accept the whole suggestion or pick individual fields.
• Guided recording mode — an action quick-pick overlay appears near every clicked element so you can choose Click, Hover, or Skip before the step commits. Hold Shift while clicking to instantly capture and navigate without waiting for the overlay.
• Reusable flows — save any group of steps as a named flow and drag them into any trail to insert all those steps at once.
• Analytics — see starts, completions, and a step-by-step drop-off funnel. Know which steps lose users and whether your changes made things better.
• Git sync (GitHub + GitLab) — load existing trails straight from your repo, edit them in the dashboard, and push changes back as commits or pull/merge requests. Works with both GitHub and GitLab.
• Selector quality grades — every captured element is graded Stable, Moderate, or Fragile, with suggestions to fix brittle selectors before they break in production.
• Playwright test runner — set any trail to both mode and it runs as a Playwright regression test in CI from the same JSON file. No separate test suite to maintain.
• Test Health dashboard — track pass rates, the most frequently broken steps, and full run history across all your CI pipelines in one place. Slack and webhook failure notifications included.