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

1# npm install
2npm 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.

1// vite.config.ts
2import { defineConfig } from "vite";
3import react from "@vitejs/plugin-react";
4import createFileRouterPlugin from "vite-plugin-pages-router/plugin";
5
6export default defineConfig({
7  plugins: [
8    react(),
9    createFileRouterPlugin({
10      pagesDir: "src/pages", // Directory containing page components
11      notFoundPage: "src/pages/404.tsx", // 404 error page component path
12      loadingComponent: "src/components/Loading.tsx", // Loading component path
13    }),
14  ],
15  // Optional alias configuration (e.g., "src" path mapping)
16  resolve: {
17    alias: {
18      src: "/src",
19    },
20  },
21});

---

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)

1// src/pages/index.tsx
2import React from "react";
3
4function HomePage(): JSX.Element {
5  return (
6    <div className="p-4 text-center">
7      <h1 className="text-2xl font-bold">Home Page</h1>
8      <p>Welcome!</p>
9    </div>
10  );
11}
12
13export default HomePage;

About Page Example (src/pages/about.tsx)

1// src/pages/about.tsx
2import React from "react";
3
4function AboutPage(): JSX.Element {
5  return (
6    <div className="p-4 text-center">
7      <h1 className="text-2xl font-bold">About Page</h1>
8      <p>This is an example of file-based routing using the plugin.</p>
9    </div>
10  );
11}
12
13export default AboutPage;

---

3. Create 404 Page and Loading Component

404 Page Example (src/pages/404.tsx)

1// src/pages/404.tsx
2import React from "react";
3
4function NotFoundPage(): JSX.Element {
5  return (
6    <div className="p-4 text-center text-red-500">
7      <h1 className="text-2xl font-bold">404 - Page Not Found</h1>
8      <p>Sorry, the requested page does not exist.</p>
9    </div>
10  );
11}
12
13export default NotFoundPage;

Loading Component Example (src/components/Loading.tsx)

1// src/components/Loading.tsx
2import React from "react";
3
4function Loading(): JSX.Element {
5  return (
6    <div className="p-4 text-center">
7      <p className="text-lg">Loading...</p>
8    </div>
9  );
10}
11
12export default Loading;

---

4. Use in App Component

Import the <RouterConfig /> component from the virtual module provided by the plugin in your app.

1// src/App.tsx
2import React from "react";
3import RouterConfig from "vite-plugin-pages-router"; // Provided via virtual module
4
5function App(): JSX.Element {
6  return (
7    <div className="min-h-screen bg-gray-50">
8      <RouterConfig />
9    </div>
10  );
11}
12
13export default App;

---

5. Run the Project

Start the Vite dev server to verify functionality:

1npm 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.