Version: 3.x

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
  },
];

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 {
      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.

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​