@xyh19/vite-plugin-route-pages
v1.0.5
Published
File system based routing for Vue 3 applications using Vite
Downloads
2
Maintainers
Readme
🏠 Homepage
Getting Started
Vue
install:
npm install -D @xyh19/vite-plugin-route-pages
npm install vue-router@next
Add to your vite.config.js
:
import Vue from '@vitejs/plugin-vue'
import Pages from '@xyh19/vite-plugin-route-pages'
export default {
plugins: [Vue(), Pages()],
}
React
install:
npm install -D @xyh19/vite-plugin-route-pages
npm install react-router react-router-dom react-router-config
Add to your vite.config.js
:
import * as reactPlugin from 'vite-plugin-react'
import Pages from '@xyh19/vite-plugin-route-pages'
export default {
jsx: 'react',
plugins: [
reactPlugin,
Pages({
react: true,
}),
],
}
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 virtual:generated-pages
module in your application.
Vue
import { createRouter } from 'vue-router'
import routes from 'virtual:generated-pages'
const router = createRouter({
// ...
routes,
})
Type
// vite-env.d.ts
/// <reference types="@xyh19/vite-plugin-route-pages/client" />
React
import { BrowserRouter } from 'react-router-dom'
import { renderRoutes } from 'react-router-config'
import routes from 'virtual:generated-pages-react'
ReactDOM.render(
<BrowserRouter>{renderRoutes(routes)}</BrowserRouter>,
document.getElementById('root')
)
Type
// vite-env.d.ts
/// <reference types="@xyh19/vite-plugin-route-pages/client-react" />
Configuration
To use custom configuration, pass your options to Pages when instantiating the plugin:
// vite.config.js
import Pages from '@xyh19/vite-plugin-route-pages'
export default {
plugins: [
Pages({
pagesDir: 'src/views',
}),
],
}
pagesDir
- Type:
string | (string | PageDirOptions)[]
- Default:
'src/pages'
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
, Check below 👇
Specifying a glob or an array of PageDirOptions
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/
│ └── dashboard/
│ ├── code/
│ ├── components/
│ └── pages/
├── admin/
│ ├── code/
│ ├── components/
│ └── pages/
└── pages/
// vite.config.js
export default {
plugins: [
Pages({
pagesDir: [
{ dir: 'src/pages', baseRoute: '' },
{ dir: 'src/features/**/pages', baseRoute: 'features' },
{ dir: 'src/admin/pages', baseRoute: 'admin' },
],
}),
],
}
extensions
- Type:
string[]
- Default:
- Vue:
['vue', 'tsx', 'ts', 'jsx', 'js']
- React:
['tsx', 'ts', 'jsx', 'js']
- Vue:
An array of valid file extensions for pages.
exclude
- Type:
string[]
- Default:
[]
An array of glob patterns to exclude matches.
# folder structure
src/pages/
├── users/
│ ├── components
│ │ └── form.vue
│ ├── [id].vue
│ └── index.vue
└── home.vue
// vite.config.js
export default {
plugins: [
Pages({
exclude: ['**/components/*.vue'],
}),
],
}
importMode
- Type:
'sync' | 'async' | (filepath: string) => 'sync' | 'async')
- Default:
- Top level index file:
'sync'
, can turn off by optionsyncIndex
. - Others(Vue):
'async'
- Others(React):
'sync'
- Top level index file:
Import mode can be set to either async
, sync
, or a function which returns
one of those values.
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'
},
}),
],
}
enableRouteBlock(experimental)
- Type:
boolean
- Default:
false
Enable route-block scanner.
routeBlockLang
- Type:
string
- Default:
'json5'
Default SFC route block parser.
replaceSquareBrackets
- Type:
boolean
- Default:
false
Replace '[]' to '_' in bundle filename
replaceDynamicPatterns
- Type:
Record<string, string>
Replace dynamiRoute pattern
// vite.config.js
export default {
// ...
plugins: [
Pages({
pagesDir: 'src/pages',
replaceDynamicPatterns: {
age: '\\d{1,3}', // 'src/pages/[a(age)].vue' => '/:a(\\d{1,3})'
},
}),
],
}
nuxtStyle
- Type:
boolean
- Default:
false
Use Nuxt.js style dynamic routing
More details: File System Routing
extendRoute
- Type:
(route: Route, parent: Route | undefined) => Route | void | Promise<Route | void>
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 },
}
},
}),
],
}
custom block for Route Data
SFC
Add route meta to the route by adding a <route>
block to the SFC and set config enableRouteBlock = true
. This will be
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>
Syntax Highlighting <route>
To enable syntax highlighting <route>
in VS Code using Vetur's Custom Code Blocks add the following snippet to your preferences...
- update setting
"vetur.grammar.customBlocks": {
"route": "json"
}
- Run the command in vscode
Vetur: Generate grammar from vetur.grammar.customBlocks
- Restart VS Code to get syntax highlighting for custom blocks.
jsx
Add route meta to the route by adding a <route>
element to the jsx and set config enableRouteBlock = true
. This will be
directly added to the route after it is generated, and will override it.
<route>
{{
name: 'name-override',
meta: {
requiresAuth: true,
},
}}
</route>
File System Routing
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
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
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.
🤝 Contributing
Contributions, issues and feature requests are welcome!Feel free to check issues page.
Show your support
Give a ⭐️ if this project helped you!