# Next.js helper methods

> This section provides information on how to use the Uniform helper methods for routing in Next.js

Source: https://docs.uniform.app/docs/guides/composition/url-management/routing/nextjs-helper-methods

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"](https://nextjs.org/docs/routing/dynamic-routes#optional-catch-all-routes).
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`

```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>
  )
}
```

## 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).

_For the US region:_

```jsx
import https from 'https'
import { CanvasClient } from '@uniformdev/canvas'
import { withUniformGetStaticPaths } from '@uniformdev/canvas-next/slug'
// Create https agent 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,
  fetch: customFetch,
})
export const getStaticPath = withUniformGetStaticPaths({ client })
```

_For the EU region:_

```jsx
import https from 'https'
import { CanvasClient } from '@uniformdev/canvas'
import { withUniformGetStaticPaths } from '@uniformdev/canvas-next/slug'
// Create https agent 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({
  apiHost: 'https://eu.uniform.app',
  edgeApiHost: 'https://eu.uniform.global',
  apiKey: process.env.UNIFORM_API_KEY,
  projectId: process.env.UNIFORM_PROJECT_ID,
  fetch: customFetch,
})
export const getStaticPath = withUniformGetStaticPaths({ client })
```

### `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.

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

### `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.

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

### `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](https://nextjs.org/docs/routing/introduction#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:

```
__ 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' }`.

#### `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](https://docs.uniform.app/docs/guides/composition/url-management/routing/slug-based-routing) is no longer the recommended way of managing URLs in Uniform.
>
> The [slug-based routing guide](https://docs.uniform.app/docs/guides/composition/url-management/routing/slug-based-routing) has more information if you're using that method.