Nana Plays Minesweeper

    next-slicezone

    0.2.6 • Public • Published

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

    Install

    npm i next-slicezone

    DownloadsWeekly Downloads

    3,213

    Version

    0.2.6

    License

    ISC

    Unpacked Size

    82.8 kB

    Total Files

    30

    Last publish

    Collaborators

    • sprite
    • hypervillain
    • amaurycahuet
    • lihbr