Vite Routes Plugin

Relevant source files

The following files were used as context for generating this wiki page:

• src/vite-plugin-routes.ts
• types/vite-plugin-routes.d.ts
• package.json
• examples/example/src/components/AppRoutes.vue
• src/components/Route.tsx

The Vite Routes Plugin is a build-time utility designed for the wouter-vue ecosystem. Its primary purpose is to automate the generation of static route configurations by scanning a directory of Vue components. This process eliminates the need for manual dynamic imports in route files, helping to keep the main bundle size small while ensuring that route components are efficiently split into separate chunks.

The plugin integrates directly into the Vite build pipeline, handling file discovery, route path generation based on configurable patterns, and automatic Rollup chunk configuration. It is particularly useful for projects with a large number of routes, as seen in the examples where up to 200 routes are managed.

Sources: src/vite-plugin-routes.ts:1-10, package.json:57-60

Plugin Architecture and Lifecycle

The plugin operates as a standard Vite plugin, hook-driven to manage the generation and resolution of route files. It primarily utilizes the buildStart, resolveId, config, and configResolved hooks.

Route Generation Flow

The generation logic resides within the buildStart hook. The plugin reads the target directory (defaulting to src/pages/routes), filters files based on a regex pattern, and sorts them to ensure deterministic output.

The flow above describes how the plugin identifies components and transforms them into a valid JavaScript module that exports an array of route objects.

Sources: src/vite-plugin-routes.ts:98-150, types/vite-plugin-routes.d.ts:42-47

Resolution and Aliasing

The plugin supports virtual aliasing via the resolveId hook. By default, it allows importing the generated file using a hash prefix (e.g., #routes/).

Configuration Options

The plugin is highly configurable through the RoutePluginOptions interface. This allows developers to customize directory locations, naming conventions, and optimization behaviors.

Option	Type	Default	Description
name	string	'routes'	Unique name for the router, used for aliases and chunks.
dir	string	'src/pages/routes'	Directory containing the .vue route components.
pattern	RegExp	/Route(\d+)\.vue$/	Regex pattern used to identify valid route files.
outputFile	string	'src/generated-routes.js'	The file path where the generated routes will be saved.
pathTemplate	function	(match) => "/route" + match[1]	Function to generate the URL path from regex match groups.
minify	boolean	true	Removes line breaks from the generated file.
compress	boolean	true	Uses template strings to reduce the size of the generated file for numeric routes.

Sources: src/vite-plugin-routes.ts:15-56, types/vite-plugin-routes.d.ts:5-40

Chunk Optimization and Manual Splitting

The plugin includes logic to automatically optimize the production build by grouping route components into specific chunks. This is handled via the manualChunks configuration in Rollup.

Automatic Chunking Logic

If not manually overridden, the plugin injects a manualChunks function that:

1. Groups the generated configuration file into a chunk named [name]-config.
2. Groups all route components found within the defined routesDir into a single named chunk (defaulting to the plugin name).

Sources: src/vite-plugin-routes.ts:225-245

Multi-Plugin Chunking

For applications using multiple instances of the plugin (e.g., for different sections of the site), a helper function createManualChunks is provided to merge multiple plugin chunking strategies.

Implementation Example

In a typical wouter-vue application, the generated routes are used within a component like AppRoutes.vue. While the plugin generates the file, the Route component consumes these imports.

// Generated content example (compressed)
// Sources: [src/vite-plugin-routes.ts:140-145]
const r1=()=>import('./pages/routes/Route1.vue');
const r2=()=>import('./pages/routes/Route2.vue');
export default [
  {path:'/route1', component:r1},
  {path:'/route2', component:r2}
];

The component src/components/Route.tsx is responsible for rendering these components once the plugin has mapped them to paths. It uses defineAsyncComponent internally to handle the functions generated by the plugin.

Sources: examples/example/src/components/AppRoutes.vue:44-55, src/components/Route.tsx:112-120

Conclusion

The Vite Routes Plugin serves as an automation layer for wouter-vue, bridging the gap between file-system based routing and high-performance manual route definitions. By automating the discovery and chunking of route components, it ensures that large-scale Vue applications maintain optimal loading performance without increasing developer overhead in route management.