Registry / web-framework / vite-plugin-pagefiles

vite-plugin-pagefiles

library0.4.2jsnpmunverified

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.

web-framework

npm install vite-plugin-pagefiles

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-PAGEFI

vite-plugin-pagefiles

web-frameworkjavascriptv0.4.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

pagefiles

✓ import pagefiles from 'vite-plugin-pagefiles'

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

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

PagefileMetaFn

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

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

TypeScript type – import type only if using TypeScript.

virtual:pagefiles

✓ import routes from 'virtual:pagefiles'

✗ const routes = require('virtual:pagefiles')

Virtual module – only works with Vite's ESM handling; require() will fail.

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> ); }

Debug

Known issues

breakingVersion 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.

affects: <1.0.0

deprecatedThe 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.

affects: <=0.4.2

gotchaVirtual 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/).

affects: >=0.0.0

gotchaBy 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).

affects: >=0.0.0

Errors

Common errors & fixes

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

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; }

TypeError: pagefiles is not a function

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'.

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

Missing Suspense wrapper when using default lazy loading.

fix

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

Upgrade

Version history

0.4.2latest on npm

Audit

Dependencies

viterequiredPeer dependency – plugin is a Vite plugin and requires Vite to function.

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/awhitty/vite-plugin-pagefiles ↗

packagehttps://www.npmjs.com/package/vite-plugin-pagefiles ↗