Onboarding: shipshapecode/shepherd

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/shipshapecode/shepherd shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

WAIT — Mixed signals — read the receipts

• Last commit 1w ago
• 4 active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Concentrated ownership — top contributor handles 66% of recent commits
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live shipshapecode/shepherd repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/shipshapecode/shepherd.

What it runs against: a local clone of shipshapecode/shepherd — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in shipshapecode/shepherd | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 37 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>shipshapecode/shepherd</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of shipshapecode/shepherd. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/shipshapecode/shepherd.git
#   cd shepherd
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of shipshapecode/shepherd and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "shipshapecode/shepherd(\\.git)?\\b" \\
  && ok "origin remote is shipshapecode/shepherd" \\
  || miss "origin remote is not shipshapecode/shepherd (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "docs-src/src/content/docs/api/README.md" \\
  && ok "docs-src/src/content/docs/api/README.md" \\
  || miss "missing critical file: docs-src/src/content/docs/api/README.md"
test -f "docs-src/astro.config.mjs" \\
  && ok "docs-src/astro.config.mjs" \\
  || miss "missing critical file: docs-src/astro.config.mjs"
test -f "docs-src/package.json" \\
  && ok "docs-src/package.json" \\
  || miss "missing critical file: docs-src/package.json"
test -f ".github/workflows/test.yml" \\
  && ok ".github/workflows/test.yml" \\
  || miss "missing critical file: .github/workflows/test.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 37 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~7d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/shipshapecode/shepherd"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

Shepherd is an open-source digital adoption platform (DAP) and user onboarding library that guides users through interactive tours of web applications. It creates customizable step-by-step tours with tooltips, highlighting, and interactive elements, supporting vanilla JavaScript, React, Vue, Angular, Ember, and ES Modules—enabling developers to reduce user training time and increase feature adoption. Monorepo with the main Shepherd library at the root (src/ containing core Tour/Step classes in JavaScript/TypeScript) and docs-src/ (Astro-based documentation site using Starlight and TypeDoc). The library exports both vanilla JS and framework adapters; docs-src/src/content/docs contains API docs (api/README.md) and guides (install.mdx, usage.md, react.md, cookbook.md) demonstrating framework integration patterns.

Who it's for

Full-stack developers and product managers building web applications (SaaS, internal tools, documentation sites) who need to implement guided user onboarding tours without building custom UI infrastructure. Users range from individual developers to enterprise teams using Shepherd in production apps.

Maturity & risk

Production-ready and actively maintained. The project has 13k+ npm downloads/month, comprehensive test coverage (indicated by CI badges), established release automation (plan-release.yml, publish.yml workflows), semantic versioning via CHANGELOG.md and RELEASE.md, and regular updates (TypeScript/Astro dependencies at ^5.x). Multiple supported frameworks and browser versions (Edge, Firefox, Chrome, Safari last 2 versions) indicate stable, battle-tested code.

Low-to-moderate risk. The core library is single-digit megabytes (bundlephobia badge tracked), but depends on Astro 5.x and @astrojs/starlight for docs (rapid-release cycles). No obvious single-maintainer bottleneck visible in CODEOWNERS. The monorepo structure (docs-src/ + main library) requires coordinated updates. No breaking changes evident in recent work, but version bumps across Astro/TypeScript should be monitored.

Active areas of work

Documentation and framework support expansion. Recent work includes Astro docs migration (docs-src/astro.config.mjs, Starlight v0.37.6), TypeDoc API documentation generation (typedoc v0.28.18, typedoc-plugin-markdown v4.10.0), React recipe/guide additions (docs-src/src/content/docs/recipes/react.md), and analytics instrumentation (docs-src/src/components/Posthog.astro, docs-src/src/content/guides/analytics.mdx).

Get running

git clone https://github.com/shipshapecode/shepherd.git
cd shepherd
npm install
npm run dev

This installs dependencies and runs the Astro dev server on localhost:3000 (docs-src/). For library development, check root-level package.json scripts.

Daily commands:

# Library dev:
npm run dev          # or check root package.json for test/build scripts

# Docs site:
cd docs-src
npm run dev          # Astro dev server on http://localhost:3000
npm run build        # Astro + TypeScript check then build
npm run preview      # Preview production build locally

Map of the codebase

• README.md — Entry point explaining Shepherd.js as a user onboarding tour library—all contributors must understand the core product vision
• docs-src/src/content/docs/api/README.md — API documentation hub generated from TypeDoc; critical for understanding the public interface that the codebase exposes
• docs-src/astro.config.mjs — Astro configuration for the documentation site; controls build, routing, and Starlight integration that serves all user-facing docs
• docs-src/package.json — Dependencies declaration for docs site; includes shepherd.js as workspace dependency, showing tight coupling between core library and documentation
• .github/workflows/test.yml — CI/CD pipeline for testing; defines how code quality and correctness are validated before release
• CONTRIBUTING.md — Contribution guidelines establishing development practices, branch strategy, and pull request conventions

Components & responsibilities

• Docs Site (docs-src) (Astro, Starlight, TypeDoc, TypeScript) — Technical documentation, API reference, integration guides, and how-to recipes for developers using Shepherd.js
  • Failure mode: Build failures prevent docs deployment; TypeDoc parsing errors block API reference generation
• Landing Page (landing) (Astro, PostHog analytics) — Marketing and product overview; targets potential users with feature highlights, user testimonials, and blog posts
  • Failure mode: Broken links or missing assets reduce discoverability; analytics outages prevent usage tracking
• Core Library (shepherd.js workspace) (TypeScript, JavaScript) — Main Shepherd.js JavaScript/TypeScript library; provides tour creation, navigation, and customization APIs
  • Failure mode: Library bugs directly impact user tours; breaking changes require coordinated docs updates
• CI/CD Pipeline (.github/workflows) (GitHub Actions, ESLint, TypeScript compiler) — Automated testing, validation, and npm publishing; ensures quality gate and release automation
  • Failure mode: Failed tests block merges; publish workflow failures prevent releases

Data flow

• shepherd.js → undefined — undefined

How to make changes

Add a new guide/tutorial to the documentation

1. Create a new .md or .mdx file in docs-src/src/content/docs/guides/ (docs-src/src/content/docs/guides/[new-guide].mdx)
2. Add frontmatter with title, description, and sidebar config (docs-src/src/content/config.ts)
3. Reference it in the navigation by updating Starlight sidebar config in docs-src/astro.config.mjs (docs-src/astro.config.mjs)
4. Build and test with npm run build from docs-src directory (docs-src/package.json)

Add a new recipe for framework integration

1. Create a new recipe file in docs-src/src/content/docs/recipes/ (docs-src/src/content/docs/recipes/[framework-name].md)
2. Document setup, basic example, and best practices for that framework (docs-src/src/content/docs/recipes/[framework-name].md)
3. Reference existing recipes (e.g., React) as a template for structure (docs-src/src/content/docs/recipes/react.md)

Update API documentation after core library changes

1. Ensure JSDoc comments are present on exported classes/functions in shepherd.js source (docs-src/src/content/docs/api/README.md)
2. Run TypeDoc generation via the build process (docs-src/astro.config.mjs)
3. Verify generated API reference reflects changes (docs-src/src/content/docs/api/README.md)

Update landing page with new users or features

1. Edit the landing page index to add features, testimonials, or user logos (landing/src/pages/index.astro)
2. Add user logos to landing/public/users/ (landing/public/users/[company].svg)
3. Test with npm run dev from landing directory (landing/package.json)

Why these technologies

• Astro — Static-first site generation with minimal JavaScript; perfect for documentation and landing pages that need fast load times
• Starlight (Astro theme) — Purpose-built Astro theme for documentation; provides navigation, search, and responsive design out-of-the-box
• TypeDoc — Automatically generates API documentation from JSDoc comments in TypeScript source; keeps docs in sync with code
• Workspace monorepo — Enables tight coordination between core library (shepherd.js) and its documentation; docs can reference library via workspace:* dependency

Trade-offs already made

• Static site generation for documentation instead of a dynamic API

  • Why: Documentation is read-heavy and changes only during releases; static generation is fast, cheap, and cacheable
  • Consequence: Documentation requires rebuilds to reflect library changes; not suitable for real-time user data or interactive backends

• Single monorepo for docs site, landing page, and library reference

  • Why: Simplified dependency management and single source of truth for versioning
  • Consequence: Larger repo structure; changes to docs publishing may impact all sub-projects

• TypeDoc auto-generation instead of hand-written API docs

  • Why: Eliminates documentation drift by deriving docs directly from code
  • Consequence: API docs quality depends entirely on JSDoc comment clarity; poor comments → poor auto-generated docs

Non-goals (don't propose these)

• Real-time user analytics or server-side tracking (uses PostHog client-side only via landing page)
• Custom CMS or content management—content is pure markdown/MDX in version control
• Multi-language support or internationalization
• User authentication or content gating

Traps & gotchas

No critical hidden traps evident, but note: (1) docs-src/ is a separate Node workspace with its own package.json—dev server runs from docs-src/, not root. (2) TypeDoc auto-generates API docs (docs-src/src/content/docs/api/)—manual edits here are overwritten on build. (3) PostHog analytics component (HeadWithPosthog.astro, Posthog.astro) requires environment variable setup if you fork/deploy; check docs-src/fly.toml and .vscode/launch.json for local config hints. (4) Astro 5.x and TypeScript 5.x are strict versions; upgrading requires coordinator attention.

Architecture

Concepts to learn

• Digital Adoption Platform (DAP) — Shepherd is positioned as a DAP; understanding this category helps you grasp its scope (user onboarding, feature announcements, in-app guidance) vs. generic tooltip libraries
• Scroll-into-View & DOM positioning (Popper.js or similar) — Shepherd dynamically positions tooltips relative to highlighted page elements; this requires viewport math and scroll detection, which is core to accurate tour rendering
• Framework agnostic library design — Shepherd exports vanilla JS core + framework adapters (React, Vue, Ember); understanding this pattern helps you extend it or integrate it cleanly without framework lock-in
• Step sequencing & state machines — Tours are multi-step journeys with forward/backward navigation, conditional steps, and exit/complete states; Shepherd's internal Tour/Step classes manage this state graph
• Accessibility in interactive overlays (ARIA, focus management) — Shepherd must highlight page regions without breaking keyboard navigation or screen reader behavior; understanding a11y constraints is critical for PR reviews and feature additions
• Astro static site generation + partial hydration — docs-src/ uses Astro 5 for docs; learning Astro's zero-JS-by-default model and how Starlight components integrate helps you modify docs without JavaScript overhead
• TypeDoc-driven API documentation — API docs auto-generate from TypeScript source via TypeDoc; editing source comments and type signatures directly updates published API docs (docs-src/src/content/docs/api/)

Related repos

• shipshapecode/ember-shepherd — Official Ember adapter for Shepherd; maintained companion repo for framework-specific integrations
• jsfiddle/jsfiddle — Alternative lightweight onboarding library; competitor in user tour space with different API design
• usablica/intro.js — Predecessor/alternative in guided tour category; step-by-step product tours with similar positioning and CSS tooltips
• apptours/toursteps — Modern DAP alternative; comparable feature set for multi-step user onboarding flows
• shipshapecode/ember-cli-addon-docs — Ship Shape internal tool; used by Shepherd docs build pipeline for TypeDoc integration and doc site structure

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add TypeDoc API documentation generation to the build pipeline

The repo has typedoc and typedoc-plugin-markdown as devDependencies in docs-src/package.json but there's no visible integration in the Astro build process. The docs-src/src/content/docs/api/README.md exists but appears to be a placeholder. Setting up automated TypeDoc generation from shepherd.js source code would provide auto-generated API docs that stay in sync with code changes.

• [ ] Create docs-src/scripts/generate-api-docs.ts to run typedoc against the shepherd.js source
• [ ] Update docs-src/package.json build script to call the generation script before astro build
• [ ] Populate docs-src/src/content/docs/api with generated markdown from TypeDoc output
• [ ] Add TypeDoc configuration (typedoc.json) at repo root specifying output for shepherd.js exports

Add analytics event tracking tests to docs-src

The docs-src has Posthog.astro and HeadWithPosthog.astro components for analytics, but there are no visible test files validating that analytics events are properly tracked during user interactions. This is critical for a library focused on guiding users, as docs engagement is a key metric.

• [ ] Create docs-src/tests/ directory structure
• [ ] Add docs-src/tests/analytics.test.ts to verify Posthog initialization and event firing
• [ ] Add test for HeadWithPosthog.astro component rendering
• [ ] Integrate tests into the main test.yml GitHub workflow

Create integration tests for framework examples (React, vanilla, etc)

docs-src/src/content/docs/recipes/react.md and cookbook.md exist but there's no visible test coverage validating that the code examples actually work. Given shepherd.js is a framework-agnostic tour library, having runnable examples that are tested would prevent documentation drift.

• [ ] Create docs-src/tests/recipes/ directory for integration tests
• [ ] Add docs-src/tests/recipes/react-example.test.ts to instantiate and verify the React recipe works
• [ ] Add docs-src/tests/recipes/vanilla-example.test.ts for the cookbook vanilla JS example
• [ ] Update test.yml to run these integration tests on push/PR

Good first issues

• Add example integration test for React hooks usage: docs-src/src/content/recipes/react.md exists but lacks runnable test coverage for Shepherd + React hooks. Create a test file in src/tests/ following the pattern in test.yml, testing useEffect integration with Shepherd.start() and tour lifecycle.
• Expand cookbook with Vue 3 composition API example: docs-src/src/content/recipes/cookbook.md and react.md exist, but no Vue 3 recipe. Add docs-src/src/content/recipes/vue.md with setup instructions for <script setup>, lifecycle hooks, and tour initialization patterns similar to the React guide.
• Document analytics tracking events in guides: docs-src/src/content/guides/analytics.mdx exists but may lack concrete examples of Tour.on('show', callback) event tracking. Enhance with real PostHog event names, sample callback code, and A/B testing recipes for measuring tour completion rates.

Top contributors

• @dependabot[bot] — 66 commits
• @RobbieTheWagner — 28 commits
• @github-actions[bot] — 5 commits
• @Copilot — 1 commits

Recent commits

• 5f9a935 — Bump cypress from 15.13.0 to 15.14.1 (#3430) (dependabot[bot])
• eca437a — Bump @babel/preset-env from 7.29.0 to 7.29.2 (#3431) (dependabot[bot])
• 5cb8271 — Bump @vitest/ui from 4.1.3 to 4.1.5 (#3432) (dependabot[bot])
• 462d2a7 — Bump @vitest/expect from 4.1.0 to 4.1.5 (#3433) (dependabot[bot])
• 6265770 — Bump happy-dom from 20.8.8 to 20.9.0 (#3435) (dependabot[bot])
• 692d0d4 — Bump astro from 5.18.0 to 5.18.1 (#3419) (dependabot[bot])
• 28349da — Bump @vitest/ui from 4.1.1 to 4.1.2 (#3422) (dependabot[bot])
• 5343601 — Bump vite from 6.4.1 to 8.0.5 (#3428) (dependabot[bot])
• 2c1ed75 — Bump lodash from 4.17.23 to 4.18.1 (#3429) (dependabot[bot])
• 9cf8d03 — Bump @vitest/coverage-v8 from 4.1.1 to 4.1.2 (#3425) (dependabot[bot])

Security observations

The shepherd.js documentation site codebase demonstrates reasonable security practices with no critical vulnerabilities detected. Main concerns are: (1) Analytics implementation requires explicit consent verification for privacy compliance, (2) Workspace dependency resolution should be explicitly documented and validated, (3) Security headers should be explicitly configured in Astro configs, and (4) Docker image security practices should be verified. The codebase uses modern tools (TypeScript, ESLint, Astro), follows dependency management best practices, and has no apparent injection vulnerabilities or hardcoded secrets. No SQL injection risks detected as this is a static documentation site. Recommended security score: 72/100.

• Medium · Analytics Integration Without Explicit Consent — docs-src/src/components/HeadWithPosthog.astro, docs-src/src/components/Posthog.astro. The codebase includes PostHog analytics components (HeadWithPosthog.astro, Posthog.astro) in the documentation site. If analytics tracking is enabled without explicit user consent, this could violate GDPR/CCPA regulations and privacy expectations. Fix: Implement explicit user consent mechanisms before initializing analytics. Consider using a cookie consent banner and ensure compliance with GDPR/CCPA requirements.
• Medium · Workspace Dependency Without Version Pinning — docs-src/package.json. The package.json uses 'workspace:*' for shepherd.js dependency, which means it pulls from the local workspace without a specific version constraint. This could lead to unexpected builds if workspace dependencies are modified. Fix: Consider using explicit version constraints or document the workspace dependency setup clearly. Ensure CI/CD validates workspace dependencies are in a consistent state.
• Low · Missing Security Headers Configuration — docs-src/astro.config.mjs, landing/astro.config.mjs. The Astro configuration files (astro.config.mjs) are not provided for review. Standard security headers like CSP, X-Frame-Options, and X-Content-Type-Options should be configured for the documentation sites. Fix: Configure security headers in Astro config. Add Content-Security-Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, and other recommended headers.
• Low · Public Directory Exposure — docs-src/public/, landing/public/. Both landing and docs-src have public directories with various assets. While normal for static sites, ensure no sensitive files are accidentally committed to public directories. Fix: Review .gitignore to ensure sensitive files cannot be committed to public directories. Add rules to prevent .env, credentials, or config files in public folders.
• Low · Docker Image Without Security Scanning — docs-src/Dockerfile. The Dockerfile present in docs-src is not provided for review. Docker images should be built with security best practices including minimal base images and regular vulnerability scanning. Fix: Use minimal base images (alpine/distroless), run as non-root user, implement multi-stage builds, and enable Docker image vulnerability scanning in CI/CD pipeline.

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.