Routing basado en ficheros con Unplugin Vue Router en Vue

Unplugin Vue Router es un plugin para Vue.js que permite generar automáticamente el enrutamiento basado en la estructura de archivos (file-based routing).

El routing basado en ficheros es un patrón que automatiza la generación de rutas a partir de la estructura de directorios de tu proyecto.

Es decir, que la estructura de carpetas y archivos refleja directamente la navegación de tu aplicación. Esto elimina la necesidad de mantener archivos de configuración de rutas manualmente.

Instalación y configuración básica

Para instalar Unplugin Vue Router en nuestro proyecto (que ya tenga instalado Vue Router) hacemos lo siguiente.

npm install unplugin-vue-router --save-dev  

Ahora para configurarlo

import { defineConfig } from 'vite'  
import Vue from '@vitejs/plugin-vue'
import VueRouter from 'unplugin-vue-router/vite'

export default defineConfig({
  plugins: [
    VueRouter({
      routesFolder: 'src/pages', // Carpeta de rutas
    }),
    Vue(), // ¡Importante: Vue() debe ir después!
  ],
})

import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router/auto' // Auto-importa las rutas

const router = createRouter({
  history: createWebHistory(),
  // ¡Las rutas se generan automáticamente!
})

const app = createApp(App)
app.use(router)
app.mount('#app')

Estructura de ficheros básica

Las rutas se generan automáticamente siguiendo convenciones sencillas. Por ejemplo,

src/  
└── pages/  
    ├── index.vue      → /  
    ├── contact.vue    → /contact
    └── about.vue      → /about  

Así de fácil 😉.

Rutas anidadas

Crea subdirectorios para rutas anidadas. Cada subdirectorio dentro de /pages crea un nuevo segmento en la ruta. Por ejemplo,

src/  
└── pages/  
     ├── welcome.vue          → /welcome 
     └── dashboard/  
          ├── settings.vue    → /dashboard/settings  
          └── profile.vue     → /dashboard/profile  

El caso especial de index en rutas

Habrás visto que index tiene un comportamiento algo especial. Este fichero representa la ruta base de su directorio. Con esta estructura:

src/  
└── pages/  
    ├── index.vue           → / 
    └── dashboard/  
        └── index.vue       → /dashboard

Rutas dinámicas y parámetros

Para rutas dinámicas y parámetros, Unplugin Vue Router utiliza corchetes como placeholders para los parámetros,

Es decir, que la siguiente estructura de carpetas

src/  
└── pages/  
    └── users/  
        ├── [id].vue     → /users/:id  
        └── index.vue    → /users  

Acceso a parámetros

Podemos acceder a los parámetros de igual forma que haríamos con el Vue Router habitualmente. Por ejemplo, para pages/users/[id].vue

<script setup lang="ts">  
const route = useRoute('/users/[id]')  
console.log(route.params.id) // Tipo inferido como string  
</script>  

Tipado seguro

El plugin genera tipos TypeScript para todas las rutas en typed-router.d.ts, proporcionando autocompletado y validación.

router.push('/users/123') // Autocompletado y validación
const { id } = route.params // Tipo inferido: `id: string`

Rutas catch-all

Para rutas que deben capturar múltiples segmentos de URL, podemos usar la sintaxis [...slug].vue,

Es decir, que por ejemplo la estructura:

src/
└── pages/
    └── docs/
        └── [...slug].vue → /docs/*

Página not-found

Para manejar rutas no existentes, crea un archivo [...not-found].vue en la raíz de pages/. Este capturará cualquier ruta no definida y mostrará tu página 404 personalizada.

src/
└── pages/
    └── [...not-found].vue

Extender rutas manualmente

También podemos añadir rutas adicionales, en el caso de que necesitemos personalizar alguna de ellas. Para ello, podemos editar el fichero routes.ts,

// src/routes.ts  
import { extendRoutes } from 'unplugin-vue-router'  

export default extendRoutes((routes) => {  
  routes.push({  
    path: '/custom',  
    component: () => import('./pages/custom.vue'),  
    meta: { requiresAuth: true }  
  })  
})