File System Based Routing for Vite

Common errors

• TypeError: Pages is not a function

  cause 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?

  cause 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'

  cause 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.

Warnings

• gotcha 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.
  Fix: Consider migrating to `unplugin-vue-router` for new Vue projects or for existing projects seeking enhanced Vue Router integration and type safety.
• breaking 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.
  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.
• breaking 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`.
  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'`.
• breaking 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`.
  Fix: Upgrade `react-router` to v6 or higher, or explicitly install `vite-plugin-pages@0.18.2` if `react-router@5` must be retained.

Install

• npm install vite-plugin-pages npm
• yarn add vite-plugin-pages yarn
• pnpm add vite-plugin-pages pnpm

Imports

• Pages
  wrong:

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

  correct:

  import Pages from '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)
  wrong:

  import { routes } from '~pages'

  correct:

  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)
  wrong:

  import { routes } from '~react-pages'

  correct:

  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)
  wrong:

  import { routes } from '~solid-pages'

  correct:

  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)
  wrong:

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

  correct:

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

  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.

Quickstart

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>