Shepherd.js: building product tours in JavaScript, and the licence that decides whether you can ship it

What Shepherd.js actually solves, and who it is for

New users land in an application with no idea which button matters. Shepherd exists to attach a sequence of steps to specific elements in your page and walk the user through them: a first-run tour, a training flow, or an announcement pinned to a feature you just shipped. The README describes it as an open source digital adoption platform and user on-boarding service, and it lists React, Ember, Angular, Vue.js, ES Modules and plain JavaScript as supported integration paths. The primary language of the repository is JavaScript, and the monorepo publishes the core as the shepherd.js package.

Who it is for is narrower than the tagline suggests. This is a library, not a hosted onboarding product. You write the tour definition, you decide when it starts, and you own the storage of whether a user has already seen it. The README points at a separate commercial offering, described as white glove services, for teams that want a custom tour built for them, and at a pricing page for the licence. So the audience splits: developers who want to script tours themselves, and companies that would rather pay for the work and the licence.

How a Shepherd tour is structured: steps, targets and a modal overlay

The architecture visible in the repository is a monorepo. The core library lives under shepherd.js/, framework wrappers live under packages/ (the README links a React wrapper at packages/react and points to separate repositories for Angular, Vue and Ember), documentation source sits in docs-src/, and the marketing site in landing/. The workspace is wired with pnpm-workspace.yaml and a single root package.json, so a change to the core is consumed by the wrappers through the workspace rather than through a published version.

Conceptually, a tour is a collection of steps, and each step is bound to a target element in your DOM. The library positions the step next to that target and dims the rest of the page so attention lands in one place. The README's phrasing is that Shepherd guides users through a custom tour or journey within your app or website, and that it is highly customizable with minimal styles. That last part is a design decision worth naming: the library ships with little visual styling, so you are expected to bring your own CSS. If you want a tour that looks finished out of the box, you will be writing that CSS.

The README does not document the internal positioning logic, the overlay implementation, or how steps behave when a target element is missing from the DOM. Those details live in the documentation site at docs.shepherdjs.dev, which the README links but does not reproduce.

Installing shepherd.js and running a first tour

The README does not print an install command, but the repository is published as an npm package: the README opens with an npm version badge for shepherd.js, and the root package.json declares shepherd.js as a workspace dependency. The package name is the one to expect, and the workspace references it as "shepherd.js": "workspace:*".

"shepherd.js": "workspace:*"

That line is the root package.json entry for the core package, and it is the only concrete reference to the package name inside the repository files. The README does not include a code sample for defining a tour, so there is no verified snippet to reproduce here. The place to get the installation instructions and a first working example is the documentation site the README links, docs.shepherdjs.dev, and the demo at shepherdjs.dev. Read those before writing tour code, because the README itself stops at describing what the library does rather than how to call it.

The AGPL-3.0 and commercial dual licence is the real adoption decision

The README states plainly that Shepherd.js is dual-licensed under AGPL-3.0 and a Commercial License, that it is free for open source and non-commercial use under AGPL-3.0, and that a commercial license is required for commercial products and revenue-generating companies. The root package.json lists the licence as AGPL-3.0, and a LICENSE.md sits at the top level alongside the pricing page linked from the README.

This is not a footnote. AGPL-3.0 is a copyleft licence with a network clause, and the project's own README treats commercial use as a paid tier. If you are adding a tour to a closed source SaaS product, the question is not whether the library is good but whether your company will buy the licence. That is a procurement conversation, not a technical one, and it should happen before anyone writes tour steps. For an open source project, an internal tool that is not distributed, or a non-commercial site, the AGPL-3.0 path is the one the README describes as free. I am not a lawyer and this is not legal advice: read LICENSE.md and shepherdjs.dev/pricing, and involve whoever handles licensing at your company.

Where Shepherd is the wrong tool

Shepherd is a client-side library, so it knows nothing about your users. It will not remember that someone finished the tour, will not segment who sees which tour, and will not report completion rates. Every one of those behaviours has to be built on top of it or bought elsewhere. If your requirement is a dashboard showing onboarding funnel drop-off, this library is one component of that system, not the system.

The second limitation is styling. The README calls the styles minimal, which means the visual result depends on CSS you write. Teams that expect a polished, opinionated onboarding widget will spend more time on styles than on tour logic.

Third, tours are bound to DOM targets. A step that points at an element which is not rendered, or which a redesign removes, has nothing to attach to. The README does not document a fallback for a missing target, so the behaviour in that case is something to verify against the documentation and in your own app before you ship a tour to production users. Single-page applications that render asynchronously are the environment where this matters most.

Alternatives and the difference in approach

The closest comparison is Intro.js, the other long-standing JavaScript library for step-by-step product tours. Both attach steps to DOM elements and both dim the surrounding page, so the day-to-day developer experience is similar. The difference that matters is licensing: Intro.js moved to a commercial model with a paid tier for commercial use, while Shepherd's README keeps an AGPL-3.0 option for open source and non-commercial use alongside its commercial licence. If your project is open source, that distinction decides the choice before any technical comparison does.

The other direction is a hosted digital adoption platform, a category the README itself uses to describe Shepherd. Hosted platforms typically take over the analytics and targeting that Shepherd leaves to you, in exchange for a script tag, a vendor relationship and a subscription. That is the right trade when onboarding is a product metric someone owns; it is the wrong trade when you want a tour defined in your own codebase and versioned with your releases.

Shepherd's own ecosystem is worth knowing about too. The README lists Rails, Drupal and Budibase integrations, and names LogSeq, SimplePlanner and Snapsure as applications using it. That tells you the library has been embedded in other people's products, not just demoed.

Maintenance, releases and the cost of staying current

The repository is not archived, and the last push was on 2026-09-21. The most recent releases shown are 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. Note what those version strings are: they are React wrapper releases, not core library releases, which fits the monorepo layout where the wrapper is versioned separately from shepherd.js.

The upgrade cost is structural rather than dramatic. The root package.json requires Node.js 22.12 or newer and pins pnpm 11.21.0 as the package manager, so anyone building from source needs both. The build script runs the core build first and then the remaining packages, and a prepare script builds shepherd.js on install. The release process is described as mostly automated, with details in RELEASE.md. For consumers, the practical cost is that the core and the wrappers version independently, so a wrapper upgrade and a core upgrade are two separate events to track. The README does not document rollback or downgrade procedures, and the CHANGELOG.md at the top level is where release history would be recorded.

Editorial conclusion

Shepherd fits teams building a guided tour inside a web app who can accept AGPL-3.0 or buy the commercial licence: open source projects, internal tools, and products whose source is already public. It is the wrong choice for a closed source commercial product whose team is not prepared to purchase a licence, because the README states that commercial products and revenue-generating companies require one. Before adopting, read LICENSE.md in full, confirm which wrappers your stack needs and how current each is, and verify that your bundler resolves the stylesheet that the tour elements depend on, since the README does not document styling or rollback behaviour.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. shipshapecode/shepherd on GitHub