Improved how routes are defined with code

[sergiodxa]

Proposal

Improve the way routes are defined using code instead of a file convention.

Background

Many people has issues with Remix's file convention since v2, but the reality is that there's always going to be someone who doesn't like the default conventions.

And while Remix has always allowed apps to customize the routes completely, it's not that clear and simple to do so.

Use Case

• Use code to define the routes instead of a file convention
• Enable more advanced routing features

API/Examples

My proposal is to do something similar to what Rails config/routes.rb file does, here's an example:

Rails.application.routes.draw do
  mount LetterOpenerWeb::Engine, at: "debug/email"

  namespace :admin do
    root to: redirect("/admin/users")

    resources :users
    resources :posts
  end

  draw(:cms)

  root to: "home#index"

  resources :users, only: [:index, :show] do
    resources :posts, only: [:index, :show]
  end

  resource :posts, only: [:show, :update, :destroy]
end

Let's define what's happening here.

mount LetterOpenerWeb::Engine, at: "debug/email"

This line is loading at a certain route another application, in this case it comes from a package.

namespace :admin do
  root to: redirect("/admin/users")

  resources :users
  resources :posts
end

This one, is creating a namespace (which adds an URL segment) and defining a root route, and two resources routes.

root to: redirect("/admin/users")

This one defines that the root (/) of the namespace will redirect to /admin/users

resources :users
resources :posts

These two define a resource (route), this defines /admin/users and /admin/posts, and all the CRUD routes for them, so

• GET /admin/users => UsersController#index
• GET /admin/users/new => UsersController#new
• POST /admin/users => UsersController#create
• GET /admin/users/:id => UsersController#show
• GET /admin/users/:id/edit => UsersController#edit
• PATCH /admin/users/:id => UsersController#update
• PUT /admin/users/:id => UsersController#update
• DELETE /admin/users/:id => UsersController#destroy

Each different CRUD goes to the same controller on different methods.

draw(:cms)

This is drawing (loading) routes from another file, is similar to mount but for local routes, it's useful to split large routes.rb files.

Finally this;

root to: "home#index"

resources :users, only: [:index, :show] do
  resources :posts, only: [:index, :show]
end

resource :posts, only: [:show, :update, :destroy]

Is similar to the ones inside the admin namespace, a resource can be nested inside another resource so here we have /users, /users/posts and /posts/:id, the only option is used to limit what actions are defined. And the root to: "home#index" is making / uses the HomeController#index.

---

I think Remix can adopt a similar approach, adapted to what Remix already supports and it's features.

import { defineRoutes } from "remix";
import remixEmailRoutes from "remix-email/routes";

import cmsRoutes from "./cms/routes";

export default defineRoutes(async ({ scope, route, extend }) => {
  // Load routes from another package
  await extend(remixEmailRoutes);

  // Load routes from another file
  await extend(cmsRoutes);

  // Define a namespace
  scope("admin", ({ route }) => {
    // Define a redirect
    route("/", { to: "/admin/users" });
    route("users");
    route("users/:userId");
    route("posts");
    route("posts/:postId");
  });

  // Define an index route
  route("/", "home");

  // Define a route
  route("users");

  // Define a route with parameters
  route("posts/:postId");

  // Define a parent route
  route("users/:userId", ({ route }) => {
    // Define a nested route
    route("posts");
  });
});

In Remix case, there's no concept of resources like Rails, instead it focus on routes, so we can have a route function here. Since namespace is used in TS, we can use scope instead, and draw can be replaced by extend.

File Convention

Like Remix, Rails has a file convention that the routes.rb uses to know where to look up for the controller, so when we do resources :users it goes to app/controllers/users_controller.rb, and if we define that resource inside the admin namespace it will goes to app/controllers/admin/users_controller.rb.

The same way, Remix could keep a simpler convention on how to find the route file, for example, the route("users") can try to find the file on app/routes/users.tsx or app/routes/users.ts (and JSX or JS). Similarly a route can be a folder with a route.tsx file inside, for example app/routes/users/route.tsx.

For the scope("admin"), the routes defined inside can be defined on app/routes/admin/users.tsx or app/routes/admin/users/route.tsx

For parameterized routes, like route("posts/:postId"), the file can be app/routes/posts.$postId.tsx or app/routes/posts.$postId/route.tsx.

This means scope use folders, and / uses . to replace the / on the file name.

Customizing the Route File

If the app wants to organize files in another way, or maybe the reuse a file in two routes, the route function could accept and optional second argument with the file path, for example.

route("users", "routes/users._index");

This would look for app/routes/users._index.tsx instead of app/routes/users.tsx, but still define /users as the route.

Also note that the file extension is omited, so Remix should look up for the file using the extensions it supports in the order tsx, ts, jsx, or js.

Nested Routes

One of the main features of Remix is nested routes, here a route can have children routes, for example:

route("users/:userId", ({ route }) => {
  route("posts");
});

In this case, the first route will look up for app/routes/users.$userId.tsx and the nested route will look up for app/routes/users.$userId/posts.tsx.

The / in the route path is replaced with . in the file name, but the nested route uses /.

Nested Routes with Custom Files

The route function second argument can be either a string with the file path, or a callback for the children routes, if you want to do both, the callback could become a third argument.

route("users/:userId", "routes/users/$userId", ({ route }) => {
  route("posts");
});

Here the first route has a custom file on app/routes/users/$userId.tsx but the nested route will use the default app/routes/users.$userId/posts.tsx.

Route Constraints (#7111)

If the Route Constraints proposal is also accepted, this can be used to define those constraints right here, for example:

route(":articleId", {
  file: "routes/$articleId",
  constraints: { articleId: /\d.+/ },
});
route(":username", "routes/$username");

The second argument of route can be either a string for a file path, a function for nested routes, or an object with options for more advanced features, in this case the file becomes an option and there's a constraints option too.

Here we define a constraint on the first route that articleId must be a number, and on the second route we don't define any constraints. This way a like /123 will match the first route, but /abc will match the second one.

Multi Tenancy

Right now, building a multi tenant app in Remix would mean you either have many if in your loader, action and component, or you have two separate Remix apps, one for the tenants and another for the app itself. Eg. one app handling company.com with landings, blog, payments, etc. and another one for tenant.company.com which has the app the tenants use.

Using constraints it's possible to define a scope that will be used as a subdomain, for example:

// this will now handle `sub.domain.tld` making `sub` be the `:tenant` value
scope(
  ":tenant",
  // here we set the file but also the subdomain constraint
  { file: "routes/$tenant", constraints: { subdomain: "tenant" } },
  (route) => {
    // routes defined here will only work when there's a subdomain
    route("/");
    route("posts/:postId", "routes/tenant/posts.$postId");
  },
);

This can be useful to create multi tenant apps, where a group of routes will only work if the app has a subdomain, other routes will be ignored when the app has no subdomain.

Custom Routes Folder

The default folder for routes is still app/routes, but it can be changed using the scope function, for example we could move our admin routes somewhere else like this:

scope("admin", { base: "admin" }, ({ route }) => {
  route("/", "routes/home");
  route("users");
  route("posts");
});

This base option defines the folder inside app, in this case the value admin will point to app/admin. Then any route inside this scope will look for files inside app/admin instead of app/routes, this way we can have multiple route folders when organizing our code.

Another thing is that because this is a scope it stills adds /admin, but because we changed the base, routes inside will not need to go to app/admin/admin/users.tsx but app/admin/users.tsx directly.

Custom Folder without URL Segments

If we want to set a custom folder for a group of routes, without adding a URL segment, we could use another base function.

export default defineRoutes(async ({ base }) => {
  base("admin", ({ route }) => {
    // routes here
  });
});

With this, any route defined inside the base will lookup files on app/admin but the URL will not have /admin as a prefix. This can be useful for grouping routes outside the routes folder without changing the URL, another e.g. could be to add debug routes in development.

export default defineRoutes(async ({ base }) => {
  if (process.env.NODE_ENV === "development") {
    base("debug", ({ route }) => {
      route("email");
      route("cache");
    });
  }
});

This way, in development, we can access /email and /cache to debug emails and cache, and those routes files will live in app/debug/email.tsx and app/debug/cache.tsx.

Splitting Routes

If the route file grows to be too large, it could be possible to split it into multiple files and combine them in app/routes.ts. This can be useful to group routes together, for example:

// app/tenant/routes.ts
import { defineRoutes } from "remix";

export default defineRoutes(async ({ route, scope }) => {
  // Define the :tenant param, move the base folder to app/tenant, and set it as a subdomain constraint
  scope(
    ":tenant",
    { base: "tenant", constraints: { subdomain: "tenant" } },
    ({ route }) => {
      route("/", "tenant/home");
      route("posts/:postId");
      route("users/:userId");
    },
  );
});

// app/admin/routes.ts
import { defineRoutes } from "remix";

export default defineRoutes(async ({ route, scope }) => {
  // Define the admin scope, move the base folder to app/admin
  scope("admin", { base: "admin" }, ({ route }) => {
    route("/", { to: "/admin/users" });
    route("users");
    route("posts");
  });
});

// app/debug/routes.ts
import { defineRoutes } from "remix";

export default defineRoutes(async ({ base }) => {
  base("debug", ({ route }) => {
    route("email");
    route("cache");
  });
});

// app/routes.ts
import { defineRoutes } from "remix";

import tenantRoutes from "./tenant/routes";
import adminRoutes from "./admin/routes";
import debugRoutes from "./debug/routes";

export default defineRoutes(async ({ route, extend }) => {
  if (process.env.NODE_ENV === "production") extend(debugRoutes);
  extend(tenantRoutes);
  extend(adminRoutes);

  // Overwrites /admin
  route("admin", "routes/admin/home");

  route("/", "home");

  route("users");

  route("posts/:postId");

  route("users/:userId", ({ route }) => {
    route("posts");
  });
});

The extend function receives a routes manifest (the output of defineRoutes) and can use it to extend the routes. This way we can split the routes into multiple files and combine them in the main app/routes.ts.

Additionally, routes defined below a extend call can overwrite the extended configuration. Similarly, a route defined above an extend call can be overwritten by the extended configuration. So the order here matters.

Package Routes

The same feature used to split routes, can be used by packages to provide routes, for example:

import { defineRoutes } from "remix";

import authRoutes from "remix-auth/routes";

export default defineRoutes(async ({ route, extend }) => {
  // This setup /auth/login, /auth/register, /auth/:provider and /auth/:provider/callback
  extend(authRoutes);

  route("/", "routes/home");
  route("about");
});

This remix-auth/routes could export a defineRoutes output, and can point the route files to node_modules/remix-auth/routes for example. This way developers could create an ecosystem of packages that provides routes ready to use.

Redirects & Rewrites

It could be possible to define redirects in the routes file too, for example:

export default defineRoutes(async ({ route }) => {
  route("old", { to: "new" });
});

This would redirect /old to /new.

Similarly rewrites could be defined like this:

export default defineRoutes(async ({ route }) => {
  route("old", { render: "new" });
});

Now if the user goes to /old it will see the content of /new, while the URL will still be /old.

Splat Routes

Sometimes, you want to define a route to be used when the URL doesn't match any valid route, a splat or catch-all route. This could be defined with a wildcard in the route.

route("*", "routes/not-found");

It wildcard could be applied to a subroute too.

route("parent", ({ route }) => {
  route("*", "route/parent/not-found");
});

In this case, going to /something will not match any route, but /parent/something/here will do.

It could also include a segment prefix.

route("admin/*", "routes/admin/not-found");

In this case, /admin/anything/here/not/matter/the/nesting will match the not-found route.

Following the convention, just using route("*") should lookup for the file app/routes/$.tsx.

Final API

To summarize, the final API would be something like this:

// app/tenant/routes.ts
import { defineRoutes } from "remix";

export default defineRoutes(async ({ route, scope }) => {
  // Define the :tenant param, move the base folder to app/tenant, and set it as a subdomain constraint
  scope(
    ":tenant",
    { base: "tenant", constraints: { subdomain: "tenant" } },
    ({ route }) => {
      route("/", "tenant/home");
      route("/", { to: "/admin/users" });
      route("posts/:postId");
      route("users/:userId");
    },
  );
});

// app/admin/routes.ts
import { defineRoutes } from "remix";

export default defineRoutes(async ({ route, scope }) => {
  // Define the admin scope, move the base folder to app/admin
  scope("admin", { base: "admin" }, ({ route }) => {
    route("/", { to: "/admin/users" }); // Redirect /admin to /admin/users
    route("users");
    route("posts");
  });
});

// app/debug/routes.ts
import { defineRoutes } from "remix";

export default defineRoutes(async ({ base }) => {
  // Change the routes folder to app/debug
  base("debug", ({ route }) => {
    route("email");
    route("cache");
  });
});

// app/routes.ts
import { defineRoutes } from "remix";

import authRoutes from "remix-auth/routes";

import tenantRoutes from "./tenant/routes";
import adminRoutes from "./admin/routes";
import debugRoutes from "./debug/routes";

export default defineRoutes(async ({ route, extend }) => {
  // Apply routes only in development
  if (process.env.NODE_ENV === "production") extend(debugRoutes);

  // Apply routes from other files or packages
  extend(tenantRoutes);
  extend(adminRoutes);
  extend(authRoutes);

  // Overwrites /admin
  route("admin", "routes/admin/home");

  // Define / route
  route("/", "home");

  route("users");

  route("posts/:postId");

  route("users/:userId", ({ route }) => {
    route("posts");
  });

  route("*", "routes/not-found");
});

[sergiodxa]

@pcattori since you're working on the new way to define routes, I wrote about my ideas here, hope it's useful for the team.

[pcattori]

Thanks @sergiodxa ! Our goal right now is to come up with better primitives for defining routes programmatically. We're most likely going to focus on just make sure we accomplish that with an API that will let us evolve and add features later, but probably won't add new features are part of the current chunk of work.

[kiliman]

Sounds reasonable, but it helps to think about possible routing needs to ensure the primitives will be able to cover those.

[pcattori]

Yep, for sure! Feel free to keep the ideas coming, just wanted to communicate that even if we don't land any new features now that doesn't mean we won't later.

[sneridagh]

@sergiodxa glad that some of your proposals made it to RR7 routes.rs!

FTR, I'd like to make you notice of a need that our open source CMS community (Plone) has right now, while we are planning to migrate from RR5 to full RR7 (framework) mode.

I left my proposal in here:
remix-run/react-router#11577

The summary is that in RR5 you were able to do:

  {
    path: ['/edit', '/**/edit'],
    component: Edit,
  },

We need splat routes with fixed suffixes.

We would love to share our use case and discuss about it and how to achieve the challenges that we have ahead with the Remix/RR team.

Thanks!