Vue Shepherd

Common errors

• Module not found: Error: Can't resolve 'shepherd.js/dist/css/shepherd.css'

  cause The necessary CSS stylesheet for Shepherd.js, which `vue-shepherd` depends on for styling, has not been imported.
  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.

• TypeError: this.$shepherd is not a function

  cause When using the Options API, `VueShepherdPlugin` must be explicitly installed with `app.use()` before `$shepherd` becomes available on the component instance.
  fix Ensure 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.

  cause Attempting to use `vue-shepherd` version 2.0.0 or higher in a Vue 2 application, which is no longer supported.
  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).

• SyntaxError: Named export 'VueShepherdPlugin' not found (module 'vue-shepherd')

  cause Attempting to use a named import for `VueShepherdPlugin` when it is exported as a default export for the Options API plugin.
  fix Change the import statement from `import { VueShepherdPlugin } from 'vue-shepherd'` to `import VueShepherdPlugin from 'vue-shepherd'`.

Warnings

• breaking 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.
  Fix: Review your project's licensing requirements. For commercial use, consider purchasing a commercial license from shepherdjs.dev or explore alternative tour libraries.
• breaking Version 2.0.0 introduced breaking changes by dropping support for Vue 2 and exclusively supporting Vue 3.
  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.
• breaking 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`.
  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.
• gotcha 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.
  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`.

Install

• npm install vue-shepherd npm
• yarn add vue-shepherd yarn
• pnpm add vue-shepherd pnpm

Imports

• useShepherd

  import { useShepherd } from 'vue-shepherd'

  The primary Composition API hook for creating and managing tours.
• VueShepherdPlugin
  wrong:

  import { VueShepherdPlugin } from 'vue-shepherd'

  correct:

  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.

Quickstart

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');