{"id":12373,"library":"vite-plugin-pages","title":"File System Based Routing for Vite","description":"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.","status":"active","version":"0.33.3","language":"javascript","source_language":"en","source_url":"https://github.com/hannoeru/vite-plugin-pages","tags":["javascript","vite","vue","vue-router","react","react-router","solid-js","@solidjs/router","file-system-based","typescript"],"install":[{"cmd":"npm install vite-plugin-pages","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-pages","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-pages","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for Vue projects using the plugin for SFC compilation.","package":"@vue/compiler-sfc","optional":true},{"reason":"Core dependency as a Vite plugin. Supports a wide range of Vite versions.","package":"vite","optional":false}],"imports":[{"note":"Since v0.32.0, the plugin is ESM-only. CommonJS `require()` is no longer supported for importing the plugin itself.","wrong":"const Pages = require('vite-plugin-pages')","symbol":"Pages","correct":"import Pages from 'vite-plugin-pages'"},{"note":"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.","wrong":"import { routes } from '~pages'","symbol":"routes (Vue)","correct":"import routes from '~pages'"},{"note":"This virtual module provides generated React Router routes. Ensure you use the specific `~react-pages` path for React applications.","wrong":"import { routes } from '~react-pages'","symbol":"routes (React)","correct":"import routes from '~react-pages'"},{"note":"This virtual module provides generated SolidJS Router routes. Ensure you use the specific `~solid-pages` path for SolidJS applications.","wrong":"import { routes } from '~solid-pages'","symbol":"routes (Solid)","correct":"import routes from '~solid-pages'"},{"note":"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.","wrong":"import type {} from 'vite-plugin-pages/client'","symbol":"Type References (Vue/React)","correct":"/// <reference types=\"vite-plugin-pages/client\" /> // For Vue\n/// <reference types=\"vite-plugin-pages/client-react\" /> // For React"}],"quickstart":{"code":"import { defineConfig } from 'vite';\nimport Pages from 'vite-plugin-pages';\nimport Vue from '@vitejs/plugin-vue'; // Example for Vue, also supports React/Solid\nimport { createRouter, createWebHistory } from 'vue-router';\nimport { createApp } from 'vue';\n\n// vite.config.ts\nexport default defineConfig({\n  plugins: [\n    Vue(),\n    Pages({\n      dirs: 'src/pages', // Default directory for pages\n      extensions: ['vue', 'js', 'ts', 'jsx', 'tsx'], // Supported file extensions\n      exclude: ['**/components/**/*.vue'], // Exclude components from being treated as routes\n    }),\n  ],\n  // Optional: alias for ~pages for better IDE support, though usually auto-resolved\n  resolve: {\n    alias: {\n      '~pages': '/src/pages'\n    }\n  }\n});\n\n// src/main.ts (Example usage in a Vue app)\nimport App from './App.vue';\nimport routes from '~pages'; // Import the auto-generated routes\n\nconst router = createRouter({\n  history: createWebHistory(),\n  routes,\n});\n\ncreateApp(App).use(router).mount('#app');\n\n// src/App.vue (Minimal example)\n<template>\n  <router-view />\n</template>\n\n<script setup lang=\"ts\">\n// Application logic here\n</script>","lang":"typescript","description":"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."},"warnings":[{"fix":"Consider migrating to `unplugin-vue-router` for new Vue projects or for existing projects seeking enhanced Vue Router integration and type safety.","message":"For 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.","severity":"gotcha","affected_versions":">=0.19.0"},{"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.","message":"In 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.","severity":"breaking","affected_versions":">=0.33.0"},{"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'`.","message":"Version 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`.","severity":"breaking","affected_versions":">=0.32.0"},{"fix":"Upgrade `react-router` to v6 or higher, or explicitly install `vite-plugin-pages@0.18.2` if `react-router@5` must be retained.","message":"Since 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`.","severity":"breaking","affected_versions":">=0.19.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to `require('vite-plugin-pages')` in a CommonJS context after v0.32.0, where the package is ESM-only.","error":"TypeError: Pages is not a function"},{"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).","cause":"Incorrect import of the virtual routes module, typically trying to use named import (`import { routes } from '~pages'`) instead of default import.","error":"Module '~pages' has no exported member 'routes'. Did you mean to use a default import?"},{"fix":"Remove the unrecognized option from your `vite.config.ts`. Consult the official `vite-plugin-pages` documentation for the latest configuration options.","cause":"Using a configuration option that was deprecated and subsequently removed in `vite-plugin-pages` v0.33.0 or later.","error":"Failed to parse Vite config: [vite-plugin-pages] Unknown option: 'oldDeprecatedOption'"}],"ecosystem":"npm"}