GuideShot docs

Publish your first guide.

By the end of this page, one command will start your app, find a stable product target, and publish an annotated WebP artifact.

1. Install the capture stack

pnpm add -D @guideshot/cli @guideshot/core @guideshot/playwright @guideshot/renderer playwright
pnpm exec playwright install chromium

2. Configure the project

GuideShot starts the existing application command and only visits origins you explicitly allow.

import { defineConfig } from '@guideshot/core'
import { playwrightDriver } from '@guideshot/playwright'
import { htmlRenderer } from '@guideshot/renderer'

export default defineConfig({
  recipes: ['shots/**/*.shot.json'],
  outputDir: 'public/generated/guideshot',
  server: { url: 'http://localhost:3000', command: 'pnpm dev' },
  safety: { allowedOrigins: ['http://localhost:3000'] },
  profiles: {
    'guide.desktop': { viewport: { width: 1280, height: 960 } }
  },
  driver: playwrightDriver(),
  renderer: htmlRenderer()
})

3. Mark the product action

Targets are stable names owned by the product. They survive layout changes better than CSS selectors.

<button data-guide-target="release.create">
  Create release
</button>

4. Write one recipe

This recipe waits for the button, captures the real page, and attaches an explanation to the named target.

{
  "$schema": "https://guideshot.dev.wemuda.com/schemas/recipe.v1.json",
  "version": 1,
  "id": "release.create",
  "profile": "guide.desktop",
  "page": { "path": "/releases" },
  "ready": [{ "expect": "visible", "target": "release.create" }],
  "annotations": [{
    "id": "create",
    "kind": "callout",
    "target": "release.create",
    "content": { "en": "Create the release from one clear action." }
  }],
  "output": { "formats": ["webp"], "width": 1600 }
}

5. Capture and verify

Validate first, inspect the planned jobs, then capture. Verify checks the manifest, files, hashes, dimensions, and alt text.

pnpm exec guideshot validate
pnpm exec guideshot plan
pnpm exec guideshot capture
pnpm exec guideshot verify