vite-plugin-pages-router
vite-plugin-pages-router is a plugin that enables Next.js-style file-based routing for Vite and React projects.
It automatically scans .tsx page files in the src/pages directory and generates routing configurations via virtual modules.
The plugin also automatically imports and applies user-provided 404 page and loading component from the specified options.
Note:
This plugin does not physically create a RouterConfig.tsx file on disk.
Instead, it leverages Vite's virtual module system to provide the <RouterConfig /> React component internally,
allowing file-based routing without requiring separate router configuration files.
Installation
# npm install
npm install vite-plugin-pages-router
Usage
1. Configure Vite Config File
Import and register the plugin in your vite.config.ts file with desired options.
The plugin serves two roles:
- Vite Plugin:
- Import the plugin function from
vite-plugin-pages-router/plugin.
- React Router Configuration Component:
- Import the virtual module from the main package (
vite-plugin-pages-router) to use <RouterConfig /> in your app.
// 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", // Directory containing page components
notFoundPage: "src/pages/404.tsx", // 404 error page component path
loadingComponent: "src/components/Loading.tsx", // Loading component path
}),
],
// Optional alias configuration (e.g., "src" path mapping)
resolve: {
alias: {
src: "/src",
},
},
});
2. Create Page Components
Create page components inside the src/pages directory.
Examples for a home page and an about page:
Home Page Example (src/pages/index.tsx)
// src/pages/index.tsx
import React from "react";
function HomePage(): JSX.Element {
return (
<div className="p-4 text-center">
<h1 className="text-2xl font-bold">Home Page</h1>
<p>Welcome!</p>
</div>
);
}
export default HomePage;
About Page Example (src/pages/about.tsx)
// src/pages/about.tsx
import React from "react";
function AboutPage(): JSX.Element {
return (
<div className="p-4 text-center">
<h1 className="text-2xl font-bold">About Page</h1>
<p>This is an example of file-based routing using the plugin.</p>
</div>
);
}
export default AboutPage;
3. Create 404 Page and Loading Component
404 Page Example (src/pages/404.tsx)
// src/pages/404.tsx
import React from "react";
function NotFoundPage(): JSX.Element {
return (
<div className="p-4 text-center text-red-500">
<h1 className="text-2xl font-bold">404 - Page Not Found</h1>
<p>Sorry, the requested page does not exist.</p>
</div>
);
}
export default NotFoundPage;
Loading Component Example (src/components/Loading.tsx)
// src/components/Loading.tsx
import React from "react";
function Loading(): JSX.Element {
return (
<div className="p-4 text-center">
<p className="text-lg">Loading...</p>
</div>
);
}
export default Loading;
4. Use in App Component
Import the <RouterConfig /> component from the virtual module provided by the plugin in your app.
// src/App.tsx
import React from "react";
import RouterConfig from "vite-plugin-pages-router"; // Provided via virtual module
function App(): JSX.Element {
return (
<div className="min-h-screen bg-gray-50">
<RouterConfig />
</div>
);
}
export default App;
5. Run the Project
Start the Vite dev server to verify functionality:
npm run dev
Visit http://localhost:5173 in your browser.
The file-based routing will render / (Home), /about (About), and other pages automatically.
Accessing an invalid route will display the 404 page, and page transitions will show the loading component.
How It Works
-
Automatic File Scanning:
The plugin scans all .tsx files in src/pages to generate route paths:
index.tsx → /about.tsx → /about[id].tsx → /:id
-
Loading & 404 Handling:
- If
loadingComponent is provided, it is used as the <Suspense fallback={...}>.
Default: <div>Loading...</div>.
- If
notFoundPage is provided, it is used for 404 routes.
Default: <div>404 Not Found</div>.
-
Virtual Module:
The plugin provides the <RouterConfig /> component via Vite's virtual module system.
This component includes <BrowserRouter>, <Suspense>, <Routes>, and 404 handling.
Routes automatically update when page files are added/removed.
By installing and configuring this plugin, you can implement file-based routing without manual router setup.
For questions or issues, visit GitHub Issues.
Tip: File-based routing mirrors your directory structure, automatically updating routes as you add/remove pages.
This significantly improves development efficiency.
