# vite-plugin-pages: file system routes for Vue, React and Solid, and when to reach for the built-in alternative

> vite-plugin-pages reads a directory and generates a route list for Vue 3, React and Solid Vite projects without manual router configuration. The v1 beta raised the floor to Node.js 22.12 and Vite 6, and the README itself tells Vue users to evaluate vue-router's built-in routing before adopting this plugin.

**hannoeru/vite-plugin-pages** — File system based route generator for ⚡️Vite

- Repository: https://github.com/hannoeru/vite-plugin-pages
- Stars: 2,078 · Forks: 129
- Language: TypeScript
- License: MIT
- Published: 2026-10-11 · Updated: 2026-10-11 · Language: en
- Canonical page: https://hysenlabs.com/projects/hannoeru-vite-plugin-pages

## File-based routing replaces hand-written route arrays in Vite projects

vite-plugin-pages reads a directory, typically src/pages, and emits a route list compatible with the router library of your chosen framework. Without a plugin of this kind, every new page requires an entry in a centrally managed route configuration file. With it, the directory layout is the configuration, and the route list updates automatically as files are added or removed during development.

Running as part of the Vite dev server and the production build, it needs no separate watcher, and changes to the directory structure take effect immediately in dev mode. It is authored in TypeScript and distributed as an ESM-only package.

One concrete discrepancy is worth noting before setup. In package.json, the description field reads "File system base vue-router plugin for Vite", a label that names only vue-router and not React or Solid. Compare that with the README, which describes the project as routing for Vue 3, React and Solid applications; the package.json keywords also include react, react-router, solid-js and @solidjs/router. Both the README and the keywords reflect a scope that the description field does not.

## Three frameworks share one install, each with its own virtual module id

Support covers Vue 3 with vue-router, React with react-router v6 or later, and Solid with @solidjs/router, and all three ship inside the same npm package. Framework-specific client type declarations live in separate files: client.d.ts for Vue, client-react.d.ts for React and client-solid.d.ts for Solid.

Importing generated routes differs by framework. Vue code imports from the virtual module ~pages, React from ~react-pages and Solid from ~solid-pages. Routers are peer dependencies and must be installed separately, so a React project still needs react-router at v6 or above in its own package.json.

Four paths are exported, as listed in the exports field of package.json: the main plugin index and the three client type paths. Client paths contain type declarations only and no runtime code, so all route matching happens inside the framework router at run time.

Sitemap generation sits outside the package scope, and the README points to vite-plugin-pages-sitemap as a companion package for that purpose.

## Installing v1.0.0-beta.2 and wiring the plugin into vite.config

Install with a single command:

```bash
npm install -D vite-plugin-pages
```

Add the plugin to your Vite configuration:

```ts
import Pages from 'vite-plugin-pages'

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

After that, create a starting file in the pages directory. Three options appear in the Quick Start: src/pages/index.vue for Vue 3, or src/pages/index.tsx or src/pages/index.jsx for React and Solid. From there, docs/getting-started.md covers wiring the generated route list to each framework's router, because this plugin generates the route object and the framework router consumes it.

v1 carries strict minimum versions. Node.js 22.12.0 or later is required, as set in the package.json engines field. Vite is accepted at v6, v7 and v8, with the peerDependency range expressed as "^6.0.0-0 || ^7.0.0-0 || ^8.0.0-0". A project using CommonJS modules must add "type": "module" to its own package.json, or restructure its Vite configuration to be ESM-compatible, before v1 works at all.

v0.33.3, released on 2026-02-02, is the last stable release before the beta series. Upgrading from v0.33 requires reading docs/migration-v1.md first, because the breaking changes between the two generations are documented there.

## Six example configurations cover nuxt-style, remix-style, SSR and framework targets

Six sub-directories live in examples/: nuxt-style, react, remix-style, solid, vue-ssr and vue. Both nuxt-style and remix-style indicate different file naming conventions for dynamic segments and nested layouts, and each controls how the plugin maps a file name or directory structure to a route parameter. Syntax details for each style live in docs/routing.md.

Convention choice carries a long-term cost. Switching from one style to another after building out a large pages directory means renaming files throughout the project, so the decision is worth settling once and staying consistent from the start.

A vue-ssr sub-directory shows that the plugin operates in server-side rendering setups, though SSR adds requirements beyond the Quick Start path, and docs/getting-started.md covers the framework-specific wiring for it.

For deploying below the domain root, docs/base-path.md documents the relevant plugin option, which is a separate concern from the routing style and can be configured independently.

## Per-file route metadata through Vue's route block syntax and JSX comments

vite-plugin-pages lets individual route files carry their own metadata without editing a central route array. In Vue single-file components, route metadata goes in a route block inside the file itself. For React and Solid, JSX comments serve the same purpose, and both mechanisms are documented in docs/route-data.md.

Co-locating metadata means a file that needs a specific route name, a redirect target or a custom property can declare it alongside the component that renders the route. Metadata is distributed across files rather than visible in one central location, which is the tradeoff that comes with this approach.

What the plugin can write into a route object is bounded by what each framework's router accepts: vue-router's route record shape for Vue, react-router v6's route definition for React and @solidjs/router's equivalent structure for Solid. docs/route-data.md describes the supported fields for each target.

## The peerDependency on @vue/compiler-sfc accepts 2.7 but the README targets Vue 3 only

In package.json, the peerDependencies field lists "@vue/compiler-sfc": "^2.7.0 || ^3.0.0". That range includes Vue 2.7 alongside Vue 3, but the README describes the project as routing for Vue 3 applications and gives no setup path for Vue 2.7 at all.

A Vue 2.7 project technically satisfies the peer dependency check but has no documented configuration path in the README or the Getting Started guide. Anyone on Vue 2.7 would need to work through docs/getting-started.md and open an issue if setup fails, because the mismatch between the peer range and the stated Vue 3 target goes unexplained in the documentation.

For React and Solid this peer dependency is irrelevant. Only Vue projects depend on @vue/compiler-sfc, and three separate client type declaration files each cover one framework, so the type situation for React and Solid users is fully independent of anything Vue-specific.

## When the README itself recommends vue-router's own file-based routing over this plugin

Placed directly below the framework support table, the first substantive note in the README tells Vue users to consider vue-router's built-in file-based routing instead, stating that it provides similar features with deeper vue-router integration. That recommendation appears in the opening section rather than in a changelog or a migration note, so it is not a warning about a specific edge case.

For React and Solid, no comparable built-in file routing exists at the router level, which makes the plugin more directly applicable for those two targets. For Vue 3 projects, the question of whether vite-plugin-pages offers capabilities the vue-router built-in does not cover is left unanswered by the README, and those differences are not enumerated anywhere in the Quick Start.

docs/config.md, which documents every plugin option, is the right place to check for configuration points that might justify choosing this plugin over the native Vue solution. One such candidate is the Custom Resolver API, documented under the name PageResolver in docs/custom-resolver.md, which controls how file paths map to route objects and is a configuration level a built-in convention does not expose.

## Conclusion

vite-plugin-pages makes the most sense for React and Solid Vite projects, where no equivalent built-in file-based routing exists at the router level. For a new Vue 3 project, the README's own introduction recommends evaluating vue-router's built-in file-based routing first, citing deeper integration with that router. Before adopting v1, confirm your project runs Node.js 22.12 and Vite 6 or later, and read docs/migration-v1.md if upgrading from a v0.x install. For React and Solid, open docs/getting-started.md and follow the framework-specific setup steps before creating your first page file.

## FAQ

### What is vite-plugin-pages?

vite-plugin-pages is a Vite plugin that reads a pages directory and generates a route list for Vue 3, React and Solid projects. Vue projects import routes from the ~pages virtual module, React from ~react-pages and Solid from ~solid-pages.

### What are the requirements for vite-plugin-pages v1?

v1 requires Node.js 22.12 or later, Vite 6 or later, and an ESM project or ESM-compatible Vite configuration. The peerDependency range for Vite covers v6, v7 and v8.

### Is there a migration guide for upgrading to vite-plugin-pages v1?

Yes. The repository includes a guide at docs/migration-v1.md that covers the requirements and breaking changes for upgrading to v1.

### Does vite-plugin-pages support server-side rendering?

Yes. The examples/ directory includes a vue-ssr sub-directory, and docs/getting-started.md covers the framework-specific wiring for SSR setups.

### How do I add metadata to a route in vite-plugin-pages?

In Vue single-file components, route metadata goes in a route block inside the file. For React and Solid, JSX comments serve the same purpose. Both mechanisms are documented in docs/route-data.md.

## Sources

- [hannoeru/vite-plugin-pages on GitHub](https://github.com/hannoeru/vite-plugin-pages)
- [Issues](https://github.com/hannoeru/vite-plugin-pages/issues)
- [License: MIT](https://github.com/hannoeru/vite-plugin-pages/blob/main/LICENSE)
- [README](https://github.com/hannoeru/vite-plugin-pages/blob/main/README.md)
- [Releases](https://github.com/hannoeru/vite-plugin-pages/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/hannoeru-vite-plugin-pages