Vite plugin to statically extract metadata from React component files and generate client-side route declarations.
This plugin is pre-release, and its API is not stable. Use at your own risk. If you have feedback and/or bugs along the way, feel free to open an issue.
The plugin also currently only supports React applications. If you're familiar with other UI libraries, especially Vue, I'd be happy to help write support code.
This plugin allows you to write "pagefiles". A pagefile is a file that fully define a single route in your application. Here's a very basic example:
// Home.page.tsx
export const Meta = () => ({
path: "/",
});
export default function Home() {
return (
<div>
<h1>Home</h1>
<p>Welcome to the homepage</p>
</div>
);
}
The file has two exports: Meta
and default
.
Meta
is a function that defines metadata about the route that is made
available at build-time. The only property in the object returned by this
function that matters to the plugin is path
, which is used to generate the
route declaration, but you may add additional properties to handle as you wish.
Similar to other file-based routing solutions, the default
export is used as
the page component.
File-based routing solutions are great because they eliminate a lot of boilerplate involved in adding routes to your application. However, they force you to organize your code based on your URL organization, and they tend to incur high levels of nesting. This can make it harder to maintain a complex application.
Pagefiles is an alternative to file-based routing that still satisfies the story around convenience. But by pushing the route metadata into the route's file itself, you are free to make your own decisions about how you organize your code.
The plugin is published on npm as vite-plugin-pagefiles
.
npm install -D vite-plugin-pagefiles
// vite.config.ts
import { defineConfig } from 'vite';
import pagefiles from 'vite-plugin-pagefiles'
export default defineConfig({
plugins: [
// ...
pagefiles(),
],
});
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>
);
}
By default, the plugin imports pagefiles asynchronously using React.lazy(() => ...)
to take advantage of bundle splitting. This means it's necessary to wrap
the call to useRoutes
in a Suspense
block. This behavior is customizable.
By default, the plugin uses the glob src/**/*.page.tsx
to discover pagefiles
in your project.
Here's an example pagefile:
import type { PagefileMetaFn } from "vite-plugin-pagefiles";
export const Meta: PagefileMetaFn = () => ({
path: "/",
});
export default function Home() {
return (
<div>
<h1>Home</h1>
<p>Welcome to the homepage</p>
</div>
);
}
This plugin is based on vite-plugin-pages and borrows heavily from its design. Thank you, @hannoeru and the other folks that have contributed to that project!