Complete step-by-step guide to set up a Sitecore JSS app using Next.js

Here’s a complete step-by-step guide to set up a Sitecore JSS app using Next.js (instead of React SPA) with Sitecore XP.

This is the modern, recommended approach (SSR + better SEO + faster apps).

1. Prerequisites

Make sure you already have:

• Node.js (v18+ recommended)
• npm
• Sitecore XP installed locally
• Sitecore Headless Services installed on XP
• Sitecore JSS CLI

Install CLI if not already:

npm install -g @sitecore-jss/sitecore-jss-cli

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

• Open Sitecore:
• https://your-sitecore.local/sitecore
• Go to:
• /sitecore/system/Settings/Services/API Keys
• Create new API Key:
  • Set Site = your site
  • Allowed Controllers = *

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:

• Create templates
• Create renderings
• Push content

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

• Open browser → http://localhost:3000
• Open Sitecore Experience Editor
• Edit page → changes reflect in Next.js app

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)

• Default in JSS Next.js
• Pages rendered on server
• Better SEO

SSG (Static Site Generation)

• Pre-render pages at build time

ISR (Incremental Static Regeneration)

• Rebuild pages dynamically

9. Project Structure

/src

/components

/pages

/lib

/styles

/scjssconfig.json

.env

Key files:

• pages/[[...path]].tsx → Catch-all route
• lib/layout-service → Fetch Sitecore data

10. Enable Experience Editor Support

Make sure:

• Your Next.js app is running
• Proxy is enabled (already configured in JSS template)

If issues:

jss start

11. Build for Production

npm run build

npm run start

Common Issues

❌ Layout data not loading

• Check API key
• Verify Sitecore URL

Experience Editor not working

• Ensure:
  • App running
  • Correct proxy config

CORS errors

• Configure CORS in Sitecore

Architecture (Next.js + Sitecore XP)

• Frontend: Next.js
• Backend: Sitecore XP
• Data: Layout Service (JSON)
• Rendering: SSR / Hybrid
• Hosting: IIS (Sitecore) + Node server (Next.js)

Thank You!