Define Routes

In this article, you’ll learn how to create routes for content queried from the Prismic API.

Most websites have multiple pages, especially those using a content management system. To support multiple pages, a website needs to define how pages and their URLs are generated. Website frameworks like Nuxt define this using routes. A route pairs a page with its URL.

To tell Prismic which URLs in your app are associated to documents, configure your app to use a route resolver. The route resolver is a collection of rules that, when sent along with your Prismic API queries, will automatically resolve a document to a URL in your app.

Resolved URLs are provided in a document’s url property.

Define routes

The route resolver is configured in your Nuxt app’s nuxt.config.js file with the prismic.apiOptions.routes option.

export default {
  prismic: {
    apiOptions: {
      routes: [
        // Resolves the Homepage document to "/"
        {
          type: "homepage",
          path: "/",
        },
      ],
    },
  },
};

The above route resolver will resolve a Homepage document’s URL to /. Now, anytime the Homepage document is queried or referenced in other documents, the response will include a url property containing the correct URL.

You can define any number of routes in the route resolver.

export default {
  prismic: {
    apiOptions: {
      routes: [
        // Resolves the Homepage document to "/"
        {
          type: "homepage",
          path: "/",
        },
        // Resolves the About Page document to "/about"
        {
          type: "about_page",
          path: "/about",
        },
      ],
    },
  },
};

Use metadata in routes

The route resolver lets you define paths containing metadata from the document it is resolving. For example, you could have a Page document that uses its UID field to define its URL, like /about or /blog. Such a route resolver would look like this:

export default {
  prismic: {
    apiOptions: {
      routes: [
        // Resolves Page documents to URLs like "/about" and "/blog"
        {
          type: "page",
          path: "/:uid",
        },
      ],
    },
  },
};

To create pages for Page documents that match this route resolver, create a file at ~/pages/_uid.vue. Learn more about fetching data for this route in the Fetch Data page.

Define nested routes

The route resolver lets you define nested routes. In the following example, a Page document’s URL will be composed using its metadata and the UIDs from its content relationship fields.

export default {
  prismic: {
    apiOptions: {
      routes: [
        {
          type: "page",
          path: "/:section/:category/:uid",
          resolvers: {
            // A list of "path variables" mapped to the API ID
            // of a content relationship field in the page type
            category: "category",
            section: "category.section",
          },
        },
      ],
    },
  },
};

This route resolver might create a URL path like /animals/fish/tuna.

To create pages for Page documents that match this route resolver, create a file at ~/pages/_section/_category/_uid.vue. Learn more about fetching data for this route on the Fetch Data page.

Static-site generation

By default, Nuxt automatically knows which pages to generate when using Static-site Generation (SSG)—no extra configuration is needed. It does this using a “crawler” that navigates through each of your app’s pages while looking for any internal links. If the crawler finds a link to an internal URL, it will generate an accompanying static page and continue looking through that page for more internal links.

Pages that are not linked from any other page in your app will not be detected by the crawler. If you need to generate unlinked pages, give Nuxt a list of their routes using the generate.routes option in nuxt.config.js.

The following example creates pages for all Page documents, including those that are not linked from anywhere in the app.

import Prismic from "@prismicio/client";

import nuxtConfig from "@/nuxt.config.js";
import sm from "@/slicemachine.config.json";

export default {
  generate: {
    routes: async () => {
      const client = Prismic.client(sm.repositoryName, {
        routes: nuxtConfig.prismic.apiOptions.routes,
      });
      const pages = await client.query(
        Prismic.Predicates.at("document.type", "page"),
      );

      return pages.results.map((page) => page.url);
    },
  },
};