Routes

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("example-prismic-repo", {
  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("example-prismic-repo", {
  routes: [
    { type: "homepage", path: "/" },
    { type: "page", path: "/:uid" },
    { type: "blog_post", path: "/blog/:uid" },
  ],
});

Route resolver properties

Route resolvers support the following properties.

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

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

Path keywords

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

The following keywords are available:

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.

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

Link resolver

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.