Vite Plugin Pages Router

1.0.25 verified Fri May 01 auth: no javascript

vite-plugin-pages-router (v1.0.25) is a Vite plugin that provides Next.js-style file-based routing for React projects. It scans .tsx files in a pages directory and auto-generates React Router v6 route configs via Vite's virtual module system. Unlike similar plugins (e.g., vite-plugin-pages), this plugin avoids generating a file on disk, keeping the route configuration internal. Requires React 18+, React Router v6+, and Vite 4+. Ships TypeScript types. Development appears active with recent releases.

Common errors

error Error: [plugin:vite-plugin-pages-router] Cannot find module 'vite-plugin-pages-router/plugin' ↓

cause Plugin is not installed or import path is wrong.

fix

Run npm install vite-plugin-pages-router and verify the import path is 'vite-plugin-pages-router/plugin'.

error Module '"vite-plugin-pages-router"' has no exported member 'RouterConfig'. Did you mean to use 'import RouterConfig from "vite-plugin-pages-router"' instead? ↓

cause Using named import for RouterConfig instead of default import.

fix

Change to: import RouterConfig from 'vite-plugin-pages-router'

error TypeError: createFileRouterPlugin is not a function ↓

cause Imported from wrong path or import style (e.g., named import from main package).

fix

Use default import from 'vite-plugin-pages-router/plugin': import createFileRouterPlugin from 'vite-plugin-pages-router/plugin'

error Cannot find module 'src/pages/404.tsx' or its corresponding type declarations. ↓

cause The notFoundPage path in plugin options is incorrect or file missing.

fix

Ensure the file exists at the specified path relative to project root.

Warnings

breaking Import createFileRouterPlugin from 'vite-plugin-pages-router' instead of 'vite-plugin-pages-router/plugin' ↓

fix Use the correct import path: import createFileRouterPlugin from 'vite-plugin-pages-router/plugin'

breaking Named import { RouterConfig } from 'vite-plugin-pages-router' returns undefined ↓

fix Use default import: import RouterConfig from 'vite-plugin-pages-router'

gotcha Plugin does not generate RouterConfig.tsx file on disk; it uses a virtual module. Do not look for a physical file. ↓

fix Simply import RouterConfig from the package name; Vite will resolve it virtually.

gotcha Missing notFoundPage or loadingComponent option will cause errors if the 404 page or lazy loading triggers ↓

fix Ensure both options point to existing .tsx files that export default a component.

Install

npm install vite-plugin-pages-router

yarn add vite-plugin-pages-router

pnpm add vite-plugin-pages-router

Imports

createFileRouterPlugin

wrong

import createFileRouterPlugin from 'vite-plugin-pages-router'

correct

import createFileRouterPlugin from 'vite-plugin-pages-router/plugin'

The plugin function is exported from the /plugin subpath, not the main package.

RouterConfig

wrong

import { RouterConfig } from 'vite-plugin-pages-router'

correct

import RouterConfig from 'vite-plugin-pages-router'

RouterConfig is a default export from the virtual module. Named import will fail.

CreateFileRouterOptions

wrong

import { CreateFileRouterOptions } from 'vite-plugin-pages-router'

correct

import type { CreateFileRouterOptions } from 'vite-plugin-pages-router/plugin'

Type import must be from the /plugin subpath; main package does not export types.

Quickstart

Minimal setup: register plugin in vite.config.ts, then use RouterConfig component in App to enable file-based routing.

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import createFileRouterPlugin from 'vite-plugin-pages-router/plugin';

export default defineConfig({
  plugins: [
    react(),
    createFileRouterPlugin({
      pagesDir: 'src/pages',
      notFoundPage: 'src/pages/404.tsx',
      loadingComponent: 'src/components/Loading.tsx',
    }),
  ],
});

// src/App.tsx
import RouterConfig from 'vite-plugin-pages-router';

function App() {
  return <RouterConfig />;
}
export default App;

// src/pages/index.tsx
function HomePage() {
  return <h1>Home</h1>;
}
export default HomePage;