Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
useShepherd
✓ import { useShepherd } from 'vue-shepherd'
The primary Composition API hook for creating and managing tours.
VueShepherdPlugin
✓ import VueShepherdPlugin from 'vue-shepherd'
✗ import { VueShepherdPlugin } from 'vue-shepherd'
Used for Options API integration by installing it as a Vue plugin via `app.use()`.
CSS Styles
✓ import 'shepherd.js/dist/css/shepherd.css'
Essential CSS styles for the tour UI must be imported separately from the main `shepherd.js` package.
VueShepherd (SSR)
✓ import VueShepherd from 'vue-shepherd/dist/vue-shepherd.ssr.js'
Specific import path for Server-Side Rendering (SSR) environments to ensure proper execution.
Demonstrates how to set up a basic site tour using the Composition API with `useShepherd`, attach a step to an element, and start the tour, including the necessary CSS import.
import { createApp, ref, onMounted } from 'vue';
import { useShepherd } from 'vue-shepherd';
import 'shepherd.js/dist/css/shepherd.css';
const App = {
setup() {
const el = ref(null);
const tour = useShepherd({
useModalOverlay: true,
defaultStepOptions: {
cancelIcon: {
enabled: true
}
}
});
onMounted(() => {
tour.addStep({
id: 'intro',
attachTo: { element: el.value, on: 'top' },
text: 'This is your first step! Click next to continue.',
buttons: [
{ action: tour.cancel, text: 'Exit' },
{ action: tour.next, text: 'Next' }
]
});
tour.addStep({
id: 'second',
text: 'This step demonstrates a modal overlay and custom buttons.',
buttons: [
{ action: tour.back, text: 'Back' },
{ action: tour.complete, text: 'Done' }
]
});
tour.start();
});
return { el };
},
template: `
<div id="app">
<h1>Welcome to Vue Shepherd!</h1>
<div ref="el" style="border: 1px solid blue; padding: 20px; margin-top: 50px;">
Content for the tour step.
</div>
</div>
`
};
createApp(App).mount('#app');
Debug
Known issues
breakingThe license for vue-shepherd and its upstream library Shepherd.js changed from MIT to AGPL-3.0. Commercial projects now require a commercial license.fixReview your project's licensing requirements. For commercial use, consider purchasing a commercial license from shepherdjs.dev or explore alternative tour libraries.
affects: >=5.0.1
breakingVersion 2.0.0 introduced breaking changes by dropping support for Vue 2 and exclusively supporting Vue 3.fixEnsure your project is running Vue 3.x. If you are on Vue 2.x, use `vue-shepherd` versions prior to 2.0.0 or migrate your application to Vue 3.
affects: >=2.0.0
breakingMajor version bumps in the underlying `shepherd.js` library (e.g., to v8 and v10) have historically introduced breaking changes that propagate to `vue-shepherd`.fixAlways consult the release notes for `shepherd.js` when upgrading `vue-shepherd` to understand potential API changes, especially when there are major version increments in its dependencies.
affects: >=0.2.0, >=0.3.0
gotchaNative TypeScript declarations were added in v4.1.0. Older versions might have incomplete or incorrect type definitions, leading to poor developer experience or type errors in TypeScript projects.fixUpgrade to `vue-shepherd` v4.1.0 or newer for comprehensive and accurate TypeScript declarations. If using older versions, you may need to declare types manually or rely on `@ts-ignore`.
affects: <4.1.0
Errors
Common errors & fixes
Module not found: Error: Can't resolve 'shepherd.js/dist/css/shepherd.css'
The necessary CSS stylesheet for Shepherd.js, which `vue-shepherd` depends on for styling, has not been imported.
fixAdd `import 'shepherd.js/dist/css/shepherd.css'` to your main application entry file (e.g., `main.js` or `main.ts`) or the component where you initialize the tour.
TypeError: this.$shepherd is not a function
When using the Options API, `VueShepherdPlugin` must be explicitly installed with `app.use()` before `$shepherd` becomes available on the component instance.
fixEnsure you have `import VueShepherdPlugin from 'vue-shepherd';` and `createApp(App).use(VueShepherdPlugin).mount('#app');` in your application's entry point. Error: Vue Shepherd requires a Vue 3 environment. Detected Vue version is 2.x.
Attempting to use `vue-shepherd` version 2.0.0 or higher in a Vue 2 application, which is no longer supported.
fixEither upgrade your application to Vue 3.x or downgrade `vue-shepherd` to a version compatible with Vue 2.x (e.g., v1.x or earlier).
SyntaxError: Named export 'VueShepherdPlugin' not found (module 'vue-shepherd')
Attempting to use a named import for `VueShepherdPlugin` when it is exported as a default export for the Options API plugin.
fixChange the import statement from `import { VueShepherdPlugin } from 'vue-shepherd'` to `import VueShepherdPlugin from 'vue-shepherd'`. Audit
Dependencies
vuerequiredPeer dependency for Vue.js functionality; requires Vue 3.0.0 or higher.
shepherd.jsrequiredThe core site tour library that vue-shepherd wraps and depends on at runtime.