Vite Plugin Pagefiles

0.4.2 verified Mon Apr 27 auth: no javascript

Vite plugin that statically extracts metadata from React component files and generates client-side route declarations, currently at version 0.4.2 (pre-release, API unstable). Instead of file-system-based routing, this plugin allows developers to define routes inline within component files using a Meta export, providing flexibility in code organization. It generates a virtual module 'virtual:pagefiles' containing route configurations. Currently supports React only, but extensible to other frameworks. Releases are on GitHub but no fixed cadence. Key differentiator: route metadata lives inside the component file, not the file path, decoupling URL structure from file organization.

Common errors

error Cannot find module 'virtual:pagefiles' or its corresponding type declarations. ↓

cause Missing TypeScript declaration for the virtual module.

fix

Add a declaration file (e.g., src/pagefiles.d.ts) with: declare module 'virtual:pagefiles' { import { RouteObject } from 'react-router-dom'; const routes: RouteObject[]; export default routes; }

error TypeError: pagefiles is not a function ↓

cause Using named import instead of default import for the plugin.

fix

Change import { pagefiles } from 'vite-plugin-pagefiles' to import pagefiles from 'vite-plugin-pagefiles'.

error Warning: React.lazy(...) requires a Suspense boundary. ↓

cause Missing Suspense wrapper when using default lazy loading.

fix

Wrap the component that calls useRoutes(routes) in <Suspense fallback={<div>Loading...</div>}>.

Warnings

breaking Version 0.x is experimental and API changes will not follow semver. Major refactors may occur in minor releases. ↓

fix Pin to exact version and expect manual migration with each update.

deprecated The plugin only supports React as of v0.4.2. Vue support is not yet available. ↓

fix Use other frameworks (e.g., Next.js) if React is not your choice, or consider contributing support.

gotcha Virtual module 'virtual:pagefiles' is not a real file; importing outside Vite's transform pipeline will fail. ↓

fix Only import 'virtual:pagefiles' within files processed by Vite (e.g., inside src/).

gotcha By default, pagefiles are loaded lazily via React.lazy(). You must wrap useRoutes in a Suspense component to handle loading states. ↓

fix Add <Suspense fallback={...}> around the component using useRoutes(routes).

Install

npm install vite-plugin-pagefiles

yarn add vite-plugin-pagefiles

pnpm add vite-plugin-pagefiles

Imports

pagefiles

wrong

import { pagefiles } from 'vite-plugin-pagefiles'

correct

import pagefiles from 'vite-plugin-pagefiles'

Default export – named import will cause 'undefined is not a function' error.

PagefileMetaFn

wrong

import { PagefileMetaFn } from 'vite-plugin-pagefiles'

correct

import type { PagefileMetaFn } from 'vite-plugin-pagefiles'

TypeScript type – import type only if using TypeScript.

virtual:pagefiles
wrong
```
const routes = require('virtual:pagefiles')
```
correct
```
import routes from 'virtual:pagefiles'
```
Virtual module – only works with Vite's ESM handling; require() will fail.

Quickstart

Creates a React SPA with pagefiles: configure Vite plugin, define a page component with Meta export, consume generated routes with React Router.

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

export default defineConfig({
  plugins: [
    react(),
    pagefiles(),
  ],
});

// src/Home.page.tsx
export const Meta = () => ({ path: '/' });

export default function Home() {
  return <h1>Home</h1>;
}

// src/App.tsx
import React, { Suspense } from 'react';
import { BrowserRouter, useRoutes } from 'react-router-dom';
import routes from 'virtual:pagefiles';

function AppRoutes() {
  return <Suspense fallback={<div>Loading...</div>}>{useRoutes(routes)}</Suspense>;
}

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