Does Shepherd.js work with React 19?
Shepherd.js broke on React 19 the day it shipped and stayed broken for thirteen months. The react-shepherd wrapper depended on __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED.ReactCurrentDispatcher, a React internal that React 19 renamed. Hard crash: TypeError: Cannot read properties of undefined (reading 'ReactCurrentDispatcher').
Teams that upgraded between January 2025 and March 2026 had no working Shepherd tour until version 7.0.4 landed. Here's the full picture for anyone evaluating Shepherd.js on React 19 today.
npm install @tourkit/core @tourkit/reactShort answer
Shepherd.js technically works with React 19 as of react-shepherd 7.0.4, released March 11, 2026. But the fix was a peer dependency relaxation, not an architectural change. Shepherd's core is written in Svelte, and the React wrapper remains a thin layer around vanilla JavaScript. For React 19 projects, libraries built natively for React (Tour Kit at under 8KB gzipped with an MIT license, or React Joyride) avoid the wrapper indirection entirely.
The 13-month compatibility gap
Here's what happened, with dates from GitHub issue #3102:
| Date | Event |
|---|---|
| January 23, 2025 | Issue #3102 opened: React 19 crashes Shepherd with TypeError |
| February 7, 2025 | A developer who purchased Shepherd Pro reports it doesn't work with React 19 either |
| July 31, 2025 | "This library is also preventing us from migrating React 19" (@salimkanoun) |
| September 10, 2025 | Same developer migrates away to a different library |
| October 30, 2025 | Community criticizes the lack of maintainer response |
| January 28, 2026 | Maintainer's first public response: "Are we able to support 18 and 19 if we relax the peerDep?" |
| March 11, 2026 | v7.0.4 released with the fix (PR #3339) |
Thirteen months is a long time to block a React upgrade. React 19 went stable in December 2024, so this wasn't a niche early-adopter problem. Every team running Shepherd.js faced the same choice: stay on React 18, force-install with --force and hope nothing else broke, or rip out the library entirely.
Why this happened (and could happen again)
Shepherd.js is built in Svelte. The React integration is a wrapper, not a React-native implementation. That architecture means the library depends on React internals to bridge the gap between Svelte's rendering model and React's component lifecycle.
As one reviewer put it: developers "will have to leave JSX behind and work either with HTML strings or plain HTML elements" for advanced Shepherd features (Sandro Roth, Evaluating Tour Libraries). That's the DX cost of a wrapper approach.
The React 19 fix was reportedly just relaxing the peerDependencies constraint from "react": "^18.2.0" to accept React 19. That addresses the install error.
Whether the underlying internal dependency is fully resolved is harder to verify without auditing the source. React's internal APIs change between majors, so the same pattern could repeat with React 20.
Comparison: Shepherd.js vs React-native alternatives
| Feature | Shepherd.js 15.2.2 | Tour Kit | React Joyride |
|---|---|---|---|
| Core language | Svelte (vanilla JS wrapper) | TypeScript (React-native) | TypeScript (React-native) |
| React 19 support | Fixed March 2026 (13-month gap) | Day-one support | Supported |
| License | AGPL-3.0 (commercial license required) | MIT (core packages) | MIT |
| Weekly npm downloads | ~130K core / ~30K wrapper | New (pre-launch) | ~706K |
| Headless mode | No (opinionated styling) | Yes (headless-first) | Partial |
| Accessibility | Partial ARIA, no focus trap | WCAG 2.1 AA, focus trap | Basic ARIA |
| Positioning engine | Floating UI | Floating UI | Floating UI (via react-floater) |
| TypeScript | Yes | Strict mode | Yes |
Downloads as of April 2026 via npm trends.
The AGPL license factor
Shepherd.js uses AGPL-3.0 for its core package. Any company generating revenue needs a commercial license from Ship Shape. The react-shepherd wrapper carries an MIT license, but that doesn't help because AGPL obligations cascade through dependencies. One developer on GitHub issue #3102 wrote that they "just purchased the pro version" thinking it would resolve the React 19 crash. It didn't (at the time).
Both Intro.js and Shepherd.js use AGPL. If license matters to your team, the MIT-licensed options are React Joyride, Driver.js, Reactour, and Tour Kit.
When to choose Shepherd.js anyway
Shepherd.js has genuine strengths. Its SVG-based backdrop supports highlighting multiple elements simultaneously. With 170+ releases and 100+ contributors, it's a mature project with active maintenance. The vanilla JS core means it works outside React too. Running Vue, Svelte, or plain HTML alongside React? Shepherd gives you one library across all of them.
If your project is AGPL-compatible (open source) and you don't need headless rendering or strict accessibility compliance, Shepherd.js at version 15.2.2 does work with React 19 now.
Decision framework
React 19 with zero breakage risk: Choose a React-native library. Tour Kit and React Joyride don't depend on React internals, so major version upgrades won't crash your tours. Tour Kit doesn't have a visual builder and requires React developers, so factor that into your team's capabilities.
Commercial SaaS products: Factor in the AGPL license cost. Shepherd.js requires a paid commercial license for any revenue-generating use. MIT alternatives like Tour Kit don't.
Cross-framework projects: Shepherd.js is one of the few tour libraries that works outside React. Running multiple frontend frameworks? The wrapper tradeoff might be worth it.
Accessibility requirements: Shepherd's ARIA support is still incomplete, with issue #198 about missing ARIA attributes filed in 2018. Tour Kit ships with WCAG 2.1 AA compliance and focus trapping out of the box.
Headless rendering needs: Shepherd ships opinionated CSS. Tour Kit is headless-first, so you render steps with your own components and it works with shadcn/ui, Tailwind, or any design system without CSS overrides.
What we'd recommend
We built Tour Kit, so take this with appropriate skepticism. Every claim here is verifiable on npm, GitHub, and bundlephobia.
For React 19 projects, a React-native tour library removes an entire category of risk. Shepherd's 13-month gap wasn't a fluke. It was the predictable consequence of wrapping a non-React core. React Joyride (~706K weekly downloads) is the established choice. Tour Kit is newer and has a smaller community, but ships headless, accessible, and modular from the start.
Tour Kit's core is under 8KB gzipped with zero runtime dependencies. It doesn't touch React internals. When React 20 lands, your tours won't break.
Get started at https://usertourkit.com/ or install directly:
npm install @tourkit/core @tourkit/reactFrequently asked questions
Does Shepherd.js officially support React 19?
Shepherd.js added React 19 support in react-shepherd 7.0.4, released March 11, 2026. The fix was a peer dependency relaxation via PR #3339. Before that release, Shepherd.js crashed on React 19 with a TypeError from renamed React internals. The 13-month gap left many teams stranded on React 18.
What caused the Shepherd.js React 19 crash?
The react-shepherd wrapper accessed ReactCurrentDispatcher from React's internal module. React 19 renamed this internal, triggering a TypeError at runtime. Libraries that depend on undocumented React internals rather than public APIs carry this risk on every major version upgrade.
Is Shepherd.js free for commercial use?
Shepherd.js uses the AGPL-3.0 license. Any revenue-generating company needs a commercial license from Ship Shape. The MIT license on react-shepherd doesn't help because AGPL cascades through dependencies. Tour Kit, React Joyride, and Driver.js are all MIT and free for commercial use.
What are the best Shepherd.js alternatives for React 19?
For React 19, the top alternatives are React Joyride (706K weekly downloads, MIT), Tour Kit (headless-first, under 8KB gzipped, MIT, WCAG 2.1 AA), and Driver.js (lightweight, MIT). All three are React-native and didn't need patches for React 19.
Will Shepherd.js break again with future React versions?
The risk exists because Shepherd.js is built in Svelte with a React wrapper layer, not as a native React library. Libraries that depend on React internals or bridge between rendering models are more likely to break on major React upgrades. React-native libraries like Tour Kit and React Joyride use only React's public APIs, which reduces this risk.
Related articles
What are the best Appcues alternatives for developers?
Compare 7 Appcues alternatives built for developers. See bundle sizes, React 19 support, pricing, and code examples to pick the right onboarding tool.
Read article
What is the best open-source onboarding framework? (2026)
Compare open-source onboarding frameworks by bundle size, React 19 support, accessibility, and full-stack coverage. Honest recommendations with data.
Read article
What is the best product tour library for SSR (server-side rendering)?
Compare product tour libraries for SSR frameworks like Next.js, Remix, and Nuxt. See which handle server rendering, hydration, and React Server Components.
Read article
What is the best shadcn/ui compatible tour library?
Compare 7 tour libraries for shadcn/ui compatibility. See bundle sizes, headless support, and Tailwind integration to pick the right fit.
Read article