Here’s a complete step-by-step guide to set up a Sitecore JSS app using Next.js (instead of React SPA) with .
This is the modern, recommended approach (SSR + better SEO + faster apps).
1. Prerequisites
Make sure you already have:
Install CLI if not already:
npm install -g @sitecore-jss/sitecore-jss-cli
Launch scalable Sitecore websites with Next.js, reusable JSS components, headless architecture, and high-performance rendering built for enterprise growth.
2. Create a Next.js JSS App
Run:
jss create my-nextjs-app nextjs
or
npx create-sitecore-jss nextjs my-jss-app
This uses Next.js instead of plain React.
Go to project folder
cd my-nextjs-app
3. Configure Connection to Sitecore XP
Step 1: Create API Key in Sitecore
Step 2: Configure Environment
Edit:
.env
Update values:
SITECORE_API_KEY=your-api-key
SITECORE_API_HOST=https://your-sitecore.local
Step 3: Configure scjssconfig.json
{
"sitecore": {
"instancePath": "C:\\inetpub\\wwwroot\\your-sitecore",
"layoutServiceHost": "https://your-sitecore.local",
"apiKey": "your-api-key"
}
}
4. Deploy JSS App to Sitecore
Run:
jss deploy app -c -d
This will:
5. Run Next.js App
Connected Mode (recommended during dev)
jss start:connected
App runs at:
http://localhost:3000
Now your Next.js app is pulling data from Sitecore XP.
6. Verify Integration
7. Create a Component
jss scaffold component Banner
Deploy again:
jss deploy app
8. Understand Next.js Rendering Modes
With Next.js in Sitecore:
SSR (Server-Side Rendering)
SSG (Static Site Generation)
ISR (Incremental Static Regeneration)
9. Project Structure
/src
/components
/pages
/lib
/styles
/scjssconfig.json
.env
Key files:
10. Enable Experience Editor Support
Make sure:
If issues:
jss start
11. Build for Production
npm run build
npm run start
Common Issues
❌ Layout data not loading
Experience Editor not working
CORS errors
Architecture (Next.js + Sitecore XP)
Sitecore JSS with Next.js is a headless development approach where Next.js provides the frontend application and Sitecore provides content management, layout data, and content services through Sitecore Headless Services.
A JSS Next.js application can be scaffolded using the Sitecore JSS initializer with the Next.js template. After initialization, configure the application for your Sitecore environment, connect the required services, and run it in disconnected or connected mode.
Connect the JSS application to Sitecore by configuring the Sitecore endpoint, API key and required JSS settings, then run the application in connected mode so it can retrieve layout and content data from Sitecore.
Sitecore Layout Service provides structured layout and content data that a JSS Next.js application can consume to determine which components and content should be rendered for a page.
Create an API key in the appropriate Sitecore API Keys location, configure its permissions according to your application's requirements, and provide the key through the JSS application's secure configuration rather than exposing it in client-side code.
Connected mode allows a JSS application to communicate with a running Sitecore instance and retrieve real Sitecore content and layout data during development.
A Next.js JSS application can integrate with Sitecore editors through the JSS editing infrastructure. The application and Sitecore editor endpoints must be configured correctly, including the required editing secret and related settings.
Sitecore JSS applications can use Next.js rendering capabilities such as server-side rendering and static generation, depending on the JSS and Next.js versions and the application's architecture and content requirements.
A JSS application can be deployed to Sitecore using the appropriate JSS deployment commands for its code-first artifacts and content. The Next.js frontend is then built and deployed using a supported Next.js hosting architecture.
Common causes include an incorrect Sitecore endpoint, invalid API key, incorrect JSS configuration, unavailable Layout Service, connectivity problems, or environment and CORS configuration issues. Check the application configuration and Sitecore services first.
