Why Nuxt Tour?

Nuxt Tour makes product tours feel like part of Nuxt and Vue. An application defines a typed tour, marks semantic targets, renders one host, and controls the journey from one composable. The library owns route changes, late targets, positioning, cleanup, focus, and failure diagnostics. Nearby targets share a continuous moving spotlight. Customize actions and progress with Vue slots while retaining the default accessible card.

Nuxt Tour is not an analytics product, visual editor, checklist system, or thin wrapper around another tour library.

Quick start

Install the package and add the module:

pnpm add @lupinum/nuxt-tour

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@lupinum/nuxt-tour'],
})

Use a coding agent

A coding agent is a development tool that can inspect and change your project. After installation, copy this prompt into your coding agent:

Add Nuxt Tour to this Nuxt application and build one accessible product tour.
Read the project's existing instructions first. Resolve
@lupinum/nuxt-tour/agent-docs from this application's directory and read its
starting pages. Use the installed version's examples and public types. Preserve
existing routes, interaction behavior, conventions, and AGENTS.md instructions.
Add or update one short Nuxt Tour pointer in AGENTS.md if the project allows it;
do not duplicate the documentation. If the file is absent, create only that
pointer. Report missing guidance. Verify start, step navigation, finish, Escape,
focus return, and a narrow screen. Use semantic target IDs instead of selectors.

If the installed package has no agent-docs export, read its packaged README and types. Use documentation from the matching source tag when more detail is needed. Installing or updating the package does not edit project instructions. The pointer resolves the installed package, so upgrades and rollbacks select the matching documentation without copying it into your application.

// app/tours/onboarding.ts
export default defineTour({
  id: 'onboarding',
  steps: [
    {
      id: 'welcome',
      title: 'Welcome',
      content: 'Let’s take a quick look around.',
    },
    {
      id: 'create-project',
      target: 'create-project',
      title: 'Create a project',
      content: 'Everything starts here.',
      placement: 'bottom-start',
    },
  ],
})

<script setup lang="ts">
const onboarding = useNuxtTour('onboarding')
</script>

<template>
  <button v-tour-target="'create-project'">
    Create project
  </button>

  <button @click="onboarding.start()">
    Show me around
  </button>

  <TourHost />
</template>

Nuxt discovers definitions from each layer's app/tours, auto-imports the composables, and generates literal tour, step, and semantic target ID types. Add one <TourHost /> near the root of the application.

For a complete plain Vue setup, import the runtime from @lupinum/nuxt-tour/vue and install createTourPlugin({ tours: [...] }). Import @lupinum/nuxt-tour/style.css for the default theme or structure.css for layout rules only. The default theme follows the system color scheme and recognizes .light, .dark, and matching data-theme values. Override its --tour-* custom properties from application CSS when the card should match your product more closely.

Read the documentation for targets, route-aware steps, interaction modes, events, and errors.

Requirements

• Node.js 22.19 or later, Node.js 24.11 or later, or Node.js 26.
• Nuxt 4 for the Nuxt module.
• Vue 3.5 or later for the Vue runtime.
• pnpm 11 for repository development.

Development

pnpm install
pnpm verify

Use pnpm dev for the Nuxt playground. Read CONTRIBUTING.md before you open a pull request. Maintainers use MAINTAINING.md.

Support and security

Ask questions in the Lupinum OSS Discord. Report vulnerabilities through GitHub private vulnerability reporting.

License

MIT © Lupinum OG.