vite-plugin-remix-routes

Use Remix routing in your Vite project.

Plugin config

1import { defineConfig } from "vite";
2import react from "@vitejs/plugin-react";
3import remixRoutes from "vite-plugin-remix-routes";
4
5export default defineConfig({
6  plugins: [react(), remixRoutes()],
7});

With options:

1remixRoutes({
2  /* options here */
3});

Options

appDirectory

https://remix.run/docs/en/v1/api/conventions#appdirectory

• Optional
• Type: string
• Default: path.join(process.cwd(), "app")

An absolute path to the folder containing the routes folder.

dataRouterCompatible

• Optional
• Type: boolean
• Default: true

Set this to false if you're not using a router compatible with the data APIs released in react-router 6.4.
https://reactrouter.com/en/main/routers/picking-a-router#using-v64-data-apis

importMode

NOTE: This option only works if dataRouterCompatible is set to false.

• Optional
• Type: (route: Route) => "async" | "sync"
• Default: () => "sync"

A function that receives a Route to determine if the route's component should be imported synchronously or asynchronously.

is404Route

NOTE: This option only works if dataRouterCompatible is set to false. You should use an ErrorBoundary component instead.

• Optional
• Type: (route: Route) => boolean
• Default: (route) => route.id.endsWith("/404")

A function that receives a Route to determine if it should be a 404 route. (path="*")

By default this matches all routes whose id's end with /404.

A route's id is the component path without extension.

routes

https://remix.run/docs/en/v1/api/conventions#routes

• Optional
• Type: (defineRoutes: DefineRoutesFunction) => Promise<ReturnType<DefineRoutesFunction>>

A function for defining custom routes, in addition to those already defined using the filesystem convention in app/routes. Both sets of routes will be merged.

ignoredRouteFiles

• Optional
• Type: string[]

https://remix.run/docs/en/v1/api/conventions#ignoredroutefiles

This is an array of globs (via minimatch) that Remix will match to files while reading your app/routes directory. If a file matches, it will be ignored rather that treated like a route module. This is useful for ignoring dotfiles (like .DS_Store files) or CSS/test files you wish to colocate.

Usage

1import remixRoutes from "virtual:remix-routes";

Example

1import { render } from "react-dom";
2import { createBrowserRouter, RouterProvider } from "react-router-dom";
3import remixRoutes from "virtual:remix-routes";
4
5// Note: This example only works with react-router >= 6.4
6const router = createBrowserRouter([
7  {
8    path: "/",
9    children: remixRoutes,
10    // You can add your own `element`, `errorElement`, `loader`, ...
11  },
12]);
13
14render(
15  <RouterProvider router={router}>
16    <App />
17  </RouterProvider>,
18  document.querySelector("#app")
19);

Example (dataRouterCompatible = false):

1import { render } from "react-dom";
2import { BrowserRouter, useRoutes } from "react-router-dom";
3import remixRoutes from "virtual:remix-routes";
4
5function App() {
6  const element = useRoutes(remixRoutes);
7
8  return <>{element}</>;
9}
10
11render(
12  <BrowserRouter>
13    <App />
14  </BrowserRouter>,
15  document.querySelector("#app")
16);

Async nested routes

When you configure routes to be imported asynchronously with the importMode option, it is important to note that this can create a request waterfall.

Lets say we land on the nested route /one/two/three.

React will first render (and load) the component for one, then two and at last three in series.
Each component needs to be loaded and rendered before the next one is loaded.

This is not ideal so you can use the EagerLoader component exported by vite-plugin-remix-routes/client to immediately load all the components that will be needed for the current route.

Example:

1import { render } from "react-dom";
2import { BrowserRouter, useRoutes } from "react-router-dom";
3import { EagerLoader } from "vite-plugin-remix-routes/client";
4import routes from "virtual:remix-routes";
5
6function App() {
7  const element = useRoutes(routes);
8
9  return (
10    <>
11      <EagerLoader routes={routes} />
12      {element}
13    </>
14  );
15}
16
17render(
18  <BrowserRouter>
19    <App />
20  </BrowserRouter>,
21  document.querySelector("#app")
22);

Note that if you don't render an <Outlet /> in one of the parent components, this will still load the subcomponent(s), even though React will not render it and would not have loaded it.
But in that case, you probably don't want a nested route anyway.

How does this work?

This is the code for EagerLoader. It gets the current location with the useLocation hook and gets all the matching routes for that location with matchRoutes. Then we loop over each of the matching routes and call it's loader method.

This loader method is added to async routes by vite-plugin-remix-routes and looks like this: loader: () => import("./path/to/route/component").

This will start the download of the route component. When React tries to render it later on, it is already loaded or it reuses the pending request if it hasn't finished yet.

More info about useRoutes can be found here:

• https://reactrouter.com/docs/en/v6/api#useroutes
• https://reactrouter.com/docs/en/v6/examples/route-objects

TypeScript

If you use TypeScript you can add the following to your vite-env.d.ts file.
This will add types for the virtual:remix-routes module.

1/// <reference types="vite-plugin-remix-routes/virtual" />

Similar projects

vite-plugin-pages

This project is inspired by vite-plugin-pages that can be used with both Vue and React.

vite-plugin-remix-routes is different in that it utilizes remix to generate the routes array instead of using a custom convention.
As the name suggests, it also only works with React.

License

MIT