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.
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.
Content from the Prismic API does not, by default, include a URL to a page in your app. If you query for a Homepage document, for example, it will not automatically know that the document is for the index route /.
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 Custom 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.
The Route Resolver is powerful enough to handle most routes. In some cases, however, you may need more control than Route Resolver offers.
The Link Resolver lets you define routes using a function in your app, giving you complete control over the URL. The Link Resolver should be used in combination with Route Resolver; if the Link Resolver returns null, the API will fall back to using the Route Resolver.
The Link Resolver is configured by creating a ~/app/prismic/link-resolver.js file in your Nuxt app.
/**
* The project's Prismic Link Resolver.
* This function overrides the URL for a given Prismic document.
*/
export default function linkResolver(doc) {
if (doc.type === 'page' && doc.uid === 'home') {
return '/'
}
// Let Route Resolver handle all other routes.
return null
}
In the above example, a Page document with a UID of home is overridden to a URL of /. Without this Link Resolver, the document would resolve to /home (assuming a Route Resolver with /:uid, like the previous example).
Generally speaking, follow this rule: Use the Route Resolver to define routes in your app. Only use the Link Resolver to override specific routes.
Further Learning
To learn more about Link Resolver, see the Link 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. Note that it uses the Link Resolver from ~/app/prismic/link-resolver.js to determine Page document routes.
import Prismic from '@prismicio/client'
import { Link } from '@prismicio/helpers'
import linkResolver from '@/app/prismic/link-resolver'
import nuxtConfig from '@/nuxt.config.js'
import sm from '@/sm.json'
export default {
generate: {
routes: async () => {
const client = Prismic.client(sm.apiEndpoint, {
routes: nuxtConfig.prismic.apiOptions.routes,
})
const pages = await client.query(
Prismic.Predicates.at('document.type', 'page')
)
return pages.results.map((page) => Link.url(page, linkResolver))
},
},
}Was this article helpful?
Can't find what you're looking for? Spot an error in the documentation? Get in touch with us on our Community Forum or using the feedback form above.