Link Resolver and Route Resolver

Learn what the Link Resolver and Route Resolver are, the differences between them, and how you can use them in your project.


The Link Resolver and Route Resolver are two different methods for creating internal URLs on your website. If your website has multiple pages, the resolvers will make your links work — such as for Link fields, Content Relationship fields, or links inside Rich Text fields.

The Link Resolver is a simple JavaScript function that accepts a document object as an argument and returns a relative URL as a string.

The Route Resolver is an API option. In Nuxt.js and Next.js, you can define the Route Resolver in your config. When present, the Prismic API will add a url property to each document in the API response.

Which one to use?

This will depend on your use case.

The Route Resolver runs on Prismic servers, meaning that it can get data from parent and grandparent documents, allowing you to build complex URLs like cities.com/north-america/united-states/san-francisco. Use the Route Resolver when you want to construct a route with parent or grandparent segments.

The Link Resolver runs client-side, which means that it can only work with the data received from the API. Use the Link resolver when you want to build simpler URLs, like me.com/post/hello-world or me.com/about-me.

If you include both

If you include both resolvers in your project, it will first use the Link Resolver. If the Link Resolver returns null, the Route Resolver will be used.

Link Resolver

The Link Resolver is a simple JavaScript function that receives a document object.

Create a Link Resolver

Let's examine an example document object:

Copy
{
  id: 'XoX2rhAAACEAA3Jf',
  type: 'page',
  tags: [],
  lang: 'en-us',
  uid: 'about',
  link_type: 'Document',
  isBroken: false
}

The Link Resolver will grab this doc object from the props and use a conditional statement to return the URL that corresponds to that document. The URLs will be generated using the metadata from the document object.

Look at the following example:

Copy
const linkResolver = (doc) => {
  if (doc.type === 'page') return `/${doc.lang}/${doc.uid}`
  if (doc.type === 'homepage') return `/${doc.lang}`
  return '/'
}

Here is an example use case of a Link Resolver. For the documents of the type page, it will return a URL using the lang code and uid metadata values of the document. And for the document that matches the type homepage, it will only return the lang code.

The URL that this Link Resolver would generate would be: /en-us/about.

You can pass a Link Resolver directly to the methods and components from Prismic's development kits. Here's an example in Node.js:

Copy
const PrismicDom = require('prismic-dom');
const linkResolver = 'path/to/link/resolver'

const html = PrismicDom.RichText.asHtml(document.data.title, linkResolver)

Route Resolver

The usage of your Route Resolver function depends on your chosen technology. In Nuxt.js and Next.js, the Route Resolver is an option in your config file. With other technologies, you can use the Route Resolver as an API option.

The Route Resolver allows you to build complex URLs based on Content Relationships. For each route, create an object with these three properties:

type

string (required)

The Custom Type of the document. Examples: 'page', 'home''blog_post', 'menu'.

path

string (required)

The dynamic route. Examples: '/:uid', '/:lang/:uid', '/:section/:category?/:uid'.

resolvers

object

An object that lists the API IDs of the Content Relationships in the route.

Here is an example Route Resolver that will generate a URL for documents of the type blog_post.

Copy
{
  type: 'blog_post',
  path: '/:lang/blog/:category?/:uid',
  resolvers: {
    country: 'country',
    category: 'country.category'
  }
}

Here, uid is the UID of the blog post. The lang is the locale code for the blog post. The resolvers will retrieve the UID of a linked country on the blog post, and then retrieve the UID of the linked category for that country. You can now use the country and category properties in the path. In this case, category is flagged as optional with a question mark. If there is no category, that URL segment will be omitted.

The Route Resolver can retrieve data up to the grandparent document. Example: /continent/country/city, where city is the main document.

Here we'll show you a few examples of how to use it with popular frameworks:

  • Next.js
  • Nuxt.js
  • Node.js
Copy
// Example prismic-configuration.js file 

export const Router = {
  routes: [
    {
      type: 'blog_post',
      path: '/:lang/blog/:category?/:uid',
      resolvers: {
        country: 'country',
        category: 'country.category',
      },
    },
  ],
  href: (type) => {
    const route = Router.routes.find((r) => r.type === type)
    return route && route.href
  },
}


Copy
// Example nuxt.config.js file

export default {
  modules: ['@nuxtjs/prismic'],
  prismic: {
    endpoint: 'https://my-repo-name.cdn.prismic.io/api/v2',
    apiOptions: {
      routes: [
        {
          type: 'blog_post',
          path: '/:lang/blog/:category?/:uid',
          resolvers: {
            country: 'country',
            category: 'country.category',
          },
        },
      ],
    },
  },
}
Copy
// Example index.js file 

const Prismic = require('@prismicio/client');
const apiEndpoint = 'https://your-repo-name.cdn.prismic.io/api/v2'
const Client = Prismic.client(apiEndpoint, { req })

const routes = JSON.stringify([
  {
    type: 'blog_post',
    path: '/:lang/blog/:category?/:uid',
    resolvers: {
      country: 'country',
      category: 'country.category',
    },
  },
])

const response = await Client.query('', { routes })


Templating links

To learn about how to template links with the Link Resolver and Route Resolver, see the documentation on link templating for your chosen technology.


Was this article helpful?
Not really
Yes, Thanks

Can't find what you're looking for? Get in touch with us on our Community Forum.