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 React component internally,
> allowing file-based routing without requiring separate router configuration files.

---

Installation

bash

npm install

npm install vite-plugin-pages-router





---



Usage



$3



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

 in your app.

ts

// 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",

    },

  },

});





---



$3



Create page components inside the

src/pages

 directory.  

Examples for a home page and an about page:



#### Home Page Example (

src/pages/index.tsx

tsx

// src/pages/index.tsx

import React from "react";



function HomePage(): JSX.Element {

  return (

    

      Home Page

      Welcome!

    

  );

}



export default HomePage;





#### About Page Example (

src/pages/about.tsx

tsx

// src/pages/about.tsx

import React from "react";



function AboutPage(): JSX.Element {

  return (

    

      About Page

      This is an example of file-based routing using the plugin.

    

  );

}



export default AboutPage;





---



$3



#### 404 Page Example (

src/pages/404.tsx

tsx

// src/pages/404.tsx

import React from "react";



function NotFoundPage(): JSX.Element {

  return (

    

      404 - Page Not Found

      Sorry, the requested page does not exist.

    

  );

}



export default NotFoundPage;





#### Loading Component Example (

src/components/Loading.tsx

tsx

// src/components/Loading.tsx

import React from "react";



function Loading(): JSX.Element {

  return (

    

      Loading...

    

  );

}



export default Loading;





---



$3



Import the

 component from the virtual module provided by the plugin in your app.

tsx

// src/App.tsx

import React from "react";

import RouterConfig from "vite-plugin-pages-router"; // Provided via virtual module



function App(): JSX.Element {

  return (

    

      

    

  );

}



export default App;





---



$3



Start the Vite dev server to verify functionality:

bash

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

.  

    Default:

.

  - If

notFoundPage

 is provided, it is used for 404 routes.  

    Default:

404 Not Found

.



- Virtual Module:

  The plugin provides the

 component via Vite's virtual module system.  

  This component includes

, , `, 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.

Installation

bash

npm install

npm install vite-plugin-pages-router

---

Usage

$3

Import and register the plugin in your

file with desired options.
The plugin serves two roles:

- Vite Plugin:
- Import the plugin function from

.
- React Router Configuration Component:
- Import the virtual module from the main package (

) to use

 in your app.

ts

// 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",

    },

  },

});





---



$3



Create page components inside the