Your product tour ran. Did anyone finish it?

Trailguide — Fri, 01 May 2026 14:36:55 +0000

The first article I wrote about Trailguide was about why tours should live in your repo as JSON files. The engineering case: version control, CI testing, no vendor lock-in.

This one is about what happens after you ship a tour.
The part most teams skip You add an onboarding tour. Users start seeing it. You move on to the next feature. Three months later someone asks "is that tour still working?" and nobody actually knows.
That is the default state for most teams. You built the tour, you have no data on it, and the only signal you get is the absence of complaints.

What you actually want to know is pretty simple: how many people start the tour, how many finish it, and which step is where most of them leave.

What the analytics actually show

Trailguide Pro tracks this without any setup. No events to wire up, no analytics SDK to configure. When you open the dashboard for a trail you see a completion funnel. Each step has a bar showing what percentage of sessions made it that far, color coded by health.

Most teams find the same pattern. One step causes 60 to 70 percent of abandonment. It's usually either too long, asks the user to do something before they're ready, or it fires on an element that loads slowly so the tooltip appears before the user can even read what's on the page.
Once you can see it you fix it. Before that you're guessing.

There's also a chart showing starts versus completions over time, so when you ship a fix you can actually see whether it moved the number. It compares the current period to the prior one. The loop is tight: change something, wait a few days, see if it helped.

Hearing from users directly (this is most important)

The other useful thing is getting feedback at the right moment in the flow.

Trailguide has a feedback step type. You drop it anywhere in a tour, after a tricky step or before the last one, and it shows a short prompt. Rating, freeform comment, or both. The responses go into Product Signals which does automatic sentiment scoring and pulls word themes out of the free text.

You end up with a ranked list of the words users reach for when they're confused or stuck. That's a different signal than a completion rate. One tells you where people leave. The other tells you why.

The full picture

The first article ended with "one file, two jobs." The same JSON that shows users an onboarding tour also runs as a Playwright regression test in CI.

The fuller picture is that you build the tour, users walk through it, CI catches it if something breaks, and the analytics and feedback tell you what to fix next. Then you update the JSON and ship again.

Nothing about that requires a vendor dashboard or a third party owning your content. The tours are files in your repo. The test runs in your CI pipeline. The analytics live in the Pro dashboard but they point back to a problem you fix in code.

That's the thing that took me a while to figure out how to explain. It's not really a tour tool. It's the whole cycle.

Free runtime at github.com/hellotrailguide/trailguide or try the Pro Editor free for 14 days at gettrailguide.com.

Why Product Tours Should Live in Your Git Repo

Trailguide — Tue, 03 Mar 2026 13:04:27 +0000

Why Product Tours Should Live in Your Git Repo

Most product tour tools have the same problem: they charge per user, lock your content in their dashboard, and have no answer for what happens when your UI changes and the tour breaks. You find out the same way your users do.

Trailguide is a free open-source runtime where tours are JSON files that live in your repo. No per-user pricing. No vendor lock-in. You own the content forever.

This post is about what you actually get when your tours live alongside your code.

Tours are just JSON files in your repo

A Trailguide trail looks like this:

{
  "id": "welcome",
  "title": "Welcome Tour",
  "version": "1.0.0",
  "steps": [
    {
      "id": "step-1",
      "target": "[data-trail-id='create-btn']",
      "placement": "bottom",
      "title": "Create your first project",
      "content": "Click here to get started."
    }
  ]
}

That file lives in your repo. It gets reviewed in PRs. It has a git history. You can roll it back, branch it, diff it. Everything your team already does with code applies to tours automatically — no new process, no new tools.

When a PM wants to update the copy on step three, the change goes through the same review flow as any other edit. When something breaks, git blame tells you when and why.

Recording a tour takes minutes, not days

The Pro Editor includes a Chrome extension recorder. Enter your app's URL, click Start Recording, and click through the flow you want to document. Every click captures three things automatically:

The element's CSS selector, using the most stable attribute available (data-trail-id, data-testid, aria-label, or a DOM path as a fallback)
A screenshot of the page at that moment
The exact element rect, so the editor can highlight precisely what was targeted

Selectors are graded Stable, Moderate, or Fragile based on what they target. A data-trail-id attribute is Stable — it won't break when you restructure the DOM. A fragile path selector shows a warning and ranked suggestions to fix it in one click.

When your UI ships an update, you open the editor and see the screenshot from when the tour was recorded. The broken element is highlighted. Anyone on the team can spot what changed, update the selector, and push a fix — without filing an engineering ticket or involving a developer.

Two-way Git sync means tours live where your code lives

The Pro Editor connects to GitHub and GitLab. You can load any trail file from a repo, edit it in the dashboard, and push it back as a commit or open a PR for review. The dashboard is for editing. The repo is the source of truth.

This means your tours go through the same deploy process as everything else. A tour change that hasn't been reviewed doesn't go to production any more than a code change would.

Analytics without instrumentation

The runtime tracks completion rates, step-by-step drop-off, and time per step automatically. No events to wire up. No analytics SDK to configure. When a step is losing people, you see it in the dashboard.

Most teams discover that one step causes 60% of tour abandonment. Once you can see that, you fix it. Without data, you're guessing.

One trail, two purposes

Here's the part that feels like a bonus once you already have everything above.

Set a trail's mode to "both" and the same JSON that guides your users also runs as a Playwright test in CI. Add action and assert fields to steps where you want Playwright to verify something:

{
  "id": "step-1",
  "target": "[data-trail-id='create-btn']",
  "placement": "bottom",
  "title": "Create your first project",
  "content": "Click here to get started.",
  "action": "click",
  "assert": { "type": "visible" }
}

Then write one test:

import { test } from '@playwright/test'
import { runTrail } from '@trailguide/playwright'
import welcomeTrail from './tours/welcome.json'

test('welcome tour', async ({ page }) => {
  await page.goto(process.env.BASE_URL ?? 'http://localhost:3000')
  await runTrail(page, welcomeTrail)
})

runTrail walks every step in order. If a selector is missing, an action fails, or an assertion is wrong, the test fails and the deploy is blocked. Steps without action or assert still run — Trailguide checks that the target element is present, which catches most selector regressions on its own.

You didn't write a test suite. You wrote a tour. The test is a side effect of having your onboarding in a format that CI can understand.

Most teams think of product tours and regression tests as two completely separate things — different tools, different formats, different maintenance burden. When tours are JSON files in your repo, that separation disappears. The content you wrote to teach users how to use your product is exactly what you need to verify it still works.

One file. Two jobs.

Getting started

The runtime is free and open source:

npm install @trailguide/core

The Pro Editor handles recording, Git sync (GitHub and GitLab), screenshot storage, selector quality grades, analytics, and the mode toggle — 14-day free trial, $49/month after. Every trail you create is a file in your repo that your team owns.

Visit gettrailguide.com
or
Source and full docs at github.com/hellotrailguide/trailguide.

DEV Community: Trailguide

Your product tour ran. Did anyone finish it?

Why Product Tours Should Live in Your Git Repo

Why Product Tours Should Live in Your Git Repo

Tours are just JSON files in your repo

Recording a tour takes minutes, not days

Two-way Git sync means tours live where your code lives

Analytics without instrumentation

One trail, two purposes

Getting started