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
.
Project map with Next.js#
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.
pages/[[...route]].jsx
Common parameters#
preview
#
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.
client
#
Use to override API client and its properties (for example, to override the HTTPS agent).
requestOptions
#
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.
modifyPath
#
An optional mapping function that you can use to modify the path passed to the API. it's not available in the withUniformGetStaticPaths
helper.
param
#
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.
Project map helpers#
The following helpers allow fetching static paths using project map.
They can be imported from @uniformdev/canvas-next/project-map
.
withUniformGetStaticPaths
#
Fetch and retrieve all or only specified nodes and return an array.
rootPath
#
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:
If you are building page in Next.js for an "About Us" section, you can specify { rootPath: '/about-us' }
.
prefix
#
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.
withUniformGetServerSideProps
and withUniformGetStaticProps
#
Returns getServerSideProps
and getStaticProps
compatible callbacks respectively.
withUniformGetServerSideProps
#
prefix
#
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.