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.