Using Next.js with Nacelle

Next.js (opens new window) is one of the leading frameworks for building web sites and web apps with React (opens new window). Next.js' APIs are highly-compatible with the Nacelle Client JS SDK, which makes for a remarkably straightforward development experience.

Next.js Example Project

In Nacelle's React monorepo (opens new window), the Next.js example project (opens new window) demonstrates the use of the Nacelle Client JS SDK to create a digital storefront. This example project takes advantage of some Next.js patterns and features that we find especially valuable.

If you'd like to use the example project as a starting point, you can use degit (opens new window) to clone the example project.

npx degit getnacelle/nacelle-react/examples/nextjs <project-name>

This will create a copy of the example project in a folder named <project-name>. Note that the cloned project won't be under any source control, so we also recommend that you navigate to <project-name> and run:

git init
git add .
git commit -m "init project"

This will initialize the project as a git repo & commit the initial files.

You should then install all of the project dependencies with npm:

npm i

After this, you should be good to start working on the site.

Getting Started

First, setup the appropriate environment variables in .env.local:

• NACELLE_SPACE_ID - your Nacelle Space Id from the Nacelle dashboard
• NACELLE_GRAPHQL_TOKEN - your Nacelle GraphQL Token from the Nacelle dashboard

Then start the development server:

npm run dev

This will start the development server on http://localhost:4000.

Image Optimization

Serving the correct image size and format is important to your site's performance. To ensure your site's images are optimized, we recommend utilizing next/image (opens new window)

Special Features

Incremental Static Regeneration

With incremental static regeneration (opens new window), a page can be regenerated on-demand after it has reached an expiration age defined by the value of the revalidate key in getStaticProps:

// pages/products/[handle].js
export async function getStaticPaths() {
  try {
    const products = await $nacelle.data.allProducts()
    const paths = dataToPaths({ data: products })

    return {
      paths,
      fallback: true,
    }
  } catch (err) {
    throw new Error(`could not fetch products on product detail page:\n${err}`)
  }
}

export async function getStaticProps({ params: { handle }, preview }) {
  const product = await $nacelle.data.product({ handle, preview }).catch(() => {
    console.warn(`no product with handle '${handle}' found.`)
    return null
  })

  return {
    props: { product },
    revalidate: 60 * 60 * 24, // 1 day in seconds
    // Next.js will attempt to re-generate the page:
    // - When a request comes in
    // - At most once every day
  }
}

For more information, check out the docs:

• incremental static regeneration (opens new window)
• the fallback key (opens new window)

Preview Mode

WARNING

Do not attempt to generate routes (getStaticPaths) with the Preview Connector

The Next.js example project uses Next.js Preview (opens new window) conventions to signal that the app should is in / out of preview mode.

In order to activate preview mode, you must access the app via the API Route (opens new window) /api/preview. This API Route uses two query parameters:

• secret (required): the secret used to prevent unauthorized access to preview content
• path (optional, default = /): the path that you will be redirected to after successfully enabling preview mode

To configure your Next.js site to preview products & content from your PIM and CMS, please refer to the Recipe that aligns with your project's combination of PIM and CMS sources:

• Shopify + Contentful
• Shopify + Sanity

Exit Preview Mode

To delete the Next.js Preview cookies (opens new window), simply visit /api/exit-preview.

Learn More

To learn more about Next.js, take a look at the following resources:

• Next.js Documentation (opens new window) - learn about Next.js features and API.
• Learn Next.js (opens new window) - an interactive Next.js tutorial.
• Example projects in the Next.js GitHub repository (opens new window)

Deploying Your Project

With Vercel

The easiest way to deploy your Next.js app is with Vercel (opens new window).

Check out the Next.js deployment documentation (opens new window) for more details.

With Netlify

Check out Netlify's Next.js docs (opens new window) for more details, and consider the limitations (opens new window) of deploying a Next.js site on Netlify before proceeding.