Open-source project
shipshapecode/shepherd avatar
shipshapecode/shepherd

Shepherd.js: an AGPL core with a commercial half, and release tags named after the React wrapper

Guide your users through a tour of your app

13,833 stars656 forksJavaScriptNOASSERTION

At a glance

What is it?
Shepherd.js is an open source user onboarding tour library that guides people through an app, with framework wrappers, a pnpm monorepo and a dual licensing model. This covers what the license means for a commercial product, why the three newest tags are all scoped to the React wrapper, what the build and test scripts require, and where the documentation actually lives.
Who is it for?
Shepherd.js fits teams that already know which wrapper they will use, on the React side in particular, and that read the licensing terms before shipping rather than after. It does not fit a product that needs the AGPL half to disappear quietly, since the commercial license is a separate purchase.
Can I use it commercially?
Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
Is it still maintained?
Yes. The repository last received commits 2 days ago.
What is it written in?
Mainly JavaScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • shipshapecode/shepherd13,833 ★ · +20
Star history
Repository2026-09-222026-11-15
shipshapecode/shepherd13.8k13.8k

20 Stars in the last 54 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The manifest records AGPL-3.0, the terms require a second decision

The root package.json declares `"license": "AGPL-3.0"` and nothing else. The licensing section of the README is longer and says Shepherd.js is dual licensed under AGPL-3.0 and a commercial license, free for open source and non commercial use under AGPL-3.0, with a commercial license required for commercial products and revenue generating companies. Those two statements are not in conflict, but they answer different questions, and the shorter one is the one a license scanner will read. For a team shipping inside a product, the sequence matters: the AGPL text is what you inherit automatically, and the commercial half is a purchase, not a configuration flag. The README points at LICENSE.md for complete details and at shepherdjs.dev/pricing for buying one, which means the terms a lawyer needs are in the repository while the transaction is not.

The three newest tags are all named after the React wrapper

The most recent tags read v7.0.6-react-shepherd on 2026-08-24, v7.0.5-react-shepherd on 2026-08-10 and v7.0.4-react-shepherd on 2026-03-11. Each one names a workspace package, not the library as a whole, which means the tag list on its own tells you nothing about the core version. One way to get the wrong dependency is copying a version number off the releases page gives you a tag that npm cannot resolve as a core package, and a core version you have to go hunting for in the shepherd.js workspace. The project does version packages independently, which means that the wrapper release and the core release you need are two separate facts. Pin the version declared in the package.json of the package you actually import.

The core is built first, then everything except the docs and the landing page

The build script states the dependency order outright.

json
"build": "pnpm -F shepherd.js build && pnpm -F '!shepherd.js' -F !landing -F !shepherd-docs build",
"prepare": "pnpm -F shepherd.js build",
"dev": "pnpm watch"

The core lives in the top level `shepherd.js/` directory and is referenced from the root devDependencies as `shepherd.js` at `workspace:*`. The second half of the build excludes three workspaces by name, `shepherd.js`, `landing` and `shepherd-docs`, while the top level directories are `landing/` and `docs-src/`, so package names and directory names do not line up and the filter is the only place the doc workspace appears. The `prepare` hook builds the core on install, which is why a fresh clone compiles something before you run anything. Two smaller things sit in the same tree: `.nojekyll` for the published site, and a committed `stderr.log` at the top level, evidence of a command whose output was tracked rather than cleaned.

Node 22.12, pnpm 11.21.0, and no npm path through these scripts

The toolchain floor is stated in the root manifest: `"packageManager": "[email protected]"` and `"engines": { "node": ">= 22.12" }`, with a `.tool-versions` file and `pnpm-workspace.yaml` plus `pnpm-lock.yaml` beside them. Every script in the file is written in pnpm filter syntax, including the whole lint family, which fans out as `pnpm -F '*' lint`, `lint:js`, `lint:prettier` and `lint:fix`. That has a concrete consequence for contributors: the repo does not contain an npm or yarn equivalent of any of it, so running the project's own checks means installing the pinned pnpm and a Node at or above 22.12. The dev and start scripts both reduce to the same watch task in the core package.

Two test tiers, and the CI path rebuilds before it runs

The test surface is split into unit and browser tiers, each with a CI and a watch form.

json
"test:ci": "pnpm build && pnpm -F shepherd.js test:ci",
"test:unit:ci": "pnpm -F shepherd.js test:unit:ci",
"test:cy:ci": "pnpm -F shepherd.js test:cy:ci",
"cypress:install": "pnpm -F shepherd.js cypress:install",
"types:check": "pnpm -F shepherd.js types:check",
"view-coverage": "pnpm -F shepherd.js view-coverage"

The Cypress binaries are a separate step, `cypress:install`, which means a unit-only run on a fresh clone gives you unit results and no end to end signal at all, and the browser suite depends on you remembering the install first. The aggregate `test:ci` builds the whole workspace before delegating to the core package, so it is the slower path and the one that catches cross package breakage. `types:check` and `view-coverage` are separate from both, so type checking and coverage reporting are opt in rather than part of the default loop.

One wrapper is vendored, three live in other repositories

Four framework surfaces are offered and they are not maintained the same way. The React wrapper sits in this repository under `packages/react`, and the most recent releases are tagged against it. The Angular wrapper is a separate repository, angular-shepherd, the Vue wrapper is vue-shepherd, both under the shipshapecode organisation, and the Ember wrapper is ember-shepherd by RobbieTheWagner. The core also works on its own with ES Modules or plain JavaScript, which is the only surface fully covered by the scripts in this tree. The consequence for a version upgrade is uneven: a React user waits for the next wrapper release inside this repo, while Angular, Vue and Ember users wait for their own maintainers, on schedules this repository does not control and does not describe. No compatibility matrix is published, so check the wrapper release notes yourself.

Docs live off repo, and the README's own tutorials link targets the wrapper

The documentation story splits in three directions. The Resources section points at the website, the documentation site at docs.shepherdjs.dev, the demo, and a Discord server. The repository carries `docs-src/` and `landing/` as separate directories, and `prettier-plugin-astro` appears in the root devDependencies. And the tutorials entry in the README links to `packages/react`, which means the guided path most newcomers follow is the React wrapper's. The README itself contains no inline usage example, no options reference and no code block, so first run knowledge is entirely off repo. If you are not on React, the tutorial that greets you is documenting someone else's integration, and the wrapper repositories are the source of truth for yours.

The adopters list shows tours inside other people's frameworks

The projects section is a useful map of what real deployments look like. Drupal's core tour module uses Shepherd for its own module tours and lets developers add tours to custom and contributed modules. SimplePlanner uses it for onboarding, and the tour only appears once you have signed up through OAuth or email, so the library sits behind an authentication step. LogSeq uses it for initial setup steps, Snapsure for teaching photographers to configure weather alerts, the Rails engine abraham generates and tracks tours inside an application, and a Budibase plugin by JayP718 turns it into a walkthrough builder for low code apps. Two things follow. First, a tour lives inside someone else's product, so a regression in positioning or focus handling is a bug your users report against your app. Second, these are the claims of other projects, not verified integrations, so treat them as a shape of use rather than a reference.

Editorial conclusion

Shepherd.js fits teams that already know which wrapper they will use, on the React side in particular, and that read the licensing terms before shipping rather than after. It does not fit a product that needs the AGPL half to disappear quietly, since the commercial license is a separate purchase. Before you commit, check the exact wrapper version against the core version in its package.json rather than trusting a tag name, run the full test chain including the Cypress step on your own Node version, and read LICENSE.md end to end.

Frequently asked questions

Is Shepherd.js free for commercial use?

Not under the default terms. Shepherd.js is dual licensed under AGPL-3.0 and a commercial license: the AGPL half is free for open source and non commercial use, while commercial products and revenue generating companies need the commercial license. The full terms are in LICENSE.md and the purchase path is shepherdjs.dev/pricing.

Which frameworks does Shepherd.js support?

React, Ember, Angular, Vue.js, ES Modules and plain JavaScript. The React wrapper ships inside this repository under `packages/react`, the Angular and Vue wrappers are separate repositories, angular-shepherd and vue-shepherd, and the Ember wrapper is ember-shepherd by RobbieTheWagner.

Which browsers does Shepherd.js support?

The support table in the README lists Edge, Firefox, Chrome and Safari, with "last 2 versions" given for Firefox, Chrome and Safari. A `.browserslistrc` file is present at the top level of the repository, so the browser targets are also part of the build configuration.

How do I run the Shepherd.js test suite locally?

Use Node 22.12 or newer with pnpm 11.21.0. The root scripts offer `test:unit:ci` and `test:unit:watch` for the unit tier, `test:cy:ci` and `test:cy:watch` for the Cypress tier after running `cypress:install`, and `test:ci`, which builds the workspace first and then delegates to the core package. `types:check` and `view-coverage` are separate commands.

What is Shepherd.js used for?

It is an open source digital adoption platform and user on boarding service for building guided tours, trainings and announcements inside an app. It is used in production by Drupal's core tour module, LogSeq, SimplePlanner, Snapsure, the abraham Rails engine and a Budibase tour plugin.

Official sources

  1. Issues
  2. Project website
  3. README
  4. Releases
  5. shipshapecode/shepherd on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/shipshapecode-shepherd.svg)](https://hysenlabs.com/projects/shipshapecode-shepherd)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/shipshapecode-shepherd.svg)](https://hysenlabs.com/projects/shipshapecode-shepherd)

Was this useful?