Concepts

Routes

Configure URLs for your Prismic pages using route resolvers.

Prismic generates page URLs, or routes, to match your website’s pages using route resolvers.

A route resolver is a JSON object containing rules for a page type’s URLs. They are passed to the Prismic client’s routes option and are sent on every API request.

import { createClient } from "@prismicio/client";

const client = createClient({
  routes: [
    { type: "blog_post", path: "/blog/:uid" },
  ],
});

const blogPost = await client.getByUID("blog_post", "my-first-post");

blogPost.url; // => "/blog/my-first-post"

The above example defines a route resolver for blog posts. The fetched blog post’s UID is my-first-post and its URL is /blog/my-first-post.

You can provide any number of route resolvers to the routes option. Most websites will have one route resolver per page type.

const client = createClient({
  routes: [
    { type: "homepage", path: "/" },
    { type: "page", path: "/:uid" },
    { type: "blog_post", path: "/blog/:uid" },
  ],
});

Learn more about the routes client option

Route resolver properties

Route resolvers support the following properties.

property
Description
Default
type
string
The API ID of a document type.
path
string

The resolved path of the document with optional keywords.

resolvers
optional
Record<string, string>

A map of custom keywords to API IDs of the content relationships in the route’s document.

uid
optional
string

A specific UID to which this route is scoped. The route is only defined for the document whose UID matches the given UID.

lang
optional
string

A specific language to which this route is scoped. The route is only defined for documents whose locale matches the given locale.

Define route resolvers

Route resolvers should be defined close to your Prismic client. We recommend creating a routes constant in your project’s prismicio.ts file (Next.js, SvelteKit) or global configuration (Nuxt).

The routes constant is passed to the Prismic client in the createClient() function.

prismicio.ts
import {
  createClient as baseCreateClient,
  type ClientConfig,
  type Route,
} from "@prismicio/client";
import { enableAutoPreviews } from "@prismicio/next";
import sm from "../slicemachine.config.json";

export const repositoryName = sm.repositoryName;

const routes: Route[] = [
  { type: "homepage", path: "/" },
  { type: "page", path: "/:uid" },
  { type: "blog_post", path: "/blog/:uid" },
];

export function createClient(config: ClientConfig = {}) {
  const client = baseCreateClient(repositoryName, {
    routes,
    fetchOptions:
      process.env.NODE_ENV === "production"
        ? { next: { tags: ["prismic"] }, cache: "force-cache" }
        : { next: { revalidate: 5 } },
    ...config,
  });

  enableAutoPreviews({ client });

  return client;
}

Learn how to define routes in Next.js projects

Path keywords

Keywords in the path property are replaced by dynamic values in the API.

The following keywords are available:

KeywordDescription
:uidThe page’s UID.
:langThe page’s locale code (e.g. fr-fr).
:lang?The page’s locale code (e.g. fr-fr) when the document is not in the master locale.

This example route resolver uses keywords to produce a URL like /fr-fr/blog/my-first-post:

{
  "type": "blog_post",
  "path": "/:lang?/blog/:uid"
}

Special cases

Route resolvers handle most URL patterns, but some scenarios require additional configuration. Here are common special cases and how to address them.

Parent-child nested URLs

Use the resolvers property to support multiple levels of URL nesting. It allows you to access the UID of a document assigned to a page’s content relationship field.

This type of route resolver is used in sites that allow content writers to affect page URLs. For example, using a page’s parent or blog post’s category is handled using the resolvers property.

Up to two levels of nesting is supported.

{
  "type": "page",
  "resolvers": {
    "parent": "parent",
    "grandparent": "parent.parent"
  },
  "path": "/:grandparent?/:parent?/:uid"
}

Example URL: /about-us/our-team/jane-doe

The resolvers property is an object mapping keyword names of your choosing to a field name. The above example uses these resolvers:

  • :parent?: Maps to a content relationship field named parent.
  • :grandparent?: Maps to a content relationship named parent in :parent?’s document.

The ? character makes the value optional. If a page does not have a document in its parent field, for example, the :parent? segment is excluded.

Override a specific UID

To override a page with a specific page type and UID, use the uid property.

{
  "type": "page",
  "uid": "my-special-page",
  "path": "/foo"
}

The page with the my-special-page UID now has a URL of /foo.

Modify a locale code

To modify the locale code in a URL, use the lang property to target a specific language. You can provide a path property that uses your desired locale code.

{
  "type": "page",
  "lang": "fr-fr",
  "path": "/fr/:uid"
}

The custom value, fr, takes the place of the fr-fr locale code. Note that the :lang keyword is not used in the example.

A page in the fr-fr locale with the my-page UID now resolves to /fr/my-page.

Broken routes

A link or content relationship is broken if the field’s linked document is archived or deleted. The API does not have a URL to return in this case.

You can provide an explicit URL for these cases to the Prismic client’s brokenRoutes option.

const client = createClient({
  routes: [{ type: "page", path: "/:uid" }],
  brokenRoute: "/404",
});

This example populates all broken links with /404.

Learn more about the brokenRoute client option

In rare cases, route resolvers may not handle your exact needs. You can use a link resolver in those cases.

If a complex URL cannot be defined using a route resolver, you can define the URL using a JavaScript function called a link resolver.

Link resolvers are used with the asLink() helper and are not provided to the Prismic client.

import { asLink, LinkResolverFunction } from "@prismicio/client";

const linkResolver: LinkResolverFunction = (link) => {
  if (link.uid?.startsWith("team-")) {
    return `/about-us/our-team/${link.uid}`;
  }
};

const url = asLink(page, { linkResolver });

Link resolvers receive a link field as an argument and return its resolved URL. If the resolver does not return a value, the client falls back to its route resolvers.

Learn more about the asLink helper