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.
Routing in Nuxt
Nuxt routes are defined using file and directory names in the pages directory, as we’ll explore on this page. For example, the file /pages/products/banana.vue will have the URL https://www.example-site.com/products/banana.
You can read more about how Nuxt handles routes in the Nuxt documentation.
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.
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',
},
],
},
},
}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.
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.
Further Learning
To learn more about route resolver, see the route resolver documentation.
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)
},
},
}Can't find what you're looking for?
Need technical Support? Spot an error in the documentation? Get in touch with us on our Community Forum.