Version: next

Dynamic Routing

Since version 3.5

This guide explains how you can create dynamic routes for url rewrites in Front-Commerce.

What is dynamic routing?

Dynamic routes are generated based on the data available in your application, allowing for more meaningful and SEO-friendly URLs. For example, instead of a generic URL such as /product/sku-6, you can have a more descriptive URL like /acme-product.html.

Consider a Remix route for your products defined as routes/product.$id.tsx. By leveraging dynamic routes, you can replace generic product URLs with SEO-friendly alternatives.

Generic Route Example

URL: /product/sku-6

SEO-Friendly Route Example

URL: /acme-product.html

By implementing dynamic routes, you enhance the readability and search engine optimization (SEO) of your URLs, which can improve your site's visibility and user experience.

How to create dynamic routes?

Create a `DynamicRouteUrlMatcher`

First, define a class that implements the DynamicRouteUrlMatcher interface to match URLs to your application's routes.

extension/UrlMatcher.ts
import type {
  DynamicRouteUrlMatcher,
  MatchedDynamicRouteUrl,
} from "@front-commerce/core";

// Define hardcoded routes for demonstration purposes
const hardcodedRoutes = [
  {
    type: "product",
    path: "/acme-product.html",
    identifier: "sku-6",
  },
  {
    type: "product",
    path: "/baz-product.html",
    redirectTo: "/acme-product.html",
    redirectType: 301,
  },
];

export default class UrlMatcher implements DynamicRouteUrlMatcher {
  matchUrl(path: string): MatchedDynamicRouteUrl | undefined {
    // Find a matching route in the hardcoded list, ideally this will be from a remote resource
    const match = hardcodedRoutes.find((route) => route.path === path);
    if (!match) {
      return undefined;
    }
    return {
      type: "product",
      path: match.path,
      identifier: match.identifier,
      params: {
        id: match.identifier, // The product ID to pass to the route
      },
    };
  }
}

This class checks if a provided URL matches any of the predefined paths and returns the corresponding route details.

Register a `DynamicRouteUrlMatcher`

Next, integrate the UrlMatcher into your application by registering it with the DynamicRoutes registry.

extension/index.ts
import { defineExtension } from "@front-commerce/core";
import UrlMatcher from "./UrlMatcher";

export default defineExtension({
  name: "acme-extension",
  meta: import.meta,
  unstable_lifecycleHooks: {
    onServerServicesInit: async (services, request, config) => {
      services.DynamicRoutes.registerUrlMatcher(
        "AcmeUrlMatcher",
        () => new UrlMatcher()
      );
    },
  },
});

This configuration ensures that your UrlMatcher is included in the server's initialization process, making it active for incoming requests.

Add `handle` export to Remix route

Update your Remix route to use the dynamic route identifier by adding it to the handle export.

routes/product.$id.tsx
import { createHandle } from "@front-commerce/remix/handle";

export const handle = createHandle({
  dynamicRoute: {
    type: "product", // to match the type of your url matcher
    priority: 1, // higher priority routes are matched first
  },
});

If you have multiple pages that use the same type for their dynamic routes, you can use the priority field to determine the order in which they are matched. Higher priority routes are matched first. for example the following routes/acme-product.$id.tsx will be matched before routes/product.$id.tsx:

routes/acme-product.$id.tsx
import { createHandle } from "@front-commerce/remix/handle";

export const handle = createHandle({
  dynamicRoute: {
    type: "product",
    priority: 2,
  },
});

Replace `useLoaderData` with `useDynamicRouteLoaderData`

Finally, replace the useLoaderData hook with the useDynamicRouteLoaderData which provides the dynamic route data.

routes/product.$id.tsx
import { useLoaderData } from "@front-commerce/remix/react";
import { useDynamicRouteLoaderData } from "@front-commerce/remix/react";
import { createHandle } from "@front-commerce/remix/handle";

export const loader = () => {...}

export const handle = createHandle(...);

export default function Product() {
  const data = useLoaderData<typeof loader>();
  const data = useDynamicRouteLoaderData<typeof loader>();

  return <div>Product: {data.product.name}</div>;
}

Visiting the Dynamic Route

When you navigate to /acme-product.html, the system uses your UrlMatcher to resolve the URL to the product page corresponding to sku-6. This approach allows you to manage URLs dynamically based on your application's data requirements.

Batching and Prioritizing URL Matchers

When multiple URL matchers are registered without any matcherOptions, it will default the batchOrder and priority to 0. This means that the order in which the URL matchers are registered will determine the order in which they are executed.

Let's say we have the following list of URL Matchers:

A → fast API (cached)
B → no API (static)
C → slow API (not cached)
D → no API (static)

We would ideally want this to first try to run B and D then A and finally C. To achieve this we can set the batchOrder and priority fields in the matcherOptions object.

extension/index.ts
services.DynamicRoutes.registerUrlMatcher("A", () => new UrlMatcherA(), {
  batchOrder: 1,
  priority: 1,
});

services.DynamicRoutes.registerUrlMatcher("B", () => new UrlMatcherB(), {
  batchOrder: 0,
  priority: 2,
});

services.DynamicRoutes.registerUrlMatcher("C", () => new UrlMatcherC(), {
  batchOrder: 2, // only run if no other batches have matched
  priority: 1,
});

services.DynamicRoutes.registerUrlMatcher("D", () => new UrlMatcherD(), {
  batchOrder: 0,
  priority: 1,
});

This would result in the following order of execution:

# batch 0
D → no API (static)
B → no API (static)

  # batch 1
  A → fast API (cached)

     # batch 2 (only run if no other batches have matched)
     C → slow API (not cached)

Extending the type declarations

For TypeScript support of the type field in your handle export, you can extend the DynamicRoutesCompositionList interface from the @front-commerce/types package to include your custom types.

Install the `@front-commerce/types` package

Ensure you have the @front-commerce/types package installed in your project, as it provides the necessary types for the DynamicRoutes.

$ pnpm add @front-commerce/types

Create declaration file

This declaration can be placed in a dynamic-routes.d.ts file within your extension's types directory.

extension/types/dynamic-routes.d.ts
declare module "@front-commerce/types" {
  export interface DynamicRoutesCompositionList {
    contentful: "contentful"; // example of another type
  }
}

Existing types can be found in the theme-chocolatine package.

note

TypeScript will merge all the found module declarations, so you can add your own without redefining the whole module.

Ensure your declaration is included in the tsconfig.json

This declaration can be placed in a dynamic-routes.d.ts file within your extension's types directory.

tsconfig.json
{
  "include": [
    "./**/*.jsx",
    "./**/*.js",
    "./**/*.ts",
    "./**/*.tsx",
    "./extensions/**/types/*.d.ts"
  ]
}

Verify your handle export

routes/contentful.$id.tsx
import { createHandle } from "@front-commerce/remix/handle";

export const handle = createHandle({
  dynamicRoute: {
    type: "contentful", // this should now autocomplete in your IDE.
  },
});

Known Limitations

Matching Catch-All Routes (Splat Routes)

In Remix, you can create a catch-all route that matches any path, for example:

URL	Matched Route
`/foo/a`	`routes/foo.$.tsx`
`/bar/a`	`routes/bar.$.tsx`

However, it's not possible to create a URL Matcher for catch-all routes because the URL will still be matched by Remix. Attempting to match /example to routes/foo.$.tsx using a URL matcher will result in the following error:

Error: Route "routes/foo.$" does not match URL "/example"

Dynamic Route Catch-All Placeholder

To implement CSR for dynamic routes, the application requires specific internal logic in the routes/_main.$.tsx file.

If you have overwritten this route, you will need to manually apply and maintain this logic to ensure proper functionality.

`useMatches()` returns different data in SSR and CSR

When using Remix's useMatches() hook on dynamic routes, the match object differs between

SSR

and CSR navigation.

During SSR, the match corresponds to the actual aliased route (e.g., routes/product.$id.tsx), so match.data and match.handle contain the expected values directly.
During CSR, the match corresponds to the routes/_main.$.tsx catch-all placeholder. This route's clientLoader wraps the actual data into a different structure:
- match.data.loaderData contains the actual route's loader data
- match.data.dynamicRouteModule contains the actual route module (including its handle, meta, links exports)
- match.handle is undefined (the _main.$.tsx catch-all does not export a handle)

Workaround

To access data and handle properties consistently across both SSR and CSR, use optional chaining and the nullish coalescing operator to fall back to the CSR-specific path:

// Accessing loader data
const foo = match.data.foo ?? match.data.loaderData?.foo;

// Accessing handle properties (match.handle is undefined during CSR)
const bar = match.handle?.bar ?? match.data.dynamicRouteModule?.handle?.bar;

Example: reading loader data from a dynamic route

Consider a product route that returns the product name from its loader:

routes/product.$id.tsx
import { createHandle } from "@front-commerce/remix/handle";

export const handle = createHandle({
  dynamicRoute: {
    type: "product",
    priority: 1,
  },
});

export const loader = () => {
  return { product: { name: "Acme product" } };
};

export default function Product() {
  // ...
}

In a layout component, you can use useMatches() to read the product from the deepest matching route. You must account for the SSR/CSR difference:

components/Breadcrumb.tsx
import { useMatches } from "@remix-run/react";

function useCurrentProduct() {
  const matches = useMatches();
  const match = matches[matches.length - 1];

  // SSR: data is available directly on the match
  // CSR: data is wrapped, the actual loader data is in match.data.loaderData
  return match.data?.product ?? match.data?.loaderData?.product;
}

export default function Breadcrumb() {
  const product = useCurrentProduct();

  if (!product) {
    return null;
  }

  return <nav>Home / {product.name}</nav>;
}

HMR Reloads with Multiple Dynamic Route Tabs

When working in development mode with Hot Module Replacement (HMR), you might encounter issues when loading multiple dynamic routes in parallel tabs. This can cause the dynamic route manifest to become out of sync, resulting in pages not loading correctly.

Symptoms

Pages with dynamic routes stop working after HMR reloads

TypeError: Cannot read properties of undefined (reading 'module')

Solutions

You can resolve this issue by either:

Restarting your development server
Using client-side navigation to the affected pages, which will re-populate the manifest and restore functionality

Known issues

No `routeModule` available to create server routes

Internal Reference: 67201

Symptoms

In production, you might see the following error:

Error: No `routeModule` available to create server routes

Abnormal rate of 500 errors in your logs.

Cause

When a same URL is loaded in a small amount of time by the same Front-Commerce server process, a race condition occurs on the ServerBuild to be partially built to load Dynamic Routes by multiple threads.

Solution

We have implemented a new experimental way to load Dynamic Routes in memory to prevent the race condition, you can apply this patch by following the dedicated Merge Request patch.

This MR implements the use of a feature flag to enable the in-memory dynamic route matcher. However, when applying this patch to your project, we recommend you to replace the feature flag by a process.env.FRONT_COMMERCE_DYNAMIC_ROUTES_IN_MEMORY environment variable to enable it.

This way, you'll be able to enable and disable it quickly on your project without the need of a rebuild.

What is dynamic routing?​

Generic Route Example​

SEO-Friendly Route Example​

How to create dynamic routes?​

Batching and Prioritizing URL Matchers​

Extending the type declarations​

Known Limitations​

Matching Catch-All Routes (Splat Routes)​

Dynamic Route Catch-All Placeholder​

useMatches() returns different data in SSR and CSR​

Workaround​

Example: reading loader data from a dynamic route​

HMR Reloads with Multiple Dynamic Route Tabs​

Symptoms​

Solutions​

Known issues​

No routeModule available to create server routes​

Symptoms​

Cause​

Solution​

What is dynamic routing?

Generic Route Example

SEO-Friendly Route Example

How to create dynamic routes?

Batching and Prioritizing URL Matchers

Extending the type declarations

Known Limitations

Matching Catch-All Routes (Splat Routes)

Dynamic Route Catch-All Placeholder

`useMatches()` returns different data in SSR and CSR

Workaround

Example: reading loader data from a dynamic route

HMR Reloads with Multiple Dynamic Route Tabs

Symptoms

Solutions

Known issues

No `routeModule` available to create server routes

Symptoms

Cause

Solution