# 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 dashboardNACELLE_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:
# 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 contentpath
(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:
- 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.