---
title: "Routes"
description: "Configure URLs for your Prismic pages using route resolvers."
category: "concepts"
audience: developers
lastUpdated: "2025-11-06T01:07:50.000Z"
---

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](https://prismic.io/docs/content-modeling.md#page-types)'s URLs. They are passed to the Prismic client's [`routes`](https://prismic.io/docs/technical-reference/prismicio-client/v7.md#config-options) option and are sent on every API request.

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

const client = createClient("example-prismic-repo", {
  routes: [
    // [!code highlight:1]
    { 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](https://prismic.io/docs/content-modeling.md#page-types).

```ts {3-5}
const client = createClient("example-prismic-repo", {
  routes: [
    { type: "homepage", path: "/" },
    { type: "page", path: "/:uid" },
    { type: "blog_post", path: "/blog/:uid" },
  ],
});
```

[Learn more about the `routes` client option](https://prismic.io/docs/technical-reference/prismicio-client/v7.md#config-options)

# Route resolver properties

Route resolvers support the following properties.

| Property             | Type                    | Description                                                                                                                   | Default |
| -------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------- |
| type                 | string                  | The API ID of a page type.                                                                                                    | None    |
| path                 | string                  | The resolved path of the page with optional [keywords](#path-keywords).                                                       | None    |
| resolvers (optional) | Record\<string, string> | A map of custom keywords to API IDs of the content relationships in the route's page.                                         | None    |
| uid (optional)       | string                  | A specific UID to which this route is scoped. The route is only defined for the page whose UID matches the given UID.         | None    |
| lang (optional)      | string                  | A specific language to which this route is scoped. The route is only defined for pages whose locale matches the given locale. | None    |

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

* **Next.js:**

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

  ```ts filename=prismicio.ts {11-15,19}
  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](https://prismic.io/docs/nextjs.md#define-routes)

* **Nuxt:**

  The `routes` option is automatically passed to the Prismic client via the Nuxt module.

  ```ts filename=nuxt.config.ts {6-10}
  export default defineNuxtConfig({
    modules: ["@nuxtjs/prismic"],
    prismic: {
      endpoint: "example-prismic-repo",
      clientConfig: {
        routes: [
          { type: "homepage", path: "/" },
          { type: "page", path: "/:uid" },
          { type: "blog_post", path: "/blog/:uid" },
        ],
      },
    },
  });
  ```

  [Learn how to define routes in Nuxt projects](https://prismic.io/docs/nuxt.md#define-routes)

* **SvelteKit:**

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

  ```ts filename=src/lib/prismicio.ts {13-17,21}
  import {
    createClient as baseCreateClient,
    type Route,
  } from "@prismicio/client";
  import {
    enableAutoPreviews,
    type CreateClientConfig,
  } from "@prismicio/svelte/kit";
  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({ cookies, ...config }: CreateClientConfig = {}) {
    const client = prismic.createClient(repositoryName, {
      routes,
      ...config,
    });

    enableAutoPreviews({ client, cookies });

    return client;
  }
  ```

  [Learn how to define routes in SvelteKit projects](https://prismic.io/docs/sveltekit.md#define-routes)

# 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](https://prismic.io/docs/fields/uid.md).                         |
| `:lang`  | The page's locale code (e.g. `fr-fr`).                                           |
| `:lang?` | The page's locale code (e.g. `fr-fr`) when the page is not in the master locale. |

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

```json
{
  "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](https://prismic.io/docs/fields/uid.md) of a page assigned to a page's [content relationship](https://prismic.io/docs/fields/content-relationship.md) 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.

```json {3-6}
{
  "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 page.

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

## Override a specific UID

To override a page with a specific [page type](https://prismic.io/docs/content-modeling.md#page-type) and [UID](https://prismic.io/docs/fields/uid.md), use the `uid` property.

```json {3}
{
  "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.

```json {3}
{
  "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](https://prismic.io/docs/fields/link.md) or [content relationship](https://prismic.io/docs/fields/content-relationship.md) is broken if the field's linked page 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`](https://prismic.io/docs/technical-reference/prismicio-client/v7.md#config-options) option.

```ts {3}
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](https://prismic.io/docs/technical-reference/prismicio-client/v7.md#config-options)

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

# Link resolver

> **Important**
>
> Always prefer route resolvers. Treat the link resolver as the last option to override route resolvers.

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()`](https://prismic.io/docs/technical-reference/prismicio-client/v7.md#aslink) helper and are not provided to the Prismic client.

```ts {3-7}
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](https://prismic.io/docs/fields/link.md) 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](https://prismic.io/docs/technical-reference/prismicio-client/v7.md#aslink)