File system based routing for Vue 3 applications using Vite

Install Pages:

$ npm install -D vite-plugin-pages

Add to your vite.config.js:

import Vue from '@vitejs/plugin-vue';
import Pages from 'vite-plugin-pages';

export default {
  plugins: [Vue(), Pages()],
};

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 virtual:generated-pages module in your application.

import { createRouter } from 'vue-router';
import routes from 'virtual:generated-pages';

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

interface UserOptions {
  pagesDir?: string | string[] | PageDirOptions[]
  extensions?: string[]
  exclude: string[]
  importMode?: ImportMode | ImportModeResolveFn
  syncIndex?: boolean
  routeBlockLang: 'json5' | 'json' | 'yaml'
  extendRoute?: (route: Route, parent: Route | undefined) => Route | void
}

Relative path to the pages directory. Supports globs.

Can be:

• single path: routes point to /
• array of paths: all routes in the paths point to /
• array of PageDirOptions allowing you to specify base routes instead of /. See Feature Areas for more details

Default: 'src/pages'

Array of valid file extensions for pages.

Default: ['vue', 'js']

An array of glob patterns to exclude matches.

Default: []

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

// vite.config.js
export default {
  // ...
  plugins: [
    Pages({
      exclude: ['**/components/*.vue']
    }),
  ],
};

Import mode can be set to either async, sync, or a function which returns one of those values.

Default:

• Top level index file: 'sync', can turn off by option syncIndex.
• Others: '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: [
    Pages({
      importMode(path) {
        // Load about page synchronously, all other pages are async.
        return path.includes('about') ? 'sync' : 'async';
      },
    }),
  ],
};

Default SFC route block parser.

Default: 'json5'

*experimental

Check: #16

Replace '[]' to '_' in bundle filename

Default: false

Use Nuxt.js style dynamic routing

More details: File System Routing

Default: false

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: [
    Pages({
      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 },
        };
      },
    }),
  ],
};

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

// vite.config.js
import Pages from 'vite-plugin-pages';

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

Add route meta to the route by adding a <route> block to the SFC. This will directly added to the route after it is generated, and will override it.

You can specific a parser to use using <route lang="yaml">, or set a default parser using routeBlockLang option.

Supported parser: JSON, JSON5, YAML

Default: JSON5

JSON/JSON5:

<route>
{
  name: "name-override",
  meta: {
    requiresAuth: false
  }
}
</route>

YAML:

<route lang="yaml">
name: name-override
meta:
  requiresAuth: true
</route>

Specifying an array of pagesDir allow you to use multiple pages folder, and specify the base route to append to the path and the route name.

Example:

folder structure:

src/
  ├── features/
  │  └── admin/
  │     ├── code/
  │     ├── components/
  │     └── pages/
  └── pages/

vite.config.js:

// pages options
pagesDir: [
  { dir: 'src/pages', baseRoute: '' },
  { dir: 'src/features/admin/pages', baseRoute: 'admin' },
],

Inspired by the routing from NuxtJS 💚

Pages 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 Pages to fit the needs of your app through configuration.

• Basic Routing
• Index Routes
• Dynamic Routes
• Nested Routes
• Catch-all Routes

Pages 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

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 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" }

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 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.

MIT License © 2021 hannoeru