File-based routing

[okalil]

This proposal describes a first-party API to map routes to the router through file structure patterns.

The problem

Remix's named route definitions are excellent, but they require "manually" connecting each set of routes to the router.
Besides being repetitive, this doesn't guarantee that a set of routes is actually mapped to the router. If you forget to call .map for at least one of the route leaves, they will never be accessible.
File-based routing can solve this by requiring the file structure to match the routes object structure, ensuring that a route module exists for every route leaf in the object.

Proposal

Ship a first-party remix/router/fs package as an optional, "plug-and-play" alternative to the remix/router APIs.

It should offer enhanced wrappers for createRouter and createController:

• createRouter must accept the routes object and query the file structure to match the object's format;
• createController must maintain a reference to the route for identity verification. The route used must correspond to the controller's file path.

Usage

// app/router.ts

import { createRouter } from 'remix/router/fs'

import { routes } from './routes.ts';

const router = createRouter({
  routes,
  routesDirectory: './actions',
  routesModules: import.meta.glob('./actions/**/controller.{ts,tsx}', {
    eager: true,
  }),
  middleware: [
    staticFiles('./public', { index: false }),
    logger({ format: '%method %path %status (%duration ms)' }),
    formData(),
    session(),
    auth(),
    render(),
    asyncContext(),
  ],
});

// app/actions/auth/login/controller.tsx

import { createController } from 'remix/router/fs'

// The route used must match the file path, otherwise `createRouter` throws an error
export default createController(routes.auth.login, {
  actions: {
    // ...
  }
})

Resources

• Userland implementation packages/router.

[rossipedia]

// The route used must match the file path, otherwise `createRouter` throws an error
export default createController(routes.auth.login, {
  actions: {
    // ...
  }
})

Curious where route.auth.login comes from? It seems like that might be a bit of a chicken-and-egg problem as we're already in the "define a route" phase by authoring the route module. Having to duplicate that in the route module itself feels like an arbitrary and somewhat unnecessary restriction. For me at least, I turn to filesystem based routing because I don't want to have to duplicate the URL source of truth in multiple places, nor have to introduce the cognitive overhead of an additional naming layer for my routes.

Note

Remix v1 also had file routing conventions based around nested folders, but decided to go with a flat file/folder approach for v2 due to the tedium of navigating large folder structures in non-trivial apps.

My own personal opinion is that I'm not so sure this should be a first-party solution. I think any filesystem-based approach should live in user-space, allowing consumers to choose their routing conventions as fits their preference/team/project.

[okalil]

We still need the route reference in createController(...) to enable type-inference for the controller actions. That was the easiest way to implement in the userland, but the framework could also provide some form of type generation based on routes.ts (like in React Router framework), then this wouldn't actually be necessary.

As for the filesystem convention, Remix already offers something along those lines. For instance, the Remix CLI already expects controller.tsx files and folder structure for actions that mirrors the routes object shape. The real addition here is making the route mapping more automatic, rather than linking every route leaf with router.map.

[sergiodxa]

How do you use the routes object to define controllers, if you use the controller file to define the routes objects?

[okalil]

I don't use the controller file to define the routes object. Both createRouter and createController use routes.ts, which in turn has no dependencies.

[brophdawg11]

My own personal opinion is that I'm not so sure this should be a first-party solution. I think any filesystem-based approach should live in user-space, allowing consumers to choose their routing conventions as fits their preference/team/project.

100% agree. We went down this road in Remix v1, v2, and RR v7 and no matter what you do, some large portions of users are unhappy because file naming/nesting conventions are incredibly subjective. We landed back on routes.ts so (1) users can do whatever they want from a convention standpoint, and (2) it avoids all the "magic" of trying to express things like dynamic parameters, optionality, etc. in filenames.

I personally like the flat routes convention from RR so I would love to see a community package for that, but I don't think we're likely to venture back into filename-based-routing solutions in the core package.