Helper methods for routing with Next.js

The Uniform package @uniformdev/canvas-next provides helper methods to help reduce boilerplate code to implement routing in Next.js.

Based on the chosen approach, helper methods are available for:

  • Recommended: Routing using the route API in @uniformdev/canvas-next/route.
  • Routing using project map in @uniformdev/canvas-next/project-map.

If a project map controls all the URLs in your Next.js project, then use Dynamic Route with optional "Catch all". That will fully delegate routing to the project map and make it authoritative. Defining other Next routes will still work, because Next.js overrides the catch-all for more specific routes.

// Example file: /pages/[[...route]].jsx import { UniformComposition, UniformSlot } from '@uniformdev/canvas-react' // default getServerSideProps implementation export { getServerSideProps } from '@uniformdev/canvas-next/route' export default function Page({ data }) { return ( <main> <UniformComposition data={data}> <UniformSlot name="content" /> </UniformComposition> </main> ) }

Flag to use draft content from Canvas. It can be overridden with { preview: process.env.NODE_ENV === 'development' } to build pages with compositions still in draft mode if the code runs in development mode.

Use to override API client and its properties (for example, to override the HTTPS agent).

import https from 'https' import { CanvasClient } from '@uniformdev/canvas' import { withUniformGetStaticPaths } from '@uniformdev/canvas-next/slug' // Create https agenct instance that ignores SSL errors // (note: this approach is also how one would use a proxy server) const httpsAgent = new https.Agent({ rejectUnauthorized: false, }) // Use that agent only in this custom fetch override const customFetch = (...args) => fetch(args[0], { ...args[1], agent: httpsAgent }) const client = new CanvasClient({ apiKey: process.env.UNIFORM_API_KEY, projectId: process.env.UNIFORM_PROJECT_ID, apiHost: process.env.UNIFORM_CLI_BASE_URL, fetch: customFetch, }) export const getStaticPath = withUniformGetStaticPaths({ client })

Override almost any parameter in an API call inside the helper. The request options available will depend on the type of helper you are using.

import { withUniformGetStaticPaths } from '@uniformdev/canvas-next/project-map' export const getStaticPaths = withUniformGetStaticPaths({ requestOptions: { depth: 5, withCompositionData: true, }, })

An optional mapping function that you can use to modify the path passed to the API. it's not available in the withUniformGetStaticPaths helper.

import { withUniformGetServerSideProps } from '@uniformdev/canvas-next/project-map' export const getServerSideProps = withUniformGetServerSideProps({ modifyPath: (path) => `/uniform${path}`, })

Available in withUniformGetStaticProps helper, it specifies name of the parameter that contains pathname or slug, depending on whether you are using the "project map" or "slug" approach respectively. It needs to match Next.js dynamic route segments. For a structure like the ./pages/[[...myParam1]].jsx page you would use { param: 'myParam1' }. Structures like withUniformGetServerSideProps instead rely on the full path received. Use prefix or modifyPath to control that behavior.

The following helpers allow fetching static paths using project map.

They can be imported from @uniformdev/canvas-next/project-map.

Fetch and retrieve all or only specified nodes and return an array.

By default, it's /, so all nodes from the project map are used. You can override this if you want to cover only a section of your website. Here is an example structure:

__ Home / |__ Events /events |__ Chistmas Eve /events/chistmas |__ New Year /events/new-year |__ ... /events/... |__ About Us /about-us |__ Contacts /about-us/contacts |__ Team /about-us/team |__ Career /about-us/career |__ Code of Conduct /about-us/code-of-coduct

If you are building page in Next.js for an "About Us" section, you can specify { rootPath: '/about-us' }.

A string that you want pre-pended to paths returned by your project map. Useful when calling from a nested folder which isn't part of your project map structure.

Returns getServerSideProps and getStaticProps compatible callbacks respectively.

A string that you want to strip from the resolved context.resolvedUrl. Useful when calling from a nested folder which isn't part of your project map structure.

Routing with composition slugs

The routing approach using composition slugs is no longer the recommended way of managing URLs in Uniform.

The slug-based routing guide has more information if you're using that method.

Last modified
Previous
Routing
Next
Redirects