# 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


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:

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