Route Resolver

Prismic generates URLs for your web pages using the route resolver.

The route resolver is an option that you can include when initializing an API client or sending an API request. It describes how Prismic should generate URLs for each document in your repository. These URLs are then included for each document and each internal link in your repository in the API response. If no route resolver is specified, the url property will be null.

The route resolver can use data from parent and grandparent documents, allowing you to build complex URLs like boutique.com/clothing/tops/red-blouse.

Setup

The route resolver’s implementation varies by framework. In some cases, you can include it in your project configuration file. In others, you include it in your client instantiation. For more information, see the documentation for your framework.

In all cases, the route resolver is an array of route objects. Each route object can include the following properties:

• A path property to describe the URL
• Conditions like lang and type to describe what documents to apply to
• A resolvers property to describe content relationships that you want to use in the URL

Let’s break that down with an example.

Example

In this example, we have an international clothing boutique. The following route resolver array will describe the routes for a homepage and some product pages:

[
  {
    type: "page",
    uid: "homepage",
    lang: "en-us",
    path: "/",
  },
  {
    type: "page",
    uid: "accueil",
    lang: "fr-fr",
    path: "/accueil",
  },
  {
    type: "product",
    resolvers: {
      category: "category",
    },
    path: "/:lang/:category/:uid",
  },
  {
    type: "product",
    resolvers: {
      category: "category",
      section: "category.section",
    },
    path: "/:lang/:section/:category/:uid",
  },
];

The first route object says that if the document is a page with the UID homepage and the locale en-us, then return the root route, /.

The second route object says that if the document is a page with the UID accueil and the locale fr-fr, then return the route /accueil.

The third route object describes the route for a product document. It defines the category resolver, so the URL can access the UID of the category content relationship. Then the route resolver constructs a URL using the locale, the category, and the document’s UID. So, for example, the document for a red dress might have the route /en-us/women/red-dress, while the French translation of that document might be /fr-fr/femmes/robe-rouge.

The fourth route object describes the route for a product document. It defines the section and category resolvers, so the URL can access the section (from a grandparent document), the category (from a parent document), and the UID. Then the route resolver constructs a URL using the locale, the section, the category, and the document’s UID. So, for example, the document for a red blouse with a parent category of tops and the parent category’s section of clothing, might have the route /en-us/clothing/tops/red-blouse, while the French translation of that document might be /fr-fr/vetements/chemises/chemisier-rouge.

API configuration

The route resolver is an API Option. To use it in an HTTP request, remove whitespace, encode the value, and, append it to the HTTP URL as described in the Document API Technical Reference.

To use the route resolver with one of our development kits, like JavaScript, React, or Vue, see the documentation for your framework.

Only the path property is required; all others are optional.

type

The API ID for a specific custom type.

uid

Either the UID for a specific document or * for any document.

lang

Either a specific locale code or * for any locale.

resolvers

The resolvers property is an object that defines parent and grandparent relationships that can be used as variables in the path property. Resolvers can access parent and grandparent properties. Resolvers cannot access great-grandparents or further.

path

A pattern for constructing each Route. The following variables are available:

Link resolver

The route resolver may fail to address advanced use-cases, like advanced conditions or URL formatting. In those cases, we provide a workaround called a link resolver. The link resolver is a user-defined function. It runs client-side. It accepts a document object and returns the route for that document as a string.

An example of a link resolver that uses a document’s first_publication_date property might look like this:

function linkResolver(doc) {
  if (doc.type === "blog_post") {
    const date = new Date(doc.first_publication_date);
    return `/${date.getFullYear()}/${doc.uid}`;
  }
  return null;
}

If your project includes both a link resolver and a route resolver, the link resolver will take priority. Where the link resolver returns null, the route resolver will be used.

The @prismicio/client package has two templating functions that accept a linkResolver parameter: asHTML() and asLink(). Provide your link resolver function as the second parameter:

prismic.asHTML(text, { linkResolver })
prismic.asLink(link, { linkResolver })

For more information on how to use these functions, see the @prismicio/client Technical Reference.