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.
type
string
resolvers
Record<string, string>
A map of custom keywords to API IDs of the content relationships in the route’s document.
uid
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
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.
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:
Keyword | Description |
---|---|
:uid | The page’s UID. |
:lang | The 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 namedparent
.:grandparent?
: Maps to a content relationship namedparent
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.
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.
Learn more about the asLink
helper