Need help with vite-plugin-voie?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

brattonross
157 Stars 8 Forks MIT License 68 Commits 5 Opened issues

Description

File system based routing plugin for Vite

Services available

!
?

Need anything else?

Contributors list

# 382,102
Shell
irc-cli...
Twitch
TypeScr...
61 commits
# 6,332
vue3
TypeScr...
vscode
Visual ...
4 commits
# 60,296
TypeScr...
Nuxt.js
vuex
Shell
1 commit
# 288,887
vue-plu...
JavaScr...
vuejs2
vite
1 commit
# 1,307
Vue.js
JavaScr...
Svelte
mdl
1 commit

voie 🛣

npm version

File system based routing for Vue 3 applications using Vite

Voie is a Vite plugin that brings file system based routing to your Vue 3 applications.

Getting Started

Install Voie:

Vite 2 is supported from

^0.7.x
, Vite 1 support is discontinued
$ npm install -D vite-plugin-voie

Note:

[email protected]^4
is a peer dependency

Add to your

vite.config.js
:
import vue from '@vitejs/plugin-vue';
import voie from 'vite-plugin-voie';

export default { plugins: [vue(), voie()], };

Overview

By default a page is a Vue component exported from a

.vue
or
.js
file in the
src/pages
directory.

You can access the generated routes by importing the

voie-pages
module in your application.
import { createRouter } from 'vue-router';
import routes from 'voie-pages';

const router = createRouter({ // ... routes, });

Note: TypeScript users can install type definitions for the generated routes via the

voie-pages
package:
$ npm install -D voie-pages

Configuration

interface UserOptions {
  pagesDir?: string;
  extensions?: string[];
  importMode?: ImportMode | ImportModeResolveFn;
  extendRoute?: (route: Route, parent: Route | undefined) => Route | void;
}

pagesDir

Relative path to the pages directory. Supports globs.

Default:

'src/pages'

extensions

Array of valid file extensions for pages.

Default:

['vue', 'js']

importMode

Import mode can be set to either

async
,
sync
, or a function which returns one of those values.

Default:

'async'

To get more fine-grained control over which routes are loaded sync/async, you can use a function to resolve the value based on the route path. For example:

// vite.config.js
export default {
  // ...
  plugins: [
    voie({
      importMode(path) {
        // Load index synchronously, all other pages are async.
        return path.includes('index') ? 'sync' : 'async';
      },
    }),
  ],
};

extendRoute

A function that takes a route and optionally returns a modified route. This is useful for augmenting your routes with extra data (e.g. route metadata).

// vite.config.js
export default {
  // ...
  plugins: [
    voie({
      extendRoute(route, parent) {
        if (route.path === '/') {
          // Index is unauthenticated.
          return route;
        }

    // Augment the route with meta that indicates that the route requires authentication.
    return {
      ...route,
      meta: { auth: true },
    };
  },
}),

], };

Using configuration

To use custom configuration, pass your options to Voie when instantiating the plugin:

// vite.config.js
import voie from 'vite-plugin-voie';

export default { plugins: [ voie({ pagesDir: 'src/views', extensions: ['vue', 'ts'], }), ], };

File System Routing

Voie is inspired by the routing from NuxtJS 💚

Voie automatically generates an array of routes for you to plug-in to your instance of Vue Router. These routes are determined by the structure of the files in your pages directory. Simply create

.vue
files in your pages directory and routes will automatically be created for you, no additional configuration required!

For more advanced use cases, you can tailor Voie to fit the needs of your app through configuration.

Basic Routing

Voie will automatically map files from your pages directory to a route with the same name:

  • src/pages/users.vue
    ->
    /users
  • src/pages/users/profile.vue
    ->
    /users/profile
  • src/pages/settings.vue
    ->
    /settings

Index Routes

Files with the name

index
are treated as the index page of a route:
  • src/pages/index.vue
    ->
    /
  • src/pages/users/index.vue
    ->
    /users

Dynamic Routes

Dynamic routes are denoted using square brackets. Both directories and pages can be dynamic:

  • src/pages/users/[id].vue
    ->
    /users/:id
    (
    /users/one
    )
  • src/[user]/settings.vue
    ->
    /:user/settings
    (
    /one/settings
    )

Any dynamic parameters will be passed to the page as props. For example, given the file

src/pages/users/[id].vue
, the route
/users/abc
will be passed the following props:
{ "id": "abc" }

Nested Routes

We can make use of Vue Routers child routes to create nested layouts. The parent component can be defined by giving it the same name as the directory that contains your child routes.

For example, this directory structure:

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

will result in this routes configuration:

[
  {
    path: '/users',
    component: '/src/pages/users.vue',
    children: [
      {
        path: '',
        component: '/src/pages/users/index.vue',
        name: 'users',
      },
      {
        path: ':id',
        component: '/src/pages/users/[id].vue',
        name: 'users-id',
      },
    ],
  },
];

Catch-all Routes

Catch-all routes are denoted with square brackets containing an ellipsis:

  • src/pages/[...all].vue
    ->
    /*
    (
    /non-existent-page
    )

The text after the ellipsis will be used both to name the route, and as the name of the prop in which the route parameters are passed.

Thanks

Many thanks go to @antfu for their support of this project.

Trivia

voie is the french word for "way" and is pronounced

/vwa/
.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.