Route Segment Constraints

[sergiodxa]

Proposal

Add segment constraint support to the route definition to allow matching multiple routes in the same segment, but using constraints to decide which one to use.

Background

Right now, if two routes match the same segment Remix Router throws an error, for example, let's say we want to have the routes

• /:articleId
• /:username

At the moment, the only way to achieve this is by defining the routes as a single route.

{
  path: ":articleOrUsername"
  loader({ request, params }) {
    // check here if it's an article or a username
  },
  // this component must use the returned value to render the correct UI
  element: <ArticleOrUserPage />
}

While this works, it's not ideal because now our component has to know how to render both an article and a user, and the loader has to know how to render both too.

Use Case

• Let the same URL segment be handled by two or more routes depending on some condition.
• Extend constraints to allow more advanced features like subdomains.

API/Examples

Route Constraints interface

I propose to create a RouteConstraints interface that can be used to define constraints for a route.

interface ParamConstraintFunction {
  (param: string, args: DataFunctionArgs): Promise<boolean> | boolean;
}

interface RouteConstraints {
  params?: { [key: string]: RegExp | ParamConstraintFunction };
}

This can be added to the definition of a route in React Router or as a route module export in Remix.

React Router API

In React Router, we can add a constraints attribute to the route definition.

let routes = createBrowserRouter([
  {
    path: ":articleId",
    element: <ArticlePage />,
    loader: articlePageLoader,
    // limit articleId to only digits
    constraints: { params: { articleId: /^\d+$/ } },
  },
]);

With this, React Router can use the constraints to ensure the route match the path segment.

One route and with constraints

Following the example above, if we have a single route matching our path segment, and it has constraints, React Router check if the constraints pass.

If they pass, it will use the route, if they don't it will consider it a 404.

Multiple routes, only one with constraints

Let's say now we add a second route.

let routes = createBrowserRouter([
  {
    path: ":articleId",
    element: <ArticlePage />,
    loader: articlePageLoader,
    constraints: { params: { articleId: /^\d+$/ } },
  },
  {
    path: ":username",
    element: <UserProfile />,
    loader: userProfileLoader,
  },
]);

In this case we have one route with constraints and another one without. Here React Router will need to first check the route with constraints.

If the constraints pass, it will use that route, if they don't it will use the other route, essentially the :username route will work as a fallback for the segment, so this segment will always have a match.

Multiple routes, all with constraints

Now let's say we decide to add a constraint to our :username route.

let routes = createBrowserRouter([
  {
    path: ":articleId",
    element: <ArticlePage />,
    loader: articlePageLoader,
    constraints: { params: { articleId: /^\d+$/ } },
  },
  {
    path: ":username",
    element: <UserProfile />,
    loader: userProfileLoader,
    // starts with alpha, can contain digits and underscores
    constraints: { params: { username: /^[a-z][a-z0-9_]+$/i } },
  },
]);

Because both routes has constraints, React Router will check them all.

• If only one pass it will use that route.
• If two or more pass it will throw an error.
• If none match it will be handled as a 404.

Constraints as functions

Sometimes, the constraint will need data, let's say we want to have /whatever match a dynamically generated landing page, and if the landing page doesn't exist it should match a user profile.

Note: This example in particular is one I'm interested to support since I have this exact use-case at work.

let routes = createBrowserRouter([
  {
    path: ":slug",
    element: <LandingPage />,
    loader: landingLoader,
    constraints: {
      params: {
        // use a function to check if the constraint pass dynamically
        async slug(slug) {
          return await existsLanding(slug)
        },
      },
    },
  },
  {
    path: ":username",
    element: <UserProfile />,
    loader: userProfileLoader,
    constraints: { params: { username: /^[a-z][a-z0-9_]+$/i } },
  },
])

Here, the slug param constraint is a function that receives the param, and the loader args, and returns a boolean, or a promise that resolves to a boolean.

If the constraint is a promise, React Router will wait for it to resolve before checking the result.

The params constraint function will let the application developer do a more advanced check, e.g. checking if the record exists in the database. Since this will block route matching, it must be a fast operation, ideally a cached lookup.

In this case, since the function one can include dynamic data, it will be preferred over the RegExp-based constraint, so if the function returns true it will use the route, even if the RegExp constraint also passes.

Remix API

In Remix, this can be defined as a module export.

// routes/$articleId.tsx
export const constraints: RouteConstraints = {
  params: { articleId: /^\d+$/ },
};

// routes/$username.tsx
export const constraints: RouteConstraints = {
  params: { username: /^[a-z][a-z0-9_]+$/i },
};

// routes/$slug.tsx
export const constraints: RouteConstraints = {
  params: {
    async slug(slug, { request, params, context }) {
      return await existsLanding(slug);
    },
  },
};

Here's where accessing the request can be useful, since a Remix application could also check the user session, headers, or other parts of the URL.

Subdomain constraint

Another use case for constraints is to allow subdomains to match as params, let's say we want to have a route that matches https://:username.example.com.

This is specially useful for multi-tenant applications, where each tenant has its own subdomain. But it will require extending the router to also know how to parse the hostname.

// routes/($tenantId).tsx
export const constraints: RouteConstraints = {
  params: {
    tenantId(tenantId) {
      if (tenantId === "www") return false; // www is not a valid tenant
      return true; // any other value is valid
    },
  },
  // read the tenantId from a subdomain
  subdomain: true,
};

In this case, the router should parse the hostname and extract the subdomain, then it should use the subdomain as param value, removing it from the pathname.

Basically if there's a subdomain it will match this route and any nested route. As an example, let's say we have the following routes.

• routes/($tenantId).tsx
• routes/($tenantId)._index.tsx
• routes/($tenantId).dashboard.tsx
• routes/_index.tsx
• routes/$article.tsx

If the user visits company.tld/123 then the router will find two possible matches, on routes/$article.tsx and routes/($tenantId).tsx (including the nested index).

Here the constraint will tell the router that routes/($tenantId).tsx should only match for a subdomain, so it will discard it and use routes/$article.tsx to render the UI.

If the user visits acme.company.tld/ then the router will also find two possible matches on routes/($tenantId).tsx and routes/_index.tsx, because the $tenantId is optional.

Here the constraint will tell the router that the tenantId param comes from the subdomain (acme) and it's valid, so it will use routes/($tenantId).tsx to render the UI instead of routes/_index.tsx.

Something to consider would be what happens with nested subdomains, e.g. foo.bar.company.tld, in that case the default handling could be to use foo.bar as the tenantId, but it could also be possible to add a constraint to the nested route to tell the router to use foo as the tenantId.

// routes/($tenantId).tsx
export const constraints: RouteConstraints = {
  params: {
    // custom constraint
    async tenantId(tenantId, request) {
      return isValidTenant(tenantId);
    },
  },
  // use a custom function to manually extract the parameter from the hostname
  subdomain(request) { // also possible this receives a URL instance directly
    let url = new URL(request.url);
    let parts = url.hostname.split(".");
    return parts[0];
  }
};

Routes with a subdomain constraint must always be on the first level of routes, they can't nested inside another route that adds segments to the URL, this means this is valid:

• routes/_layout.tsx
• routes/_layout.($tenantId).tsx // _layout is a pathless layout route here

But this is not:

• routes/app.tsx
• routes/app.($tenantId).tsx

Prior Art

• Rails Segment Constraints
• Rails Request-Based Constraints
• Laravel Regular Expression Constraints
• Laravel Subdomain Routing
• Laravel Folio Subdomain Routing - They have a configuration to tell that the subdomain match a specific folder of views

[kiliman]

I think this will be doable once RR uses a tree structure to match routes. The constraints would determine which branch to follow for matching.

#4857

[mylescarrick]

This would be brilliant. After 15 years in Rails I came looking for this today – so many use cases for dynamic paths. I can hack around it for now with generic/shared params but the implementation described here would be perfect, and very similar to what the Rails all I'm porting does today.

[wingleung]

I'm bumping into more and more limitations with the current way of defining routes using file names so I love the finer grained control in this proposed solution.

Issues I'm bumping into now:

• /some/longer/route/paths/are/more/difficult/to/maintain
  • 👉 especially if you have multiple specific routes that do the same thing, while other routes have a default behaviour
• /some/paths/need/a/dynamic-segment-selector~PAGE_ID
  • 👉 paths with ~PAGE_ID needs a separate handler than the ones without ~PAGE_ID
  • ⚠️ can't be done with react-router because you cannot have partial dynamic segments