@techwarq/tour-engine
v0.1.0
Published
Instrument your app to capture flows for launchvid — screenshots, screen recording, waypoints, interactions.
Maintainers
techwarqReadme
@techwarq/tour-engine
Instrument your app to capture real product flows — screenshots, screen recordings, interaction data, and waypoints — then feed them to launchvid to generate polished launch videos.
Install
npm install @techwarq/tour-engineQuick start
1. Create tour.config.ts in your project root
import type { TourConfig } from '@techwarq/tour-engine';
const config: TourConfig = {
project_name: "MyProduct",
output_dir: "./tour-output",
app_url: "http://localhost:3000", // your dev server
capture: {
screenshots: true,
video: true,
interactions: true,
components: true,
},
};
export default config;2. Wrap your app root
Next.js App Router (app/layout.tsx):
import { TourProvider } from '@techwarq/tour-engine';
import tourConfig from '../tour.config';
export default function RootLayout({ children }) {
return (
<html>
<body>
<TourProvider config={tourConfig}>{children}</TourProvider>
</body>
</html>
);
}React / Vite (src/main.tsx):
import { TourProvider } from '@techwarq/tour-engine';
import tourConfig from '../tour.config';
ReactDOM.createRoot(document.getElementById('root')!).render(
<TourProvider config={tourConfig}>
<App />
</TourProvider>
);Vue 3 (src/main.ts):
import { TourPlugin } from '@techwarq/tour-engine';
import tourConfig from '../tour.config';
app.use(TourPlugin, tourConfig);3. Mark key pages with waypoints
import { TourWaypoint } from '@techwarq/tour-engine';
export default function Dashboard() {
return (
<TourWaypoint name="dashboard" description="Main application dashboard">
<div className="dashboard">...</div>
</TourWaypoint>
);
}Or use the hook:
import { useTourWaypoint } from '@techwarq/tour-engine';
const ref = useTourWaypoint({ name: "dashboard", description: "Main dashboard" });
return <div ref={ref}>...</div>;4. Add the capture script to package.json
{
"scripts": {
"tour:capture": "tour-engine capture --config tour.config.ts"
}
}5. Start your app, then capture
# Terminal 1
npm run dev
# Terminal 2
npm run tour:captureCaptured assets are written to ./tour-output/<project_name>/:
tour-output/MyProduct/
├── manifest.json ← launchvid reads this
├── screenshot-hero.png
├── screenshot-dashboard.png
├── screenshot-pricing.png
└── session.webm ← full session recording6. Generate your launch video
launchvid --sdkCLI reference
tour-engine capture [options]
Options:
-c, --config <path> Path to tour.config.ts (default: "tour.config.ts")
-u, --url <url> App URL, overrides config.app_url
-v, --verbose Print each waypoint as it is captured
-h, --helpTourConfig reference
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| project_name | string | ✓ | Used as output folder name and in the manifest |
| output_dir | string | ✓ | Where to write captured assets |
| app_url | string | | Dev server URL (default: http://localhost:3000) |
| capture.screenshots | boolean | | Capture screenshots at each waypoint |
| capture.video | boolean | | Record a full session video |
| capture.interactions | boolean | | Log click and focus events |
| capture.components | boolean | | Collect data-component attribute values |
How it works
- TourProvider / TourPlugin instruments your React/Vue app at runtime and sets
data-tour-waypointattributes on marked elements. tour-engine capturelaunches a headless Playwright browser, navigates to your running app, and finds all[data-tour-waypoint]elements.- At each waypoint it scrolls into view, waits for animations to settle, and takes a 1920×1080 screenshot.
- A full session video is recorded by Playwright's built-in recorder.
- Click and focus events are intercepted via an injected script.
- Everything is written to
manifest.jsonin the output directory, whichlaunchvid --sdkreads.