unplugin-vue-router

What is unplugin-vue-router?

unplugin-vue-router is a plugin for Vue.js that provides enhanced routing capabilities. It simplifies the process of defining and managing routes in a Vue.js application, offering features like automatic route generation, route guards, and more.

What are unplugin-vue-router's main functionalities?

Automatic Route Generation

This feature allows you to automatically generate routes based on the file structure of your project. It simplifies the process of setting up routes by eliminating the need to manually define each route.

```javascript
import { createRouter, createWebHistory } from 'vue-router';
import routes from 'virtual:generated-pages';

const router = createRouter({
  history: createWebHistory(),
  routes,
});

export default router;
```

Route Guards

Route guards are used to protect certain routes based on conditions such as authentication status. This feature allows you to define global or per-route guards to control access to different parts of your application.

```javascript
router.beforeEach((to, from, next) => {
  if (to.meta.requiresAuth && !isAuthenticated()) {
    next({ name: 'login' });
  } else {
    next();
  }
});
```

Dynamic Routing

Dynamic routing allows you to define routes with dynamic segments, such as user IDs. This feature is useful for creating routes that depend on variable parameters.

```javascript
const routes = [
  { path: '/user/:id', component: UserComponent }
];

const router = createRouter({
  history: createWebHistory(),
  routes,
});
```

Other packages similar to unplugin-vue-router

vue-router

vue-router is the official router for Vue.js. It provides a comprehensive set of features for routing in Vue.js applications, including nested routes, route guards, and dynamic routing. Compared to unplugin-vue-router, vue-router requires more manual setup for route definitions but offers a high level of customization.

vite-plugin-pages

vite-plugin-pages is a Vite plugin that automatically generates routes based on the file structure of your project. It is similar to unplugin-vue-router in that it simplifies route management, but it is specifically designed to work with Vite, a build tool that is often used with Vue.js.

README

unplugin-vue-router

Automatic file based Routing in Vue with TS support ✨

• StackBlitz Demo

This build-time plugin simplifies your routing setup and makes it safer and easier to use thanks to TypeScript. Requires Vue Router >=4.4.0.

[!WARNING] While unplugin-vue-router typed routing and file based routing is fundamentally stable, it contains other experimental APIs that are subject to change (e.g. Data Loaders). Make sure to check the relevant Documentation for the latest information. If you find any issue, design flaw, or have ideas to improve it, please, open open an issue or a Discussion.

Install

npm i -D unplugin-vue-router

Add VueRouter plugin before Vue plugin:

Vite

// vite.config.ts
import VueRouter from 'unplugin-vue-router/vite'

export default defineConfig({
  plugins: [
    VueRouter({
      /* options */
    }),
    // ⚠️ Vue must be placed after VueRouter()
    Vue(),
  ],
})

Example: playground/

Rollup

// rollup.config.js
import VueRouter from 'unplugin-vue-router/rollup'

export default {
  plugins: [
    VueRouter({
      /* options */
    }),
    // ⚠️ Vue must be placed after VueRouter()
    Vue(),
  ],
}

Webpack

// webpack.config.js
module.exports = {
  /* ... */
  plugins: [
    require('unplugin-vue-router/webpack')({
      /* options */
    }),
  ],
}

Vue CLI

// vue.config.js
module.exports = {
  configureWebpack: {
    plugins: [
      require('unplugin-vue-router/webpack')({
        /* options */
      }),
    ],
  },
}

esbuild

// esbuild.config.js
import { build } from 'esbuild'
import VueRouter from 'unplugin-vue-router/esbuild'

build({
  plugins: [VueRouter()],
})

Setup

After installing, you should run your dev server (usually npm run dev) to generate the first version of the types. Then you need to add the types to your tsconfig.json.

{
  "include": [
    // ...
    "./typed-router.d.ts"
  ],
  // ...
  "compilerOptions": {
    // ...
    "moduleResolution": "Bundler"
    // ...
  }
}

Then, if you have an env.d.ts file like the one created by npm vue create <my-project>, add the unplugin-vue-router/client types to it:

// env.d.ts
/// <reference types="vite/client" />
/// <reference types="unplugin-vue-router/client" />

If you don't have an env.d.ts file, you can create one and add the unplugin-vue-router types to it or you can add them to the types property in your tsconfig.json:

{
  "compilerOptions": {
    // ...
    "types": ["unplugin-vue-router/client"]
  }
}

Finally, import the generated routes from vue-router/auto-routes and pass them to the router:

import { createRouter, createWebHistory } from 'vue-router'
+import { routes } from 'vue-router/auto-routes'

createRouter({
  history: createWebHistory(),
  // pass the generated routes written by the plugin 🤖
+  routes,
})

Alternatively, you can also import the routes array and create the router manually or pass it to some plugin. Here is an example with Vitesse starter:

 import { ViteSSG } from 'vite-ssg'
 import { setupLayouts } from 'virtual:generated-layouts'
 import App from './App.vue'
 import type { UserModule } from './types'
-import generatedRoutes from '~pages'
+import { routes } from 'vue-router/auto-routes'

 import '@unocss/reset/tailwind.css'
 import './styles/main.css'
 import 'uno.css'

-const routes = setupLayouts(generatedRoutes)

 // https://github.com/antfu/vite-ssg
 export const createApp = ViteSSG(
   App,
   {
-   routes,
+   routes: setupLayouts(routes),
    base: import.meta.env.BASE_URL
  },
   (ctx) => {
     // install all modules under `modules/`
     Object.values(import.meta.glob<{ install: UserModule }>('./modules/*.ts', { eager: true }))
       .forEach(i => i.install?.(ctx))
   },
 )

• 📖 Check more in the Documentation.

License

MIT

Changelog

0.10.8 (2024-09-08)

Features

• loaders: allow errors as a function (df80b28)
• loaders: allow plain value in colada loader key (646e5bf)
• loaders: avoid warning during ssr (99d7b0b)
• loaders: warn incorrect query usage (e43c5f5)