{"id":12574,"library":"vue-shepherd","title":"Vue Shepherd","description":"Vue Shepherd is a Vue wrapper library for Shepherd.js, a robust JavaScript library designed for guiding users through applications with interactive site tours. The package is currently at its stable version 6.0.0 and offers integration for both Vue's Composition API via `useShepherd` and Options API using `VueShepherdPlugin`. It differentiates itself by providing a native Vue experience for Shepherd.js, simplifying the process of adding step-by-step guides within Vue applications. The release cadence is moderate, often aligning with updates to the underlying Shepherd.js library and broader Vue ecosystem evolutions. A critical aspect for adopters is the licensing; starting from v5.0.1, the library transitioned to the AGPL-3.0 license, which necessitates a commercial license for commercial products and revenue-generating companies.","status":"active","version":"6.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/shipshapecode/vue-shepherd","tags":["javascript","vue","site tour","tour","shepherd","typescript"],"install":[{"cmd":"npm install vue-shepherd","lang":"bash","label":"npm"},{"cmd":"yarn add vue-shepherd","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-shepherd","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for Vue.js functionality; requires Vue 3.0.0 or higher.","package":"vue","optional":false},{"reason":"The core site tour library that vue-shepherd wraps and depends on at runtime.","package":"shepherd.js","optional":false}],"imports":[{"note":"The primary Composition API hook for creating and managing tours.","symbol":"useShepherd","correct":"import { useShepherd } from 'vue-shepherd'"},{"note":"Used for Options API integration by installing it as a Vue plugin via `app.use()`.","wrong":"import { VueShepherdPlugin } from 'vue-shepherd'","symbol":"VueShepherdPlugin","correct":"import VueShepherdPlugin from 'vue-shepherd'"},{"note":"Essential CSS styles for the tour UI must be imported separately from the main `shepherd.js` package.","symbol":"CSS Styles","correct":"import 'shepherd.js/dist/css/shepherd.css'"},{"note":"Specific import path for Server-Side Rendering (SSR) environments to ensure proper execution.","symbol":"VueShepherd (SSR)","correct":"import VueShepherd from 'vue-shepherd/dist/vue-shepherd.ssr.js'"}],"quickstart":{"code":"import { createApp, ref, onMounted } from 'vue';\nimport { useShepherd } from 'vue-shepherd';\nimport 'shepherd.js/dist/css/shepherd.css';\n\nconst App = {\n  setup() {\n    const el = ref(null);\n\n    const tour = useShepherd({\n      useModalOverlay: true,\n      defaultStepOptions: {\n        cancelIcon: {\n          enabled: true\n        }\n      }\n    });\n\n    onMounted(() => {\n      tour.addStep({\n        id: 'intro',\n        attachTo: { element: el.value, on: 'top' },\n        text: 'This is your first step! Click next to continue.',\n        buttons: [\n          { action: tour.cancel, text: 'Exit' },\n          { action: tour.next, text: 'Next' }\n        ]\n      });\n\n      tour.addStep({\n        id: 'second',\n        text: 'This step demonstrates a modal overlay and custom buttons.',\n        buttons: [\n          { action: tour.back, text: 'Back' },\n          { action: tour.complete, text: 'Done' }\n        ]\n      });\n\n      tour.start();\n    });\n\n    return { el };\n  },\n  template: `\n    <div id=\"app\">\n      <h1>Welcome to Vue Shepherd!</h1>\n      <div ref=\"el\" style=\"border: 1px solid blue; padding: 20px; margin-top: 50px;\">\n        Content for the tour step.\n      </div>\n    </div>\n  `\n};\n\ncreateApp(App).mount('#app');","lang":"typescript","description":"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."},"warnings":[{"fix":"Review your project's licensing requirements. For commercial use, consider purchasing a commercial license from shepherdjs.dev or explore alternative tour libraries.","message":"The license for vue-shepherd and its upstream library Shepherd.js changed from MIT to AGPL-3.0. Commercial projects now require a commercial license.","severity":"breaking","affected_versions":">=5.0.1"},{"fix":"Ensure 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.","message":"Version 2.0.0 introduced breaking changes by dropping support for Vue 2 and exclusively supporting Vue 3.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Always 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.","message":"Major version bumps in the underlying `shepherd.js` library (e.g., to v8 and v10) have historically introduced breaking changes that propagate to `vue-shepherd`.","severity":"breaking","affected_versions":">=0.2.0, >=0.3.0"},{"fix":"Upgrade 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`.","message":"Native 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.","severity":"gotcha","affected_versions":"<4.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Add `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.","cause":"The necessary CSS stylesheet for Shepherd.js, which `vue-shepherd` depends on for styling, has not been imported.","error":"Module not found: Error: Can't resolve 'shepherd.js/dist/css/shepherd.css'"},{"fix":"Ensure you have `import VueShepherdPlugin from 'vue-shepherd';` and `createApp(App).use(VueShepherdPlugin).mount('#app');` in your application's entry point.","cause":"When using the Options API, `VueShepherdPlugin` must be explicitly installed with `app.use()` before `$shepherd` becomes available on the component instance.","error":"TypeError: this.$shepherd is not a function"},{"fix":"Either 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).","cause":"Attempting to use `vue-shepherd` version 2.0.0 or higher in a Vue 2 application, which is no longer supported.","error":"Error: Vue Shepherd requires a Vue 3 environment. Detected Vue version is 2.x."},{"fix":"Change the import statement from `import { VueShepherdPlugin } from 'vue-shepherd'` to `import VueShepherdPlugin from 'vue-shepherd'`.","cause":"Attempting to use a named import for `VueShepherdPlugin` when it is exported as a default export for the Options API plugin.","error":"SyntaxError: Named export 'VueShepherdPlugin' not found (module 'vue-shepherd')"}],"ecosystem":"npm"}