{"id":22771,"library":"vite-plugin-pagefiles","title":"Vite Plugin Pagefiles","description":"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.","status":"active","version":"0.4.2","language":"javascript","source_language":"en","source_url":"https://github.com/awhitty/vite-plugin-pagefiles","tags":["javascript","vite","react","pagefiles","typescript"],"install":[{"cmd":"npm install vite-plugin-pagefiles","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-pagefiles","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-pagefiles","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency – plugin is a Vite plugin and requires Vite to function.","package":"vite","optional":false}],"imports":[{"note":"Default export – named import will cause 'undefined is not a function' error.","wrong":"import { pagefiles } from 'vite-plugin-pagefiles'","symbol":"pagefiles","correct":"import pagefiles from 'vite-plugin-pagefiles'"},{"note":"TypeScript type – import type only if using TypeScript.","wrong":"import { PagefileMetaFn } from 'vite-plugin-pagefiles'","symbol":"PagefileMetaFn","correct":"import type { PagefileMetaFn } from 'vite-plugin-pagefiles'"},{"note":"Virtual module – only works with Vite's ESM handling; require() will fail.","wrong":"const routes = require('virtual:pagefiles')","symbol":"virtual:pagefiles","correct":"import routes from 'virtual:pagefiles'"}],"quickstart":{"code":"// vite.config.ts\nimport { defineConfig } from 'vite';\nimport react from '@vitejs/plugin-react';\nimport pagefiles from 'vite-plugin-pagefiles';\n\nexport default defineConfig({\n  plugins: [\n    react(),\n    pagefiles(),\n  ],\n});\n\n// src/Home.page.tsx\nexport const Meta = () => ({ path: '/' });\n\nexport default function Home() {\n  return <h1>Home</h1>;\n}\n\n// src/App.tsx\nimport React, { Suspense } from 'react';\nimport { BrowserRouter, useRoutes } from 'react-router-dom';\nimport routes from 'virtual:pagefiles';\n\nfunction AppRoutes() {\n  return <Suspense fallback={<div>Loading...</div>}>{useRoutes(routes)}</Suspense>;\n}\n\nexport default function App() {\n  return (\n    <BrowserRouter>\n      <AppRoutes />\n    </BrowserRouter>\n  );\n}","lang":"typescript","description":"Creates a React SPA with pagefiles: configure Vite plugin, define a page component with Meta export, consume generated routes with React Router."},"warnings":[{"fix":"Pin to exact version and expect manual migration with each update.","message":"Version 0.x is experimental and API changes will not follow semver. Major refactors may occur in minor releases.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Use other frameworks (e.g., Next.js) if React is not your choice, or consider contributing support.","message":"The plugin only supports React as of v0.4.2. Vue support is not yet available.","severity":"deprecated","affected_versions":"<=0.4.2"},{"fix":"Only import 'virtual:pagefiles' within files processed by Vite (e.g., inside src/).","message":"Virtual module 'virtual:pagefiles' is not a real file; importing outside Vite's transform pipeline will fail.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Add <Suspense fallback={...}> around the component using useRoutes(routes).","message":"By default, pagefiles are loaded lazily via React.lazy(). You must wrap useRoutes in a Suspense component to handle loading states.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"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; }","cause":"Missing TypeScript declaration for the virtual module.","error":"Cannot find module 'virtual:pagefiles' or its corresponding type declarations."},{"fix":"Change import { pagefiles } from 'vite-plugin-pagefiles' to import pagefiles from 'vite-plugin-pagefiles'.","cause":"Using named import instead of default import for the plugin.","error":"TypeError: pagefiles is not a function"},{"fix":"Wrap the component that calls useRoutes(routes) in <Suspense fallback={<div>Loading...</div>}>.","cause":"Missing Suspense wrapper when using default lazy loading.","error":"Warning: React.lazy(...) requires a Suspense boundary."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}