Set up a Route Resolver
Learn what the Route Resolver is and how to use it in your project.
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.
The Route Resolver can use data from parent and grandparent documents, allowing you to build complex URLs like cities.com/united-states/california/san-francisco.
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.
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',
},
]
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 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 language, 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.
To learn more about how to use the Route Resolver, see the Route Resolve API Option Technical Reference.
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/helpers package has two templating functions that accept a linkResolver parameter: asHTML() and asLink(). Provide your Link Resolver function as the second parameter:
prismicH.asHTML(text, linkResolver)
prismicH.asLink(link, linkResolver)For more information on how to use these functions, see the @prismicio/helpers Technical Reference.
Was this article helpful?
Can't find what you're looking for? Spot an error in the documentation? Get in touch with us on our Community Forum or using the feedback form above.