@franck35/nuxt-tour

nuxt-tour

Layer Nuxt fournissant une surcouche à useTour de Nuxt UI. Gère un registre global du tour actif et expose un composant popover et un bouton de lancement réutilisables.

Prérequis

• Nuxt 4.x
• @nuxt/ui installé dans le projet consommateur

Installation

Via GitLab (dépôt privé)

Dans nuxt.config.ts :

extends: ['@franck35/nuxt-tour'],

Structure du layer

nuxt-tour/
├── nuxt.config.ts
├── app/
│   ├── components/
│   │   └── TourPopover.vue       # Conteneur global du popover
│   └── composables/
│       └── useTourRegistry.ts    # Registre global du tour actif

Intégration dans le layout

Ajoute <TourPopover /> une seule fois dans ton layout principal :

<!-- app/layouts/default.vue -->
<template>
  <div>
    <AppHeader />
    <slot />
        <TourPopover v-if="activeTour" :tour="activeTour" /> <!-- ← ici, une seule fois -->
  </div>
</template>

<script setup lang="ts">
const { activeTour } = useTourRegistry()
</script>

Créer un tour pour une page

Crée un composable useTour<NomDePage> dans ton projet qui définit les étapes et enregistre le tour :

// app/composables/useTourDashboard.ts
export function useTourDashboard() {
     const { createPageTour } = useTourRegistry()

    return createPageTour([
      {
        title: 'Bienvenue 👋',
        description: 'Voici votre tableau de bord.',
        target: '[data-tour="dashboard-header"]',
      },
      {
        title: 'Statistiques',
        description: 'Consultez vos métriques en temps réel.',
        target: '[data-tour="dashboard-stats"]',
      },
      {
        title: 'Actions rapides',
        description: 'Accédez aux raccourcis depuis ce menu.',
        target: '[data-tour="dashboard-actions"]',
      },
    ])
}

// app/composables/useTourSettings.ts
export function useTourSettings() {
   const { createPageTour } = useTourRegistry()

    return createPageTour([
      {
        title: 'Profil',
        description: 'Modifiez vos informations personnelles.',
        target: '[data-tour="settings-profile"]',
      },
      {
        title: 'Notifications',
        description: 'Configurez vos préférences de notifications.',
        target: '[data-tour="settings-notifs"]',
      },
    ])
}

Utilisation dans une page

<!-- app/pages/dashboard.vue -->
<script setup lang="ts">
const tour = useTourDashboard()
</script>

<template>
  <div>
    <div data-tour="dashboard-header">
      <h1>Tableau de bord</h1>
      <UButton
        v-if="tour"
        icon="ic:twotone-signpost"
        variant="outline"
        @click="tour.start()"
      >
        Démarrer la visite
      </UButton>
    </div>

    <div data-tour="dashboard-stats">
      <!-- ... -->
    </div>

    <div data-tour="dashboard-actions">
      <!-- ... -->
    </div>
  </div>
</template>

Composables exposés par le layer

useTourRegistry()

Registre global — une seule instance partagée dans toute l'app.

Composants exposés par le layer

<TourPopover />

Conteneur global à placer une seule fois dans le layout. Affiche automatiquement le popover du tour actif. Ne nécessite aucune prop.

Bonnes pratiques

• ✅ Place <TourPopover /> dans le layout, pas dans les pages
• ✅ Un seul useTour<Page> par page — onUnmounted nettoie automatiquement
• ✅ Utilise data-tour="..." sur les éléments cibles pour un ciblage sans couplage au CSS
• ❌ Ne pas appeler registerTour sans le onUnmounted correspondant