Registry / web-framework / vite-plugin-pages

vite-plugin-pages

library0.33.3jsnpmunverified

vite-plugin-pages is a Vite plugin that enables file system-based routing for modern JavaScript frameworks, currently supporting Vue 3, React, and SolidJS applications. As of version 0.33.3, the project maintains an active development pace, regularly updating to support the latest Vite versions (e.g., v8, v7, v6, v5 were recently added). Its core value proposition is simplifying route management by automatically generating routes from a predefined directory structure, eliminating the need for manual route configuration in large applications. However, a significant recommendation is that for Vue users, the official `unplugin-vue-router` is generally preferred due to its deeper integration with `vue-router`'s internals and advanced features like auto-generated route types with autocomplete, offering a more tailored developer experience. This positions `vite-plugin-pages` as a robust, general-purpose solution particularly valuable for React and SolidJS ecosystems, or for simpler Vue setups where advanced `vue-router` integration might not be a primary concern.

web-framework

npm install vite-plugin-pages

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-PAGES

vite-plugin-pages

web-frameworkjavascriptv0.33.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Pages

✓ import Pages from 'vite-plugin-pages'

✗ const Pages = require('vite-plugin-pages')

Since v0.32.0, the plugin is ESM-only. CommonJS `require()` is no longer supported for importing the plugin itself.

routes (Vue)

✓ import routes from '~pages'

✗ import { routes } from '~pages'

This is a virtual module provided by the plugin, dynamically generating your Vue routes based on file system structure. Do not try to destructure it.

routes (React)

✓ import routes from '~react-pages'

✗ import { routes } from '~react-pages'

This virtual module provides generated React Router routes. Ensure you use the specific `~react-pages` path for React applications.

routes (Solid)

✓ import routes from '~solid-pages'

✗ import { routes } from '~solid-pages'

This virtual module provides generated SolidJS Router routes. Ensure you use the specific `~solid-pages` path for SolidJS applications.

Type References (Vue/React)

✓ /// <reference types="vite-plugin-pages/client" /> // For Vue /// <reference types="vite-plugin-pages/client-react" /> // For React

✗ import type {} from 'vite-plugin-pages/client'

These are TypeScript triple-slash directives, typically placed in `vite-env.d.ts`, to provide type augmentation for the generated route modules. They are not standard `import` statements.

This quickstart demonstrates how to configure `vite-plugin-pages` in `vite.config.ts` and integrate the auto-generated routes into a basic Vue 3 application, including common options.

import { defineConfig } from 'vite'; import Pages from 'vite-plugin-pages'; import Vue from '@vitejs/plugin-vue'; // Example for Vue, also supports React/Solid import { createRouter, createWebHistory } from 'vue-router'; import { createApp } from 'vue'; // vite.config.ts export default defineConfig({ plugins: [ Vue(), Pages({ dirs: 'src/pages', // Default directory for pages extensions: ['vue', 'js', 'ts', 'jsx', 'tsx'], // Supported file extensions exclude: ['**/components/**/*.vue'], // Exclude components from being treated as routes }), ], // Optional: alias for ~pages for better IDE support, though usually auto-resolved resolve: { alias: { '~pages': '/src/pages' } } }); // src/main.ts (Example usage in a Vue app) import App from './App.vue'; import routes from '~pages'; // Import the auto-generated routes const router = createRouter({ history: createWebHistory(), routes, }); createApp(App).use(router).mount('#app'); // src/App.vue (Minimal example) <template> <router-view /> </template> <script setup lang="ts"> // Application logic here </script>

Debug

Known issues

gotchaFor Vue.js users, the official `unplugin-vue-router` is recommended over `vite-plugin-pages` due to its deeper integration with `vue-router`, improved type generation, and advanced features. While `vite-plugin-pages` still supports Vue, `unplugin-vue-router` offers a superior developer experience for Vue applications.

fix

Consider migrating to `unplugin-vue-router` for new Vue projects or for existing projects seeking enhanced Vue Router integration and type safety.

affects: >=0.19.0

breakingIn v0.33.0, all previously deprecated options were removed. Projects upgrading to or past this version must update their `vite-plugin-pages` configuration to use current options or remove invalid ones, which will result in build errors if not addressed.

fix

Review your `vite.config.ts` and remove any deprecated options. Refer to the latest documentation for `vite-plugin-pages` to use currently supported configuration properties.

affects: >=0.33.0

breakingVersion 0.32.0 migrated the package to be an ESM-only module. This means CommonJS `require()` syntax is no longer supported for importing `vite-plugin-pages`, and projects not configured for ESM will encounter `ERR_REQUIRE_ESM`.

fix

Ensure your Vite configuration and project are set up for ESM. Update import statements from `const Pages = require('vite-plugin-pages')` to `import Pages from 'vite-plugin-pages'`.

affects: >=0.32.0

breakingSince v0.19.0, `vite-plugin-pages` only supports `react-router` version 6 and above. Users on `react-router` v5 will encounter incompatibilities and must either upgrade `react-router` or use an older version of `vite-plugin-pages`.

fix

Upgrade `react-router` to v6 or higher, or explicitly install `vite-plugin-pages@0.18.2` if `react-router@5` must be retained.

affects: >=0.19.0

Errors

Common errors & fixes

TypeError: Pages is not a function

Attempting to `require('vite-plugin-pages')` in a CommonJS context after v0.32.0, where the package is ESM-only.

fix

Change `const Pages = require('vite-plugin-pages')` to `import Pages from 'vite-plugin-pages'` in your `vite.config.ts` and ensure your project is configured for ESM.

Module '~pages' has no exported member 'routes'. Did you mean to use a default import?

Incorrect import of the virtual routes module, typically trying to use named import (`import { routes } from '~pages'`) instead of default import.

fix

Use the correct default import syntax: `import routes from '~pages'` (for Vue), `import routes from '~react-pages'` (for React), or `import routes from '~solid-pages'` (for Solid).

Failed to parse Vite config: [vite-plugin-pages] Unknown option: 'oldDeprecatedOption'

Using a configuration option that was deprecated and subsequently removed in `vite-plugin-pages` v0.33.0 or later.

fix

Remove the unrecognized option from your `vite.config.ts`. Consult the official `vite-plugin-pages` documentation for the latest configuration options.

Upgrade

Version history

0.33.3latest on npm

Audit

Dependencies

@vue/compiler-sfcoptionalRequired for Vue projects using the plugin for SFC compilation.

viterequiredCore dependency as a Vite plugin. Supports a wide range of Vite versions.

Agent activity

5 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/hannoeru/vite-plugin-pages ↗

packagehttps://www.npmjs.com/package/vite-plugin-pages ↗