Allow specifying arbitrary modules in routes.ts

[rossipedia]

Sharing common "base" framework configuration across multiple apps is hard.
Sharing common route configurations across multiple apps is also hard/tedious.

Let's make it better!

TL;DR: It's my belief that allowing for arbitrary module specifiers (ie: anything that can be passed to import() or be resolved via the bundler) in routes.ts, in addition to file-system paths, can open up a world of compositional and collaborative possibilities!

---

Currently, React Router framework mode is focused on files, has the following contstraints:

• {appDir}/root.tsx - special file for the root route
• {appDir}/entry.server.tsx - (optional¹) special file for the server entry
• {appDir}/entry.client.tsx - (optional¹) special file for the client entry
• Routes configured in routes.ts must reference paths on the file system

¹While these files are optional, if provided they must be these exact paths

This works for most cases, but tends to breaks down in certain scenarios:

• It's difficult to publish a package of routes that can be installed into any React Router application
• It's difficult/tedious to share a common server/client/root configuration across a suite of applications
  that must run on the same set of utilities/configuration, such as enterprise environments that have standardized
  things like authentication / observability / caching / db access / etc.

These things are technically possible to do today with things like unstable_middleware, or more complex build-time solutions
such as @jrestall's work here.

However, I feel they could be made much better. To explain how, first let's look at how you have to do this currently.

Sharing common framework configuration today

My current solution looks like this. These files are copy/pasted across multiple applications without changes:

(Shared config files)

app/routes.ts

import type { RouteConfig } from '@react-router/dev/routes';
import { flatRoutes } from '@react-router/fs-routes';
export default flatRoutes() satisfies RouteConfig;

react-router.config.ts

import { configureReactRouter } from '@docker/web-platform/build-config';
export default configureReactRouter();

app/root.tsx

import Component, { loader, Layout, ErrorBoundary } from '@docker/web-platform/root-route';
export { loader, Layout, ErrorBoundary };
export default Component;

app/entry.client.ts

import { bootstrapReactRouterClient } from '@docker/web-platform/entry.client';
bootstrapReactRouterClient();

app/entry.server.ts

import {
  createReactRouterServerHandler,
  handleError,
} from '@docker/web-platform/entry.server';
export default createReactRouterServerHandler();
export { handleError };

Also, I have a set of routes that are installed in express that handle things like OAuth/OIDC and
similar cross cutting concerns.

IMO, copy/paste-ing this kind of config is

• Tedious
• Error prone
• Hard to maintain

How to make it better

I think that changing one constraint of the routing system would allow for solving most of these pain points:

A route config entry should be able to provide an arbitrary module specifier in place of a file-system path

As a quick strawman, I'm proposing something like this:

// routes.ts
import type { RouteConfig } from '@react-router/dev/routes';
import { index, route } from '@react-router/dev/routes';

export default [
  index('routes/home.tsx'),
  route('login', module('@mycompany/shared-routes/login')),
] satisfies RouteConfig;

Important

Why module('...') instead of something like import('...') or import * as login from '...'?

Because we don't want to actually import this thing when routes.ts is executed. We're providing
a specifier to the framework compiler and it needs to know that this is going to be handled differently from
a file-system path when the app is built.

At the risk of Not Knowing What The Heck I'm Talking About™, I believe that enabling this pattern could solve most of the issues I outlined above: Collections of routes could be built and published on package registries (npmjs.com / jsr.io / Artifactory / GH Packages / etc) and simply export a set of RouteConfigEntry[] that reference module specifiers instead of file system paths.

The plumbing for resolving a route entry to a module instead of a file system path could also be re-used to implement customizing where the root route and the client/server entry modules are located. They could be supplied by an installed package instead of having to live in the applications 'appFolder'.

This could be implemented with named exports from react-router.config.ts:

export default [ ... ] as RouteConfig;
export const root: RouteConfigEntry = module('@mycompany/react-router/root');
export const clientEntry: RouteConfigEntry = module('@mycompany/react-router/entry.client');
export const serverEntry: RouteConfigEntry = module('@mycompany/react-router/entry.server');

Unanswered questions:

• I'm not entirely certain what complications this would present to the react-router typegen process. I don't think it would be too problematic, as (in my mind) we're merely adding an additional way to find a route module's contents. If the typegen step relies on typescript source code, there may be some modifications necessary to load those types from published *.d.ts definitions instead of raw *.ts source code.

[sergiodxa]

I like the proposal btw, I have always wanted to have a way to load routes from a package so we could build something like Rails Engines where you can install a package and that can give you a full app to integrate into your app, imagine react-router-cms that you install, set the routes and it just works.

---

I'm not sure what should a package exports based on this proposal.

export default [
  index('routes/home.tsx'),
  route('login', module('@mycompany/shared-routes/login')),
] satisfies RouteConfig;

module('@mycompany/shared-routes/login')

I understand this point to a route module that's exported by a package.

simply export a set of RouteConfigEntry[] that reference module specifiers instead of file system paths

But from this I understand that the package exports something similar to routes.ts and that's merged, similar to how relative helper works but instead of inside app it can be inside the package.

I think being able to import a RouteConfig from a package would be nice as it will allow to share groups of routes directly. But also being able to reference specific modules can be useful if I only want to share a few routes or I want the app developer to choose where to place them in the route tree.

---

Some other questions about this:

1. Let's say I prefix my package routes, this means that I can't use absolute routes inside the package if I render a Link? Because if I link to /admin, but the app developer prefix it with /app then my link will be broken

2. A route module right now is split in two, the server exports and the client exports, both including the isomorphic exports like the component.

Should this happen at the app level or the package level I export something like route.server.js and route.client.js and somehow RR knows what to use)?

3. Would it be possible to add extra children routes? Imagine I install thes react-router-admin package, and I want a custom /admin/something but nested inside the layout, should I be able to pass children to the route module?

If it only supports referencing routes manually it would be possible like this:

export default [
  index('routes/home.tsx'),
  route('login', module('@mycompany/shared-routes/login'), [
    // more route from my package
  ]),
] satisfies RouteConfig;

But a package exports a RouteConfig, should there be a way? Or should package allow both ways? I imagine something like this for pre-defined route configs:

import adminRoutes from "react-router-admin";

export default [
  index("routes/home.tsx"),
  ...adminRoutes
] satisfies RouteConfig;

Or if you want to define them manually:

export default [
  index("routes/home.tsx"),
  route("admin", module("react-router-admin/layout"), [
    route("users", module("react-router-admin/entity"), { id: "admin/users" }),
    route("articles", module("react-router-admin/entity"), { id: "admin/articles" }),
    route("settings", "routes/admin/settings.tsx") // custom route inside package layout
  ])
] satisfies RouteConfig;