Next SliceZone

A component that fetches Prismic files, returns slices found and matches them with front-end components.

RFC: https://github.com/prismicio/slice-machine/issues/7

Fetching content

Next SliceZone exports 2 functions that are designed to help you quickly get all static paths of a NextJS given route, fetch associated documents on Prismic, and return slices found there.

useGetStaticProps

useGetStaticProps can be used in every page using the SliceZone. It's responsible for:

• fetching content from Prismic
• returning a pre-written Next getStaticProps

Page example

Query a singleton page of type "homepage"

import { Client } from '../prismic'
import { useGetStaticProps } from 'next-slicezone/hooks'
import resolver from '../sm-resolver'

const Page = ({ uid, slices }) => (
    <SliceZone resolver={resolver} slices={slices} />
)

export const getStaticProps = useGetStaticProps({
  client: Client(),
  type: 'homepage', // query document of type "page"
  queryType: 'single', // homepage is a singleton document
})

export default Page

Properties

useGetStaticProps takes a params object as argument.

| Param | Type | Required | Default value | Description | Example value | |----------- |-------------------- |---------- |-------------------- |--------------------------------------------------------------------------------- |-------------------------------------- | | apiParams | object | false | null | Object passed to client apiOptions. | { lang: 'fr-fr' } | | client | function | true | null | Pass a Prismic client here | Prismic.client(apiEndpoint) | | slicesKey | string | false | body / slices | Key of slices array in API response (doc.data[slicesKey]) | 'MySliceZone' | | type | string | false | page | Custom type to be queried | 'another_cts' | | queryType | string | false | repeat | One of 'repeat' or 'single', to switch between getByUID and getSingle calls | 'single' | | getStaticPropsParams | object | false | null | Object passed to return object of getStatcProps| { revalidate: true } |

Example with API Params

Your API calls might depend on other factors in your app, for example the language the user talks. Pass an apiParams object or function to transform your call to the Prismic API.

const PageInFrench = ({ uid, slices }) => (
    <SliceZone resolver={resolver} slices={slices} />
)

export const getStaticProps = useGetStaticProps({
  client: Client(),
  type: 'homepage', // query document of type "page"
  queryType: 'single', // homepage is a singleton document
  apiParams:  {
      lang: 'fr-fr'
  }
})

export default PageInFrench

👆 apiParams can also be a function! See example below

useGetStaticPaths

useGetStaticPaths should be used in each dynamic page that relies on the SliceZone. It's responsible for:

• fetching documents by type on Prismic
• formatting params passed to getStaticProps

Page example (/pages/[lang]/[uid])

Query a repeatable type "page" in a language based on URL parameter.

import { useGetStaticProps, useGetStaticPaths } from 'next-slicezone/hooks'

const Page = ({ uid, slices, data }) => (
    <div>
        <h1>{data.keyTextTitle}</h1>
        <SliceZone resolver={resolver} slices={slices} />
    </div>
)


export const getStaticProps = useGetStaticProps({
    type: 'page',
    queryType: 'repeat',
    apiParams({ params }) {
        // params are passed by getStaticPaths
        return {
            lang: params.lang,
            uid: params.uid
        }
    }
})

// fetch all docs of type `MyPage` and pass params accordingly
export const getStaticPaths = useGetStaticPaths({
  client: Client(),
  type: 'page',
  formatPath: (prismicDocument) => {
      return {
          params: {
              uid: prismicDocument.uid,
              lang: prismicDocument.lang
          }
      }
  }
})

export default Page

Properties

useGetStaticPaths takes a params object as argument. Refer to Next docs to understand what's expected from formatPath.

| Param | Type | Required | Default Value | Description | Example | |------------ |---------- |---------- |--------------- |--------------------------------------- |------------------------------- | | type | - | - | - | Same as useGetStaticProps | - | | apiParams | - | - | - | Same as useGetStaticProps | - | | client | - | - | - | Same as useGetStaticProps | - | | formatPath | function | true | (doc) => null | Function to format Next path argument. Pass null to skip. | ({uid}) =>({ params:{ uid }}) |

SliceZone

Once slices have been fetched server-side, we need to get all slices found and match them with your components.

To display the right content, the SliceZone takes as parameters props passed at build time by useGetStaticProps. Notably:

• slices, the array data components fetched from Prismic
• resolver, a function that resolves calls to components from the SliceZone
• sliceProps, an object or function that passes props to matched slices

Example SliceZone

const Page = ({ data, slices }) => (
    <SliceZone
        slices={slices}
        resolver={resolver}
        sliceProps={({ slice, sliceName, i }) => ({
           theme: i % 1 ? 'light' : 'dark',
           alignLeft: data.keyTextTitle?.length > 35
        })}
)

The resolver function can be generated for you and should be everytime you make a change to your slices structure (rename, add, delete a slice, add a library...). To do this, create a pages/_document file and add the createResolver method to its getInitialProps method:

Example _document file

import Document, { Html, Head, Main, NextScript } from 'next/document'
import { createResolver } from 'next-slicezone/resolver'

export default class extends Document {
  static async getInitialProps(ctx) {
    const initialProps = await Document.getInitialProps(ctx)
    /* In development, generate an sm-resolver.js file
    that will map slices to components */
    if (process.env.NODE_ENV === 'development') {
      await createResolver()
    }
    return { ...initialProps }
  }

  render() {
    return (
      <Html>
        <Head />
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    )
  }
}