vite-plugin-auto-route

2.1.0 verified Mon Apr 27 auth: no javascript

A Vite plugin for automatic file-based routing in Vue 3, similar to Nuxt, Next.js, and UmiJS. Current stable version is 2.1.0. It generates vue-router route configurations from a directory structure, producing lazy-loaded components and nested routes automatically. Released as a dev dependency, it supports both ESM and CJS but recommends ESM. Key differentiator: lightweight, no full framework overhead, integrates directly with Vite and Vue Router without additional runtime dependencies. Does not support hot module reloading for new routes, requires page refresh after adding files. Ships TypeScript types.

Common errors

error Cannot find module 'vite-plugin-auto-route' or its corresponding type declarations. ↓

cause Missing package installation or incorrect import path.

fix

Run npm install --save-dev vite-plugin-auto-route and ensure package.json contains it.

error Plugin 'vite-plugin-auto-route' is not a function. ↓

cause Using CommonJS require() or incorrect default import.

fix

Use ES module import: import VitePluginAutoRoute from 'vite-plugin-auto-route'

error Error: The 'routesFile' option must be a string. ↓

cause Passing an object or non-string value to routesFile option.

fix

Set routesFile to a valid file path string, e.g., './src/router/autoRoutes.ts'

error No routes generated. The views directory is empty or path is wrong. ↓

cause pagesDir option pointing to incorrect or empty directory.

fix

Ensure pagesDir exists and contains .vue files; check the path relative to project root.

Warnings

gotcha Hot module reloading does not work for new pages. Adding a new .vue file requires a full page refresh to see the new route. ↓

fix Manually refresh the browser after adding new files.

deprecated CommonJS require pattern may not work in future versions. ESM is recommended. ↓

fix Use ES module import: import VitePluginAutoRoute from 'vite-plugin-auto-route'

gotcha The plugin generates a TypeScript file with explicit component paths. You must use import.meta.glob to resolve them, as shown in the docs. ↓

fix Follow the provided setup with import.meta.glob to map string paths to actual components.

gotcha If you install the plugin as 'vite-plugin-auto-routes' (note the 's'), you will get a different, unrelated package. ↓

fix Install the correct package: 'vite-plugin-auto-route'

Install

npm install vite-plugin-auto-route

yarn add vite-plugin-auto-route

pnpm add vite-plugin-auto-route

Imports

default

wrong

const VitePluginAutoRoute = require('vite-plugin-auto-route')

correct

import VitePluginAutoRoute from 'vite-plugin-auto-route'

ESM is recommended; CJS may work but is not officially supported.

GeneratedRoute

wrong

import { GeneratedRoute } from 'vite-plugin-auto-route'

correct

import type { GeneratedRoute } from 'vite-plugin-auto-route'

GeneratedRoute is a type export, not a runtime value. Use type import.

AutoRoutesOptions

wrong

const { AutoRoutesOptions } = require('vite-plugin-auto-route')

correct

import type { AutoRoutesOptions } from 'vite-plugin-auto-route'

Options interface is also a type export.

Quickstart

Basic setup: registers the plugin in vite.config.ts, generating routes from views folder to a file automatically.

// vite.config.ts
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import VitePluginAutoRoute from 'vite-plugin-auto-route';

export default defineConfig({
  plugins: [
    vue(),
    VitePluginAutoRoute({
      pagesDir: './src/views',
      routesFile: './src/router/autoRoutes.ts',
    }),
  ],
});