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

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

# 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 {
      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:

# Preview Mode

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



In pages/api/preview.js, please be sure to update the previewModeSecret to a value of your choosing.

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:

# 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:

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