- Routing Vue.js : guide complet Vue Router 4

Pourquoi Vue Router 4 ?

Vue Router est la bibliothèque officielle de routage de l'écosystème Vue. Là où Vue gère la couche vue, Vue Router gère la correspondance URL ↔ composant, l'historique de navigation, les paramètres dynamiques, les guards de sécurité, et le lazy loading. C'est la fondation de toute SPA (Single Page Application) Vue moderne.

La version 4, sortie pour Vue 3 et stabilisée depuis 2021, apporte plusieurs avancées majeures : intégration native avec la Composition API via useRouter() / useRoute(), support TypeScript complet, nouveau système d'historique (createWebHistory, createWebHashHistory, createMemoryHistory), scrollBehavior amélioré, et compatibilité avec <Suspense> pour les composants asynchrones. La syntaxe est plus déclarative et plus lisible qu'en v3.

Ce que cet article couvre

• L'installation et la configuration de base (créer le router, le brancher à l'app).
• Les trois modes d'historique et leurs cas d'usage en production.
• Les routes simples, nommées, imbriquées avec layouts partagés.
• La navigation programmatique avec useRouter() et useRoute().
• Les paramètres dynamiques, query strings, et le pattern props: true.
• Les navigation guards globaux, par route et par composant.
• Le lazy loading natif via les imports dynamiques.
• scrollBehavior, transitions, TypeScript, et les pièges classiques.

Pourquoi un routeur côté client plutôt qu'une navigation classique ?

Une SPA gère la navigation sans rechargement complet : seule la zone identifiée par <RouterView /> change, les composants persistants (header, sidebar) restent montés. Le bénéfice immédiat est la fluidité : pas de flash blanc entre les pages, pas de re-téléchargement du CSS/JS partagé, état préservé en mémoire (input non vidés, scroll d'un panneau conservé). Le coût : il faut un peu plus de configuration côté serveur (fallback vers index.html) et veiller au SEO pour le contenu indexable (SSR via Nuxt, ou pré-rendu via vite-ssg). Vue Router 4 prend en charge la complexité interne — votre code reste déclaratif.

Installation et configuration de base

La configuration de base d'une application Vue Router 4 tient en trois étapes : installer le package, créer le fichier router, et le brancher à l'application. Chaque étape est minimale individuellement mais leur combinaison définit toute la navigation de votre application. Voici la version commentée pas-à-pas.

Installer le package

# npm
npm install vue-router@4

# pnpm (recommandé sur les projets Vite)
pnpm add vue-router@4

# yarn
yarn add vue-router@4

Créer le router (src/router/index.ts)

// src/router/index.ts
import { createRouter, createWebHistory } from 'vue-router';
import Home from '@/views/Home.vue';

const router = createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),
  routes: [
    { path: '/',      name: 'home',    component: Home },
    { path: '/about', name: 'about',   component: () => import('@/views/About.vue') },
    // Catch-all 404 — toujours en dernier
    {
      path: '/:pathMatch(.*)*',
      name: 'not-found',
      component: () => import('@/views/NotFound.vue'),
    },
  ],
});

export default router;

Brancher le router à l'application

// src/main.ts
import { createApp } from 'vue';
import App from './App.vue';
import router from './router';

createApp(App).use(router).mount('#app');

Composants RouterLink et RouterView

<!-- App.vue -->
<script setup lang="ts">
import { RouterLink, RouterView } from 'vue-router';
</script>

<template>
  <header>
    <nav>
      <RouterLink :to="{ name: 'home' }">Accueil</RouterLink>
      <RouterLink :to="{ name: 'about' }">À propos</RouterLink>
    </nav>
  </header>

  <!-- Composant de la route courante rendu ici -->
  <main>
    <RouterView />
  </main>
</template>

Trois modes d'historique : web, hash, memory

Vue Router 4 propose trois modes d'historique, chacun adapté à un contexte précis. Le choix se fait à l'instanciation du router.

Le choix du mode d'historique se fait une fois pour toutes au démarrage de l'application — vous ne pouvez pas en changer dynamiquement. Pensez à l'environnement de déploiement avant de choisir : un site sur Vercel, Netlify ou Cloudfront supportera createWebHistory sans souci ; un site déposé tel quel sur S3 ou GitHub Pages exigera createWebHashHistory si vous n'ajoutez pas de règle de redirection.

Configuration serveur pour createWebHistory

Avec createWebHistory, le serveur doit renvoyer index.html pour toute URL non statique — sinon les rafraîchissements sur /users/42 renvoient un 404. Voici les configs typiques.

# Nginx
location / {
  try_files $uri $uri/ /index.html;
}

# Apache (.htaccess)
RewriteEngine On
RewriteBase /
RewriteRule ^index\.html$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.html [L]

# Vercel (vercel.json)
{ "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }] }

# Netlify (_redirects)
/*    /index.html   200

Définir des routes simples et nommées

Chaque route est un objet avec au minimum path et component. Toujours ajouter name : les noms simplifient les refactos (changer un chemin ne casse pas la navigation interne) et améliorent la lisibilité.

const routes: RouteRecordRaw[] = [
  {
    path: '/',
    name: 'home',
    component: () => import('@/views/Home.vue'),
  },
  {
    path: '/articles',
    name: 'articles',
    component: () => import('@/views/ArticleList.vue'),
    meta: { requiresAuth: false, title: 'Articles' },
  },
  {
    path: '/articles/:slug', // paramètre dynamique
    name: 'article-detail',
    component: () => import('@/views/ArticleDetail.vue'),
    props: true, // les params sont passés en props
    meta: { requiresAuth: true },
  },
];

Navigation par nom dans le template

<template>
  <!-- Utilisation par nom — résistant aux refactos -->
  <RouterLink :to="{ name: 'article-detail', params: { slug: article.slug } }">
    {{ article.title }}
  </RouterLink>

  <!-- Active class personnalisée -->
  <RouterLink
    :to="{ name: 'articles' }"
    active-class="is-active"
    exact-active-class="is-current"
  >
    Liste
  </RouterLink>
</template>

Routes imbriquées et layouts partagés

Les routes imbriquées permettent de partager un layout (sidebar, header, breadcrumb) entre plusieurs vues. Le composant parent contient un <RouterView /> où les composants enfants se rendent.

const routes: RouteRecordRaw[] = [
  {
    path: '/dashboard',
    component: () => import('@/layouts/DashboardLayout.vue'),
    meta: { requiresAuth: true },
    children: [
      // Route "index" — affichée à /dashboard exactement
      { path: '',        name: 'dashboard',  component: () => import('@/views/dashboard/Home.vue') },
      { path: 'stats',   name: 'stats',      component: () => import('@/views/dashboard/Stats.vue') },
      { path: 'orders',  name: 'orders',     component: () => import('@/views/dashboard/Orders.vue') },
      { path: 'orders/:id', name: 'order-detail',
        component: () => import('@/views/dashboard/OrderDetail.vue'), props: true },
    ],
  },
];

<!-- layouts/DashboardLayout.vue -->
<template>
  <div class="dashboard">
    <aside class="sidebar">
      <RouterLink :to="{ name: 'dashboard' }">Vue d'ensemble</RouterLink>
      <RouterLink :to="{ name: 'stats' }">Statistiques</RouterLink>
      <RouterLink :to="{ name: 'orders' }">Commandes</RouterLink>
    </aside>
    <main class="content">
      <RouterView /> <!-- chaque enfant s'affiche ici -->
    </main>
  </div>
</template>

Plusieurs RouterView nommés (named views)

Pour des layouts avec plusieurs zones (sidebar dynamique + main + droite), utilisez les named views. Chaque <RouterView name="..."/> reçoit son propre composant déclaré dans components.

const routes = [
  {
    path: '/',
    components: {
      default:  () => import('@/views/Main.vue'),
      sidebar:  () => import('@/views/Sidebar.vue'),
      header:   () => import('@/views/HeaderHome.vue'),
    },
  },
];

// Template :
// <RouterView />                  ← default
// <RouterView name="sidebar" />
// <RouterView name="header" />

Navigation programmatique avec useRouter

Avec la Composition API, useRouter() retourne l'instance du router pour naviguer par code (après un login, une action utilisateur, une réponse API). useRoute() retourne la route courante.

<script setup lang="ts">
import { useRouter, useRoute } from 'vue-router';
import { ref } from 'vue';
import { loginApi } from '@/api/auth';

const router = useRouter();
const route = useRoute();

const email = ref('');
const password = ref('');

async function handleLogin() {
  const result = await loginApi(email.value, password.value);
  if (!result.success) return;

  // Redirection vers la page demandée OU dashboard par défaut
  const redirect = (route.query.redirect as string) ?? '/dashboard';
  router.push(redirect);
}
</script>

Les méthodes de navigation

// Push — ajoute une entrée dans l'historique
router.push('/about');
router.push({ name: 'article-detail', params: { slug: 'hello' } });
router.push({ path: '/search', query: { q: 'vue', page: 2 } });

// Replace — remplace l'entrée courante (pas de retour possible)
router.replace({ name: 'login' });

// Go — déplacement relatif dans l'historique
router.go(-1);  // équivalent du bouton "précédent"
router.go(2);   // avance de 2 pages

// Résolution sans navigation — utile pour générer un href
const resolved = router.resolve({ name: 'article-detail', params: { slug: 'x' } });
console.log(resolved.href); // "/articles/x"

Attendre la fin de la navigation

router.push() renvoie une Promise. Vous pouvez l'await pour exécuter du code après que la nouvelle route soit montée (analytics précis, focus management, scroll personnalisé). Si un guard annule la navigation, la promise se résout avec un objet d'erreur typé — vous pouvez le détecter via isNavigationFailure pour ne pas confondre une redirection volontaire avec un échec réel.

import { isNavigationFailure, NavigationFailureType } from 'vue-router';

const failure = await router.push({ name: 'protected' });
if (isNavigationFailure(failure, NavigationFailureType.aborted)) {
  console.log('Navigation annulée par un guard');
}

Paramètres, query strings et props

Lecture des params et query avec useRoute

<script setup lang="ts">
import { useRoute } from 'vue-router';
import { computed, watch } from 'vue';

const route = useRoute();

// Paramètre dynamique :slug depuis path='/articles/:slug'
const slug = computed(() => route.params.slug as string);

// Query string ?page=2&sort=date
const page  = computed(() => Number(route.query.page) || 1);
const sort  = computed(() => (route.query.sort as string) ?? 'date');

// Réagir aux changements de slug (navigation entre articles)
watch(slug, async (newSlug) => {
  await loadArticle(newSlug);
});
</script>

Pattern recommandé : props: true

Plutôt que de lire route.params.slug dans le composant, déclarez props: true sur la route et recevez le paramètre comme une prop normale. Le composant devient indépendant de Vue Router, donc plus simple à tester.

// router/index.ts
{
  path: '/articles/:slug',
  name: 'article-detail',
  component: () => import('@/views/ArticleDetail.vue'),
  props: true, // params transformés en props
}

// Variante fonction — pour combiner params + query
{
  path: '/search',
  component: SearchResults,
  props: (route) => ({
    q: route.query.q ?? '',
    page: Number(route.query.page) || 1,
  }),
}

<!-- views/ArticleDetail.vue -->
<script setup lang="ts">
defineProps<{ slug: string }>();
// On lit slug directement, plus besoin de useRoute()
</script>

<template>
  <article>Slug : {{ slug }}</article>
</template>

Navigation Guards et protection des routes

Les navigation guards interceptent les changements de route avant qu'ils n'aboutissent. Trois niveaux selon la granularité voulue.

1. Guard global — beforeEach (auth typique)

// src/router/index.ts
import { useAuthStore } from '@/stores/auth';

router.beforeEach((to, from) => {
  const auth = useAuthStore();

  if (to.meta.requiresAuth && !auth.isAuthenticated) {
    // Redirection vers login en mémorisant la destination
    return {
      name: 'login',
      query: { redirect: to.fullPath },
    };
  }

  // Vérifier les rôles
  if (to.meta.roles && !to.meta.roles.includes(auth.user.role)) {
    return { name: 'forbidden' };
  }

  // Pas de return = navigation autorisée
});

router.afterEach((to) => {
  // Pas un guard, mais un hook après navigation — idéal pour les analytics
  document.title = (to.meta.title as string) ?? 'Mon App';
  analytics.pageview(to.fullPath);
});

2. Guard par route — beforeEnter

const routes = [
  {
    path: '/admin',
    component: AdminPanel,
    beforeEnter: (to, from) => {
      const auth = useAuthStore();
      if (!auth.isAdmin) return { name: 'forbidden' };
    },
  },
];

3. Guards par composant (Composition API)

<script setup lang="ts">
import { onBeforeRouteLeave, onBeforeRouteUpdate } from 'vue-router';
import { ref } from 'vue';

const formIsDirty = ref(false);

// Empêcher la sortie d'une page avec un formulaire non sauvegardé
onBeforeRouteLeave((to, from) => {
  if (!formIsDirty.value) return true;
  return confirm('Quitter sans sauvegarder ?');
});

// Recharger les données quand le slug change sans démonter le composant
onBeforeRouteUpdate(async (to, from) => {
  if (to.params.slug !== from.params.slug) {
    await loadArticle(to.params.slug as string);
  }
});
</script>

Ordre d'exécution des guards

Les guards s'exécutent dans un ordre déterministe et important à connaître pour débuguer : (1) beforeRouteLeave sur les composants désactivés, (2) beforeEach global, (3) beforeRouteUpdate sur les composants réutilisés, (4) beforeEnter sur la route ciblée, (5) beforeRouteEnter sur les nouveaux composants, (6) beforeResolve global, et enfin (7) afterEach global (qui n'est plus un guard mais un hook). Cette chaîne complète permet d'intercepter tous les cas — du retour navigateur au refresh d'une route avec params différents.

Lazy loading et code splitting

Le lazy loading est natif et tient en une ligne : remplacez component: SomeComponent par component: () => import('@/views/SomeComponent.vue'). Vite ou Webpack génèrent automatiquement un chunk JavaScript séparé téléchargé à la demande.

const routes = [
  // Eager — chargé dans le bundle initial (page d'accueil)
  { path: '/', component: Home },

  // Lazy — chunk dédié, téléchargé à la 1ère visite
  { path: '/dashboard', component: () => import('@/views/Dashboard.vue') },

  // Lazy avec nom de chunk explicite (utile pour le debug)
  {
    path: '/admin',
    component: () => import(/* webpackChunkName: "admin" */ '@/views/Admin.vue'),
  },
];

Gains mesurables du lazy loading

Sur un projet Vue 3 réel comportant 25 vues, le passage à 100 % lazy fait typiquement chuter le bundle initial de 800 ko à 180 ko gzipped, et le LCP mobile de 4,2 s à 1,8 s sur une connexion 4G. La règle simple : si une vue n'est pas indispensable pour la page d'entrée, lazy-loadez-la. Les pages d'admin, les écrans de configuration, les paniers, les détails d'article, les paramètres utilisateur — tous candidats parfaits.

Suspense pour gérer le chargement

<!-- App.vue -->
<template>
  <RouterView v-slot="{ Component }">
    <Suspense>
      <component :is="Component" />

      <template #fallback>
        <LoadingSpinner />
      </template>
    </Suspense>
  </RouterView>
</template>

Prefetch automatique au survol des liens

Avec Vite, vous pouvez précharger un chunk au survol d'un RouterLink grâce à la directive v-prefetch ou à un wrapper custom. C'est une optimisation transparente : l'utilisateur ne perçoit aucune latence au clic puisque le code est déjà téléchargé.

// directives/prefetch.ts — directive Vue custom
import type { Directive } from 'vue';

export const vPrefetch: Directive<HTMLAnchorElement, () => Promise<unknown>> = {
  mounted(el, binding) {
    let prefetched = false;
    el.addEventListener('mouseenter', () => {
      if (prefetched) return;
      prefetched = true;
      binding.value(); // déclenche l'import dynamique
    });
  },
};

// Usage : <RouterLink :to="..." v-prefetch="() => import('@/views/Admin.vue')">

scrollBehavior et transitions

Gérer le scroll comme dans un site classique

// router/index.ts
const router = createRouter({
  history: createWebHistory(),
  scrollBehavior(to, from, savedPosition) {
    // Bouton précédent / suivant — restaurer la position
    if (savedPosition) return savedPosition;

    // Ancre dans l'URL — scroll vers l'élément
    if (to.hash) {
      return { el: to.hash, behavior: 'smooth', top: 80 };
    }

    // Nouvelle page — remonter en haut
    return { top: 0, behavior: 'smooth' };
  },
  routes,
});

Transitions entre routes

<!-- App.vue -->
<template>
  <RouterView v-slot="{ Component, route }">
    <Transition :name="(route.meta.transition as string) ?? 'fade'" mode="out-in">
      <component :is="Component" :key="route.path" />
    </Transition>
  </RouterView>
</template>

<style>
.fade-enter-active, .fade-leave-active { transition: opacity .2s ease; }
.fade-enter-from, .fade-leave-to { opacity: 0; }

.slide-enter-active, .slide-leave-active { transition: transform .3s ease; }
.slide-enter-from { transform: translateX(100%); }
.slide-leave-to { transform: translateX(-100%); }
</style>

Le :key="route.path" est essentiel — sans lui, Vue ne sait pas qu'il s'agit d'un changement de composant à animer. Avec mode="out-in", l'ancien composant disparaît avant que le nouveau n'apparaisse, ce qui évite les chevauchements visuels.

TypeScript : typer les routes nommées

Vue Router 4 supporte le typage strict des noms de routes via la déclaration RouteNamedMap. Vous obtenez l'autocomplete sur les noms et la vérification des params requis.

// types/router.d.ts
import 'vue-router';

declare module 'vue-router' {
  interface RouteMeta {
    requiresAuth?: boolean;
    roles?: string[];
    title?: string;
    transition?: 'fade' | 'slide';
  }
}

// router/index.ts — version typée
import { createRouter, createWebHistory, type RouteRecordRaw } from 'vue-router';

const routes: RouteRecordRaw[] = [
  {
    path: '/articles/:slug',
    name: 'article-detail',
    component: () => import('@/views/ArticleDetail.vue'),
    meta: { requiresAuth: true, title: 'Article' }, // typé via RouteMeta
  },
];

Pour aller plus loin, le plugin officiel unplugin-vue-router génère automatiquement le type union de tous les noms de routes à partir de votre dossier pages/ (à la Next.js). L'autocomplete sur router.push({ name: '...' }) propose alors uniquement les noms valides.

Convention de nommage et organisation

Sur les gros projets, regrouper les routes par feature plutôt que par type est plus maintenable. Créez un dossier src/router/ avec un fichier par domaine (admin.routes.ts, public.routes.ts, account.routes.ts) et concaténez-les dans index.ts. Chaque fichier exporte un tableau RouteRecordRaw[] typé. Le résultat : un fichier de 30 lignes au lieu d'un monstre de 500 lignes, et chaque feature owner sait où regarder pour ses routes.

Pièges, performance et bonnes pratiques

Tester un router en isolation

Pour tester un composant qui utilise useRoute ou useRouter, créez un router de test avec createRouter + createMemoryHistory puis injectez-le dans le harness Vitest via app.use(router). Les guards peuvent être testés en isolation en appelant directement leur fonction avec un objet route mocké. Les méthodes asynchrones (router.push) sont awaitables — utilisez await router.push(...) dans vos tests pour attendre la résolution complète avant l'assertion.

// router.test.ts
import { createRouter, createMemoryHistory } from 'vue-router';
import { describe, it, expect } from 'vitest';
import { routes } from '@/router/routes';

describe('authGuard', () => {
  it('redirige vers login si non authentifié', async () => {
    const router = createRouter({ history: createMemoryHistory(), routes });
    await router.push('/dashboard');
    expect(router.currentRoute.value.name).toBe('login');
  });
});

Métriques à surveiller

• Taille du chunk principal < 200 ko gzipped pour un bon LCP mobile.
• Time to Interactive < 3 s sur connexion 4G — chunks lazy + prefetch.
• Couverture des guards — au moins un test unitaire par guard d'auth.
• Routes 404 en analytics — détecter les liens cassés via la route catch-all.

Mini-projet appliqué — app Vue 3 multi-routes typées avec auth

Cas concret : un back-office Vue 3 avec 9 routes (publiques + protégées), guards d'authentification, lazy loading par feature, et typage TypeScript strict des params. C'est le squelette des SaaS Vue 3 production qu'on retrouve dans 80 % des projets.

1. Configuration des routes — structure modulaire

// router/index.ts
import { createRouter, createWebHistory, type RouteRecordRaw } from 'vue-router';
import { useAuthStore } from '@/stores/auth';

const routes: RouteRecordRaw[] = [
    // Routes publiques — lazy loaded
    {
        path: '/',
        name: 'home',
        component: () => import('@/pages/HomePage.vue'),
        meta: { title: 'Accueil' },
    },
    {
        path: '/login',
        name: 'login',
        component: () => import('@/pages/LoginPage.vue'),
        meta: { title: 'Connexion', guestOnly: true },
    },

    // Section protégée — layout commun
    {
        path: '/dashboard',
        component: () => import('@/layouts/DashboardLayout.vue'),
        meta: { requiresAuth: true },
        children: [
            {
                path: '',
                name: 'dashboard',
                component: () => import('@/pages/dashboard/HomePage.vue'),
            },
            {
                path: 'users',
                name: 'users',
                component: () => import('@/pages/dashboard/UsersPage.vue'),
                meta: { requiresRole: 'admin' },
            },
            {
                path: 'users/:id',
                name: 'user-detail',
                component: () => import('@/pages/dashboard/UserDetailPage.vue'),
                props: true,
            },
            {
                path: 'orders',
                name: 'orders',
                component: () => import('@/pages/dashboard/OrdersPage.vue'),
            },
            {
                path: 'settings',
                name: 'settings',
                component: () => import('@/pages/dashboard/SettingsPage.vue'),
            },
        ],
    },

    // Catch-all 404
    {
        path: '/:pathMatch(.*)*',
        name: 'not-found',
        component: () => import('@/pages/NotFoundPage.vue'),
    },
];

export const router = createRouter({
    history: createWebHistory(),
    routes,
    scrollBehavior(to, from, savedPosition) {
        if (savedPosition) return savedPosition;
        if (to.hash) return { el: to.hash, behavior: 'smooth' };
        return { top: 0 };
    },
});

2. Guard global d'authentification + role

Pour le pattern auth complet (cookies httpOnly + refresh), voir le mini-projet auth tokens 2026.

// router/index.ts (suite)
router.beforeEach(async (to, _from, next) => {
    const auth = useAuthStore();

    // Hydrater l'auth depuis le cookie au premier navigation
    if (!auth.checked) await auth.fetchCurrentUser();

    // Si la route exige une auth et que l'utilisateur n'est pas connecté
    if (to.meta.requiresAuth && !auth.isAuthenticated) {
        return next({
            name: 'login',
            query: { returnTo: to.fullPath },
        });
    }

    // Si la route est "guestOnly" (login, signup) et user déjà connecté
    if (to.meta.guestOnly && auth.isAuthenticated) {
        return next({ name: 'dashboard' });
    }

    // Vérification du rôle si demandé
    if (to.meta.requiresRole && auth.user?.role !== to.meta.requiresRole) {
        return next({ name: 'not-found' });
    }

    next();
});

// Mise à jour du titre de page après chaque navigation
router.afterEach((to) => {
    document.title = to.meta.title ? `${to.meta.title} | MyApp` : 'MyApp';
});

3. Typage strict des RouteMeta + params

Pour les patterns TypeScript Vue 3 avancés, voir le guide Vue 3 + TypeScript.

// types/router.d.ts
import 'vue-router';

declare module 'vue-router' {
    interface RouteMeta {
        title?: string;
        requiresAuth?: boolean;
        requiresRole?: 'admin' | 'member' | 'guest';
        guestOnly?: boolean;
    }
}

// Helper de routes type-safe — équivalent React Router routes
export const routes = {
    home: () => ({ name: 'home' as const }),
    login: (returnTo?: string) => ({
        name: 'login' as const,
        query: returnTo ? { returnTo } : undefined,
    }),
    dashboard: () => ({ name: 'dashboard' as const }),
    users: () => ({ name: 'users' as const }),
    userDetail: (id: string) => ({
        name: 'user-detail' as const,
        params: { id },
    }),
    orders: () => ({ name: 'orders' as const }),
    settings: () => ({ name: 'settings' as const }),
} as const;

4. Composant — navigation typée et useRoute typé

<!-- pages/dashboard/UserDetailPage.vue -->
<script setup lang="ts">
import { useRoute, useRouter } from 'vue-router';
import { routes } from '@/router';

// Props auto-injectées via props: true
const props = defineProps<{ id: string }>();

const route = useRoute();
const router = useRouter();

async function deleteUser() {
    await fetch(`/api/users/${props.id}`, { method: 'DELETE' });
    // Navigation typée — autocomplete sur les routes existantes
    router.push(routes.users());
}

function navigateTo(targetId: string) {
    router.push(routes.userDetail(targetId));
}
</script>

<template>
    <article>
        <h1>Détail utilisateur {{ id }}</h1>
        <router-link :to="routes.users()">← Retour à la liste</router-link>
        <button @click="deleteUser">Supprimer</button>
    </article>
</template>

5. Guard par composant — formulaire non sauvegardé

<!-- pages/dashboard/SettingsPage.vue -->
<script setup lang="ts">
import { ref } from 'vue';
import { onBeforeRouteLeave } from 'vue-router';

const hasUnsavedChanges = ref(false);

// Avertir avant de quitter la page si non sauvegardé
onBeforeRouteLeave(async () => {
    if (!hasUnsavedChanges.value) return true;

    const confirmed = window.confirm(
        'Vous avez des modifications non sauvegardées. Voulez-vous vraiment quitter ?'
    );
    return confirmed;
});
</script>

6. Lazy loading par feature avec préfetch

// router/lazy.ts — pattern de préchargement au survol
import type { Component } from 'vue';

const lazyComponents = new Map<string, Promise<Component>>();

export function lazyLoad(importFn: () => Promise<any>, key: string) {
    return () => {
        if (!lazyComponents.has(key)) {
            lazyComponents.set(key, importFn());
        }
        return lazyComponents.get(key)!;
    };
}

// Précharger au survol du lien
<router-link
    :to="routes.users()"
    @mouseenter="lazyComponents.get('users') || import('@/pages/dashboard/UsersPage.vue')"
>
    Utilisateurs
</router-link>

Pour pousser le pattern à un meta-framework complet (file-based routing, SSR, auto-imports), voir le mini-projet blog Nuxt 3 fullstack. Pour la version React équivalente, voir le mini-projet dashboard React Router qui couvre le même pattern côté React avec data router + loaders.

Conclusion

Vue Router 4 est l'aboutissement de huit ans d'itérations sur le routage Vue. La version actuelle combine une API déclarative simple à apprendre (les routes sont un tableau d'objets) avec des fonctionnalités avancées : guards multi-niveaux, lazy loading natif, support TypeScript complet, scroll behavior configurable, transitions, et compatibilité <Suspense>. La courbe d'apprentissage est douce — vous pouvez démarrer en cinq minutes — mais le plafond est haut, à la hauteur de ce que demande une application en production.

En 2026, la combinaison gagnante pour une SPA Vue 3 est : <script setup> + Composition API + Vue Router 4 + Pinia + Vite. Cette stack offre un DX (developer experience) excellent, des temps de build courts, et une intégration TypeScript de premier ordre. Si vous démarrez aujourd'hui, partez directement sur cette base ; si vous maintenez du code en Vue 2 + Vue Router 3, planifiez la migration — la version 2 est en fin de vie et la 3 reçoit déjà moins d'attention en sécurité.

Pour aller plus loin, deux pistes à explorer dès que les bases sont solides : Nuxt 3, le meta-framework Vue qui ajoute SSR, routing basé sur les fichiers du dossier pages/, et data fetching intégré ; et unplugin-vue-router, qui apporte le même routing-par-fichiers sans nécessiter Nuxt. Ces deux outils s'appuient sur Vue Router 4 en interne — connaître les concepts vus dans cet article reste indispensable, mais l'écriture devient plus déclarative et l'autocomplete TypeScript est encore meilleure. C'est la direction prise par l'écosystème pour les nouveaux projets Vue 3 ambitieux.