create-content-sdk-app 2.2.0-canary.20260625092313 → 2.2.0

package/dist/templates/nextjs-app-router/.agents/skills/content-sdk-graphql-data-fetching/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: content-sdk-graphql-data-fetching
-description: Fetches page data and dictionary via the single Sitecore client. App Router: getPage(path ?? [], { site, locale }), getDictionary, getAppRouterStaticParams; for preview use draftMode() and getPreview/getDesignLibraryData from searchParams. Use when fetching page or dictionary content.
+description: Fetches page data and dictionary via the single Sitecore client. App Router: getPage(path ?? [], { site, locale }), getDictionary, getAppRouterStaticParams in generateStaticParams when generateStaticPaths is enabled; for preview use draftMode() and getPreview/getDesignLibraryData from searchParams. Use when fetching page or dictionary content.
 ---
 
 # Content SDK GraphQL Data Fetching (App Router)
@@ -15,7 +15,7 @@ All Sitecore data fetching goes through the single client in `src/lib/sitecore-c
 
 ## How to perform
 
-- Use the client from `src/lib/sitecore-client.ts` only. In the catch-all page: `await params`, then `client.getPage(path ?? [], { site, locale })`. For SSG use `generateStaticParams` and `client.getAppRouterStaticParams(siteNames, locales)`. For preview use `draftMode()` and `getPreview`/`getDesignLibraryData` from searchParams.
+- Use the client from `src/lib/sitecore-client.ts` only. In the catch-all page: `await params`, then `client.getPage(path ?? [], { site, locale })`. For SSG, follow the `generateStaticParams` rules in Hard Rules below. For preview use `draftMode()` and `getPreview`/`getDesignLibraryData` from searchParams.
 
 ## Hard Rules
 
@@ -23,7 +23,7 @@ All Sitecore data fetching goes through the single client in `src/lib/sitecore-c
 - Pass **site** and **locale** from route params (e.g. `await params` in the page). Do not rely on global state for site/locale in server code.
 - **Catch-all page:** `client.getPage(path ?? [], { site, locale })`. Params are a Promise (Next.js 15+); use `await params` to get `{ site, locale, path? }`.
 - **Preview:** Use `draftMode()`; if `draft.isEnabled`, use `client.getPreview(editingParams)` or `client.getDesignLibraryData(editingParams)` from **searchParams**. Otherwise use getPage with site and locale.
-- **SSG:** `generateStaticParams` — use `client.getAppRouterStaticParams(siteNames, locales)` where site names come from `.sitecore/sites.json` (e.g. `sites.map((s) => s.name)`), locales from `src/i18n/routing.ts` (e.g. `routing.locales.slice()`). Return at least one default param when not generating full paths (e.g. `{ site, locale, path: [] }`).
+- **SSG:** In `generateStaticParams`, call `client.getAppRouterStaticParams(siteNames, locales)` where site names come from `.sitecore/sites.json` (e.g. `sites.map((s) => s.name)`) and locales from `src/i18n/routing.ts` (e.g. `routing.locales.slice()`), but only when `process.env.NODE_ENV !== 'development'` and `scConfig.generateStaticPaths` is true. Otherwise return `[]`. Do not synthesize a fallback param (e.g. `{ site: 'default', locale, path: [] }`).
 - Config for the client comes from `sitecore.config.ts`; use environment variables, never hardcode secrets.
 
 ## Stop Conditions

package/dist/templates/nextjs-app-router/.agents/skills/content-sdk-multisite-management/SKILL.md

@@ -19,7 +19,7 @@ Site resolution from request (e.g. hostname or cookie); proxy rewrites to /[site
 
 ## Hard Rules
 
-- Site list is in `.sitecore/sites.json` (typically generated by Sitecore CLI or deployment). Avoid hand-editing unless the format is known.
+- Site list is in `.sitecore/sites.json` (generated by CLI `generateSites`). When multisite is enabled, sites come from Edge; the configured default site is prepended **only** when `scConfig.defaultSite` is explicitly set (`NEXT_PUBLIC_DEFAULT_SITE_NAME`). Do not synthesize a fake site when env is unset. Avoid hand-editing unless the format is known.
 - **Proxy:** Implemented in `src/proxy.ts`. Next.js runs middleware from `middleware.ts` at root or in `src/` — if the app only has `proxy.ts`, add `src/middleware.ts` that re-exports it.
 - **Chain order is fixed:** LocaleProxy → AppRouterMultisiteProxy → RedirectsProxy → PersonalizeProxy. **Do not change this order.** LocaleProxy runs first so i18n and multisite see the correct locale. AppRouterMultisiteProxy rewrites to /[site]/[locale]/[...path].
 - **Matcher:** Exclude API routes, _next/, sitemap, robots, healthz, Sitecore paths, and static assets so the proxy stays lightweight.

package/dist/templates/nextjs-app-router/.windsurfrules

@@ -47,6 +47,7 @@ src/
 ### @sitecore-content-sdk
 
 - Use `SitecoreClient` for content fetching
+- In `generateStaticParams`, call `getAppRouterStaticParams` only when `scConfig.generateStaticPaths` is true; otherwise return `[]`
 - Implement proper error handling with try/catch blocks
 - Cache API responses using React Query or SWR
 - Handle content preview vs. published content scenarios

package/dist/templates/nextjs-app-router/AGENTS.md

@@ -104,7 +104,7 @@ These are the main head-app–specific concepts. Details are in the sections bel
 
 ### Multisite and Edge middleware (proxy)
 
-- **Site list:** `.sitecore/sites.json` — typically generated by the Sitecore CLI or deployment. Used by middleware and API route handlers. Avoid hand-editing unless you know the format.
+- **Site list:** `.sitecore/sites.json` — generated by the Sitecore CLI (`generateSites`). Contains Edge sites when multisite is enabled; prepends the configured default site **only** when `scConfig.defaultSite` is explicitly set (`NEXT_PUBLIC_DEFAULT_SITE_NAME`). Do not synthesize a fake site when env is unset. Used by middleware and API route handlers. Avoid hand-editing unless you know the format.
 - **Edge middleware:** Implemented in **`src/proxy.ts`**. Next.js only runs middleware from a file named `middleware.ts` at root or in `src/`. If this app has only `proxy.ts`, add `src/middleware.ts` that re-exports it (e.g. `export { default } from './proxy';`) so the proxy runs.
 - **Proxy chain (order is critical):** `defineProxy(locale, multisite, redirects, personalize).exec(req)`:
   - **LocaleProxy** — runs first; uses `sites` and `routing.locales` from `src/i18n/routing.ts`. Required for App Router so locale is set before multisite.
@@ -117,7 +117,7 @@ These are the main head-app–specific concepts. Details are in the sections bel
 ### Data fetching and preview
 
 - **Page data:** In the page (or a Server Component), use `client.getPage(path ?? [], { site, locale })`. For preview, use `draftMode()`; if `draft.isEnabled`, use `client.getPreview(editingParams)` or `client.getDesignLibraryData(editingParams)` from `searchParams`; otherwise use `getPage` with `site` and `locale`.
-- **SSG:** `generateStaticParams` — use `client.getAppRouterStaticParams(sites, routing.locales)` (sites from `.sitecore/sites.json`). Return at least one default param when not generating full paths (e.g. dev or when `generateStaticPaths` is off).
+- **SSG:** In `generateStaticParams`, call `client.getAppRouterStaticParams(sites, routing.locales)` (sites from `.sitecore/sites.json`) only when `process.env.NODE_ENV !== 'development'` and `scConfig.generateStaticPaths` is true. Otherwise return `[]` (local dev, editing hosts, or `GENERATE_STATIC_PATHS=false`). Do not synthesize a fallback param (e.g. `{ site: 'default', locale, path: [] }`).
 - **Metadata:** `generateMetadata` in the same segment can call `client.getPage(path ?? [], { site, locale })` and derive `title` (e.g. from route fields). Next.js will cache as appropriate.
 
 ### Server vs Client components

package/dist/templates/nextjs-app-router/Skills.md

@@ -32,7 +32,7 @@ Using SDK field components: `<Text>`, `<RichText>`, `<Image>`, `<Link>`, with pr
 
 ### content-sdk-graphql-data-fetching
 
-Page and dictionary fetching via the single Sitecore client in `src/lib/sitecore-client.ts`. Use `getPage(path ?? [], { site, locale })`, `getDictionary`, `getAppRouterStaticParams` for SSG. For preview use `draftMode()` and `getPreview`/`getDesignLibraryData` from searchParams.
+Page and dictionary fetching via the single Sitecore client in `src/lib/sitecore-client.ts`. Use `getPage(path ?? [], { site, locale })`, `getDictionary`, and `client.getAppRouterStaticParams` in `generateStaticParams` when `scConfig.generateStaticPaths` is true (otherwise return `[]`). For preview use `draftMode()` and `getPreview`/`getDesignLibraryData` from searchParams.
 
 ### content-sdk-route-configuration
 
@@ -44,7 +44,7 @@ Site and environment: `sitecore.config.ts`, environment variables, default site
 
 ### content-sdk-multisite-management
 
-Multisite: `.sitecore/sites.json`, proxy in `src/proxy.ts`. Chain order is **fixed:** LocaleProxy → AppRouterMultisiteProxy → RedirectsProxy → PersonalizeProxy. Do not change proxy order.
+Multisite: `.sitecore/sites.json` (CLI `generateSites` — Edge sites plus configured `defaultSite` only when `NEXT_PUBLIC_DEFAULT_SITE_NAME` is set), proxy in `src/proxy.ts`. Chain order is **fixed:** LocaleProxy → AppRouterMultisiteProxy → RedirectsProxy → PersonalizeProxy. Do not change proxy order.
 
 ### content-sdk-dictionary-and-i18n
 

package/dist/templates/nextjs-app-router/copilot-instructions.md

@@ -42,6 +42,7 @@ src/
 
 ### @sitecore-content-sdk
 - Use `SitecoreClient` for content fetching
+- In `generateStaticParams`, call `getAppRouterStaticParams` only when `scConfig.generateStaticPaths` is true; otherwise return `[]`
 - Implement proper error handling with try/catch blocks
 - Cache API responses using React Query or SWR
 - Handle content preview vs. published content scenarios

package/dist/templates/nextjs-app-router/src/app/[site]/[locale]/[[...path]]/page.tsx

@@ -64,15 +64,7 @@ export const generateStaticParams = async () => {
       routing.locales.slice()
     );
   }
-  // Next.js 16 requires at least one result
-  // Return a default param for the root page
-  return [
-    {
-      site: sites[0]?.name || 'default',
-      locale: routing.defaultLocale || scConfig.defaultLanguage,
-      path: [],
-    },
-  ];
+  return [];
 };
 <% } -%>
 // Metadata fields for the page.

package/dist/templates/nextjs-app-router-cache-components/.agents/skills/content-sdk-cache-components-and-osr/SKILL.md

@@ -11,7 +11,7 @@ This template is the cache-aware variant of the App Router template. It enables
   - `getSitecorePage({ site, locale, path })` → `sc:route:...`, `sc:item:...` (variants are isolated naturally by the URL path / Cache Components key, no `sc:pvv:` tag is added)
   - `getSitecoreDictionary({ site, locale })` → `sc:dict:{site}:{locale}`
   - `getSitecoreErrorPage({ site, locale, code })` → same tag strategy as `getSitecorePage`
-- A **single Sitecore-webhook endpoint** at `POST /api/revalidate` (in `src/app/api/revalidate/route.ts`) built with `createSitecoreRevalidateRouteHandler`. It consumes the Experience Edge / Content Operations payload shape — `updates[]` are translated into `sc:item:<id>:<locale>:latest` tags, and `tags[]` is a pass-through array that accepts `sc:`-prefixed strings verbatim (handy for ad-hoc / operational calls) or bare item IDs (mapped to `sc:item:<id>:<defaultLocale>:latest`). Dictionary tags from `sites` (`.sitecore/sites.json`, including the default site from `generateSites`) are appended on every call.
+- A **single Sitecore-webhook endpoint** at `POST /api/revalidate` (in `src/app/api/revalidate/route.ts`) built with `createSitecoreRevalidateRouteHandler`. It consumes the Experience Edge / Content Operations payload shape — `updates[]` are translated into `sc:item:<id>:<locale>:latest` tags, and `tags[]` is a pass-through array that accepts `sc:`-prefixed strings verbatim (handy for ad-hoc / operational calls) or bare item IDs (mapped to `sc:item:<id>:<defaultLocale>:latest`). Dictionary tags from `sites` (`.sitecore/sites.json`; configured `defaultSite` from `generateSites` only when `NEXT_PUBLIC_DEFAULT_SITE_NAME` is set) are appended on every call.
 - Optional auth via **`SITECORE_REVALIDATE_SECRET`**: when set, send the same value in **`x-revalidate-secret`**; when empty, no header is required.
 - A `sitecore.config.ts` with the **SDK in-process dictionary cache disabled** (`dictionary: { caching: { enabled: false } }`) so dictionary updates flow through Cache Components only.
 
@@ -44,6 +44,7 @@ This template is the cache-aware variant of the App Router template. It enables
   - Do **not** call `revalidateTag` directly from components; route all invalidation through `/api/revalidate` (or call the route handler in tests).
 - **Adding tags to a new helper:** Mirror the existing helpers. Compute tags with SDK helpers when applicable, fall back to deterministic strings (`sc:something:{site}:{locale}`) otherwise, and ensure those tags are also producible from whatever event triggers invalidation (webhook `updates[]` or ad-hoc `tags[]`).
 - **Sitemap / robots / editing routes** with `cacheComponents: true` do not need an explicit `export const dynamic = 'force-dynamic'` — Next.js infers it.
+- **Editing-host build (`GENERATE_STATIC_PATHS=false`):** Cache Components forbids `return []` from `generateStaticParams`. Return one param `{ site: BUILD_VALIDATION_SITE, locale, path: [] }` from `src/lib/sitecore-build-validation.ts` (`_DEFAULT_` — build-only, not a real Sitecore site). In `page.tsx` / `generateMetadata`, call `isBuildValidationSite(site)` and skip Edge (`setCachedPageParams`, then `notFound()` or minimal metadata). On XM Cloud, `SITECORE` is set during the **build** so `generateSites` skips Edge and `.sitecore/sites.json` can be `[]`; do not put `SITECORE` in `.env.local` for normal `npm start` (it enables editing-host `PreviewProxy` behavior). Locally, simulate with `SITECORE=true npm run build`. Empty `NEXT_PUBLIC_DEFAULT_SITE_NAME` does not block `/` when `sites.json` has Edge sites — routing uses `sites.json`, not only the env var.
 
 ## Debugging stale content
 

package/dist/templates/nextjs-app-router-cache-components/.agents/skills/content-sdk-graphql-data-fetching/SKILL.md

@@ -20,15 +20,16 @@ This template ships **tag-aware cache helpers** under `src/lib/cache/`. All non-
   - Dictionary: `getSitecoreDictionary({ site, locale })`
   - 404 / 500 Sitecore error content (Server context): `getSitecoreErrorPage({ site, locale, code })`
 - For preview / draft, import the SDK client from `src/lib/sitecore-client.ts` and call `client.getPreview(editingParams)` or `client.getDesignLibraryData(editingParams)` directly. Do **not** wrap these in `'use cache'`.
-- For SSG params, call `client.getAppRouterStaticParams(siteNames, locales)` in `generateStaticParams`.
+- For SSG params in `generateStaticParams`, call `client.getAppRouterStaticParams(siteNames, locales)` only when `process.env.NODE_ENV !== 'development'` and `scConfig.generateStaticPaths` is true. When `generateStaticPaths` is false, return one param from `BUILD_VALIDATION_SITE` in `src/lib/sitecore-build-validation.ts` (Cache Components forbids `return []`).
 
 ## Hard Rules
 
 - **Cached reads (non-preview):** Use the helpers in `src/lib/cache/`. Do not call `client.getPage` / `client.getDictionary` / `client.getErrorPage` directly in pages, layouts, or i18n config — bypassing the helpers means the read is missing Sitecore cache tags and `revalidateTag` will not invalidate it.
 - **Preview reads:** Use `client.getPreview(editingParams)` / `client.getDesignLibraryData(editingParams)` **directly**. Preview must stay dynamic; do not put it under `'use cache'`.
-- **Catch-all page (`src/app/[site]/[locale]/[[...path]]/page.tsx`):** `await params` → check `draftMode().isEnabled`; if enabled, use the client directly with `searchParams`; otherwise call `getSitecorePage({ site, locale, path: path ?? [] })`.
-- **`generateMetadata`** in the same segment should also call `getSitecorePage` so it shares the cache entry with the page render.
-- **SSG:** `generateStaticParams` — use `client.getAppRouterStaticParams(siteNames, locales)` where site names come from `.sitecore/sites.json` (e.g. `sites.map((s) => s.name)`), locales from `src/i18n/routing.ts` (e.g. `routing.locales.slice()`). Return at least one default param when not generating full paths.
+- **Catch-all page (`src/app/[site]/[locale]/[[...path]]/page.tsx`):** `await params` → if `isBuildValidationSite(site)` (`BUILD_VALIDATION_SITE` / `_DEFAULT_`), call `setCachedPageParams({ site, locale })` then `notFound()` without Edge. Otherwise check `draftMode().isEnabled`; if enabled, use the client directly with `searchParams`; else call `getSitecorePage({ site, locale, path: path ?? [] })`. Call `setCachedPageParams` before every `notFound()` on real routes.
+- **Segment not-found:** `getCachedPageParams()` → static HTML when site is empty or `isBuildValidationSite(site)`; otherwise `getSitecoreErrorPage`. Do not call `headers()` in not-found.
+- **`generateMetadata`** in the same segment should call `getSitecorePage` for real sites; return `{ title: 'Page' }` when `isBuildValidationSite(site)`.
+- **SSG:** In `generateStaticParams`, call `client.getAppRouterStaticParams(siteNames, locales)` where site names come from `.sitecore/sites.json` (e.g. `sites.map((s) => s.name)`) and locales from `src/i18n/routing.ts` (e.g. `routing.locales.slice()`), but only when `process.env.NODE_ENV !== 'development'` and `scConfig.generateStaticPaths` is true. When `generateStaticPaths` is false, return `{ site: BUILD_VALIDATION_SITE, locale, path: [] }` from `src/lib/sitecore-build-validation.ts` — not `return []`, not `sites[0]`, not hardcoded `'default'`. See [empty-generate-static-params](https://nextjs.org/docs/messages/empty-generate-static-params).
 - **Single SitecoreClient instance** in `src/lib/sitecore-client.ts`. The cache helpers import this client; do not create a second client.
 - Pass **site** and **locale** from route params (e.g. `await params` in the page). Do not rely on global state for site/locale in server code.
 - Config for the client comes from `sitecore.config.ts`; use environment variables, never hardcode secrets.

package/dist/templates/nextjs-app-router-cache-components/.agents/skills/content-sdk-multisite-management/SKILL.md

@@ -19,7 +19,7 @@ Site resolution from request (e.g. hostname or cookie); proxy rewrites to /[site
 
 ## Hard Rules
 
-- Site list is in `.sitecore/sites.json` (typically generated by Sitecore CLI or deployment). Avoid hand-editing unless the format is known.
+- Site list is in `.sitecore/sites.json` (generated by CLI `generateSites` in `sitecore.cli.config.ts`). When multisite is enabled, sites come from Edge; the configured default site is prepended **only** when `scConfig.defaultSite` is explicitly set (`NEXT_PUBLIC_DEFAULT_SITE_NAME`). Do not synthesize a fake site when env is unset. Avoid hand-editing unless the format is known.
 - **Proxy:** Implemented in `src/proxy.ts`. Next.js runs middleware from `middleware.ts` at root or in `src/` — if the app only has `proxy.ts`, add `src/middleware.ts` that re-exports it.
 - **Chain order is fixed:** PreviewProxy → BotTrackingProxy → LocaleProxy → AppRouterMultisiteProxy → RedirectsProxy → PersonalizeProxy. **Do not change this order.** PreviewProxy authorizes preview first; LocaleProxy must run before multisite so i18n and multisite see the correct locale. AppRouterMultisiteProxy rewrites to /[site]/[locale]/[...path].
 - **Matcher:** Exclude API routes (including `/api/revalidate`), `_next/`, sitemap, robots, healthz, Sitecore paths, and static assets so the proxy stays lightweight.

package/dist/templates/nextjs-app-router-cache-components/.agents/skills/content-sdk-route-configuration/SKILL.md

@@ -15,7 +15,7 @@ Single catch-all route and layout hierarchy. Site and locale are **in the path**
 
 ## How to perform
 
-- Single Sitecore page: `src/app/[site]/[locale]/[[...path]]/page.tsx`. Use `await params` for `{ site, locale, path? }`; if `draftMode().isEnabled` use the client directly, otherwise call `getSitecorePage({ site, locale, path: path ?? [] })`. Call `setRequestLocale(\`${site}_${locale}\`)` at the top. Layout chain: `app/layout.tsx` → `app/[site]/layout.tsx` (Bootstrap, draftMode) → `app/[site]/[locale]/[[...path]]/layout.tsx` (calls `setCachedPageParams({ site, locale })`) → page. Segment not-found: `src/app/[site]/[locale]/[[...path]]/not-found.tsx` reads `getCachedPageParams()` and calls `getSitecoreErrorPage`. Root not-found: `src/app/not-found.tsx` falls back to `scConfig.defaultSite` / `scConfig.defaultLanguage` and calls `getSitecoreErrorPage`.
+- Single Sitecore page: `src/app/[site]/[locale]/[[...path]]/page.tsx`. Use `await params` for `{ site, locale, path? }`; if `isBuildValidationSite(site)` skip Edge (`setCachedPageParams`, `notFound()`); else if `draftMode().isEnabled` use the client directly; otherwise call `getSitecorePage({ site, locale, path: path ?? [] })`. Call `setCachedPageParams` before each `notFound()` on real routes. Layout chain: `app/layout.tsx` → `app/[site]/layout.tsx` (Bootstrap, draftMode) → `app/[site]/[locale]/[[...path]]/layout.tsx` (calls `setCachedPageParams({ site, locale })`) → page. Segment not-found: reads `getCachedPageParams()`; static HTML when site is empty or `isBuildValidationSite(site)`; else `getSitecoreErrorPage`. Root not-found: `src/app/not-found.tsx` uses `scConfig.defaultSite` / `scConfig.defaultLanguage`.
 
 ## Hard Rules
 
@@ -26,7 +26,7 @@ Single catch-all route and layout hierarchy. Site and locale are **in the path**
 - **`generateMetadata`** in the same segment should mirror the page's `draftMode` branching (preview → `client.getPreview` / `client.getDesignLibraryData`; otherwise `getSitecorePage`) so the `<title>` matches the rendered body and shares the same cache entry in the non-draft path.
 - **Layout hierarchy:** `app/layout.tsx` → `app/[site]/layout.tsx` (Bootstrap with `siteName={site}` and `draftMode()`) → `app/[site]/[locale]/[[...path]]/layout.tsx` (calls `setCachedPageParams({ site, locale })`) → page. Do not put site/locale-specific data fetching in the root layout. **Keep the segment layout's `setCachedPageParams` call** — the segment `not-found.tsx` depends on it.
 - Placeholders are rendered by the layout (e.g. Placeholder component); do not change placeholder names or structure without aligning with Sitecore layout definition.
-- **Segment not-found (404):** `src/app/[site]/[locale]/[[...path]]/not-found.tsx`. Reads `{ site, locale }` via `getCachedPageParams()` (set by the segment layout for the same request), with `scConfig.defaultSite` / `scConfig.defaultLanguage` as a safety fallback, then calls `getSitecoreErrorPage({ site, locale, code: ErrorPage.NotFound })`. Wrap the rendered layout in `NextIntlClientProvider` so i18n works in the 404 markup. **Do not** call `headers()` here — it would opt the route out of SSG; the `getCachedPageParams` mechanism exists precisely to avoid that.
+- **Segment not-found (404):** `src/app/[site]/[locale]/[[...path]]/not-found.tsx`. Reads `{ site, locale }` via `getCachedPageParams()` (set by the segment layout and by the page before `notFound()`), with `scConfig.defaultSite` / `scConfig.defaultLanguage` as fallback. If `!resolvedSite?.trim()` or `isBuildValidationSite(resolvedSite)` (`_DEFAULT_`), return static fallback HTML without Edge. Otherwise call `getSitecoreErrorPage({ site, locale, code: ErrorPage.NotFound })`. Wrap Sitecore 404 layout in `NextIntlClientProvider`. **Do not** call `headers()` here.
 - **Root not-found (fallback 404):** `src/app/not-found.tsx`. Used when no segment claims the request (e.g. an unknown top-level path). Resolves site/locale from `scConfig.defaultSite` / `scConfig.defaultLanguage` and calls `getSitecoreErrorPage(...)` so 404 content gets the same Sitecore cache tags (`sc:route`, `sc:item`) as a normal page and can be invalidated by webhook.
 - **Server error (500):** `src/app/global-error.tsx` is a Client Component (`'use client'`) and calls `client.getErrorPage(ErrorPage.InternalServerError, …)` from the client side. It is **not** cached — the cache helpers are server-only.
 

package/dist/templates/nextjs-app-router-cache-components/.agents/skills/content-sdk-site-setup-and-env/SKILL.md

@@ -21,7 +21,7 @@ Central config in sitecore.config.ts; all secrets and environment-specific value
 
 - Use `sitecore.config.ts` with `defineConfig` from the SDK. Expose api (edge, local), defaultSite, defaultLanguage, editingSecret, multisite, redirects, personalize as needed.
 - All sensitive or environment-specific values must come from environment variables (e.g. `process.env.SITECORE_API_KEY`, `process.env.SITECORE_REVALIDATE_SECRET`). Never hardcode API keys, secrets, or production URLs in source.
-- **Document in `.env.*.example`:** `SITECORE_EDGE_CONTEXT_ID`, `NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID`, `SITECORE_API_KEY` / `SITECORE_API_HOST` (local), `NEXT_PUBLIC_DEFAULT_SITE_NAME`, `NEXT_PUBLIC_DEFAULT_LANGUAGE`, `SITECORE_EDITING_SECRET`, `SITECORE_REVALIDATE_SECRET` (optional; empty = no `x-revalidate-secret` header).
+- **Document in `.env.*.example`:** `SITECORE_EDGE_CONTEXT_ID`, `NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID`, `SITECORE_API_KEY` / `SITECORE_API_HOST` (local), `NEXT_PUBLIC_DEFAULT_SITE_NAME`, `NEXT_PUBLIC_DEFAULT_LANGUAGE`, `SITECORE_EDITING_SECRET`, `SITECORE_REVALIDATE_SECRET` (optional; empty = no `x-revalidate-secret` header), `GENERATE_STATIC_PATHS` (optional; `false` for editing-host builds — OSR still uses `BUILD_VALIDATION_SITE` in `generateStaticParams`, not `return []`).
 - **Dictionary cache must stay disabled** in `sitecore.config.ts`: `dictionary: { caching: { enabled: false } }`. The cache helper in `src/lib/cache/get-sitecore-dictionary.ts` is the only dictionary cache layer; if you re-enable the SDK cache, `revalidateTag` will not invalidate dictionary data.
 - Document every new or changed env var in `.env.example` (or `.env.remote.example` / `.env.container.example`). Use placeholder or empty value and a short comment; never put real secrets in example files.
 - Never commit `.env` or `.env.local`; they are gitignored. Example files are the source of truth for which vars exist.

package/dist/templates/nextjs-app-router-cache-components/.cursor/rules/sitecore.mdc

@@ -103,7 +103,8 @@ Dynamic Routes:
 
 - Use [[...path]] for Sitecore catch-all routes (under `[site]/[locale]/`)
 - Handle route parameters appropriately
-- Implement proper 404 handling via the root `src/app/not-found.tsx` (uses `getSitecoreErrorPage`)
+- Implement proper 404 handling: segment `src/app/[site]/[locale]/[[...path]]/not-found.tsx` (reads `getCachedPageParams()`; static HTML when site is empty or `isBuildValidationSite(site)`; otherwise `getSitecoreErrorPage`) and root `src/app/not-found.tsx` (falls back to `scConfig.defaultSite` / `scConfig.defaultLanguage`)
+- When `generateStaticPaths` is false, `generateStaticParams` returns `BUILD_VALIDATION_SITE` (`_DEFAULT_`) — not `return []` (Cache Components). Skip Edge in page/metadata for that site.
 - Support preview mode when needed (uncached path)
 
 Layout and Loading:
@@ -139,7 +140,7 @@ export default async function LocalizedPage() {
 - Body shape (Sitecore Experience Edge / Content Operations):
   - `updates[]`: publish-event rows; each `identifier` (with `-media` / `-layout` stripped) maps to `sc:item:<id>:<locale>:latest`
   - `tags[]`: pass-through array. `sc:`-prefixed strings are revalidated verbatim (use this for ad-hoc / operational calls); bare item IDs are mapped to `sc:item:<id>:<defaultLocale>:latest`
-  - Dictionary tags from `sites` (`.sitecore/sites.json`, including the default site from `generateSites`) are appended on every call
+  - Dictionary tags from `sites` (`.sitecore/sites.json`; includes configured `defaultSite` from `generateSites` only when `NEXT_PUBLIC_DEFAULT_SITE_NAME` is set) are appended on every call
 - Do not bypass auth or call `revalidateTag` directly from components
 
 ## Configuration

package/dist/templates/nextjs-app-router-cache-components/.windsurfrules

@@ -49,7 +49,8 @@ src/
 
 ### @sitecore-content-sdk
 
-- Use `SitecoreClient` directly for preview, editing, and `getAppRouterStaticParams`
+- Use `SitecoreClient` directly for preview, editing, and `getAppRouterStaticParams` (in `generateStaticParams` when `scConfig.generateStaticPaths` is true; when false return `{ site: BUILD_VALIDATION_SITE, locale, path: [] }` from `src/lib/sitecore-build-validation.ts` — Cache Components forbids `return []`)
+- **Build validation:** `_DEFAULT_` is build-only — skip Edge in page/metadata when `isBuildValidationSite(site)`; segment `not-found.tsx` skips Edge when site is `_DEFAULT_`. Call `setCachedPageParams` before `notFound()` on real routes; read with `getCachedPageParams()` in segment not-found (do not use `headers()` there).
 - Use the cache helpers in `src/lib/cache/` (e.g. `getSitecorePage`, `getSitecoreDictionary`, `getSitecoreErrorPage`) for cached reads — these wrap the client under `'use cache'` and attach Sitecore tags
 - Implement proper error handling with try/catch blocks
 - Handle content preview vs. published content scenarios — preview must remain **dynamic** (do not wrap preview in `'use cache'`)

package/dist/templates/nextjs-app-router-cache-components/AGENTS.md

@@ -77,7 +77,7 @@ These are the main head-app–specific concepts. Details are in the sections bel
 - **`POST /api/revalidate`** is a single Sitecore-webhook endpoint. It accepts the Sitecore Experience Edge / Content Operations payload shape:
   - `updates[]` — Sitecore publish-event rows; the handler maps each row's `identifier` (with `-media` / `-layout` stripped) to `sc:item:<id>:<locale>:latest`.
   - `tags[]` — pass-through array. `sc:`-prefixed strings are revalidated verbatim (handy for ad-hoc, operational calls); bare item IDs are mapped to `sc:item:<id>:<defaultLocale>:latest`.
-  - Dictionary tags from `sites` (`.sitecore/sites.json`, including the default site from `generateSites`) are merged on every call so dictionary changes are covered.
+  - Dictionary tags from `sites` (`.sitecore/sites.json`; configured `defaultSite` from `generateSites` only when `NEXT_PUBLIC_DEFAULT_SITE_NAME` is set) are merged on every call so dictionary changes are covered.
 - **Auth (optional):** leave `SITECORE_REVALIDATE_SECRET` empty to skip auth (no `x-revalidate-secret` header). When set, callers must send the same value in `x-revalidate-secret` (configure that header on your Sitecore webhook).
 - **Dictionary cache:** `sitecore.config.ts` disables the SDK's in-process dictionary cache (`dictionary: { caching: { enabled: false } }`). The Cache Components helper is the only dictionary cache layer, so `revalidateTag` works end to end.
 
@@ -90,7 +90,8 @@ These are the main head-app–specific concepts. Details are in the sections bel
 ### SitecoreClient
 
 - **Where:** Single shared instance in `src/lib/sitecore-client.ts` — `new SitecoreClient({ ...scConfig })` with config from `sitecore.config.ts`.
-- **Use directly for:** preview and editing (`getPreview`, `getDesignLibraryData`, internal editing routes), 500 page (`client.getErrorPage(ErrorPage.InternalServerError)` in `global-error.tsx`), and `getAppRouterStaticParams`.
+- **Use directly for:** preview and editing (`getPreview`, `getDesignLibraryData`, internal editing routes), 500 page (`client.getErrorPage(ErrorPage.InternalServerError)` in `global-error.tsx`), and `getAppRouterStaticParams` when `generateStaticPaths` is true.
+- **Build validation:** when `generateStaticPaths` is false, `generateStaticParams` returns `BUILD_VALIDATION_SITE` (`_DEFAULT_` from `src/lib/sitecore-build-validation.ts`); the page and `generateMetadata` skip Edge for that site; segment `not-found.tsx` skips Edge when site is `_DEFAULT_`. See SSG rules under Data fetching.
 - **Use the cache helpers for everything else:** non-preview page reads go through `getSitecorePage`; dictionary reads through `getSitecoreDictionary`; 404 content through `getSitecoreErrorPage`. The cache helpers wrap the same client under `'use cache'` and attach the right tags.
 - **Do not:** Create a second client or instantiate SitecoreClient elsewhere. Pass `site` and `locale` from route params (or `getCachedPageParams()` in the segment `not-found.tsx`, or `scConfig.defaultSite` / `scConfig.defaultLanguage` in the root `not-found.tsx`), not from global state.
 
@@ -131,7 +132,7 @@ These are the main head-app–specific concepts. Details are in the sections bel
 
 ### Multisite and Edge middleware (proxy)
 
-- **Site list:** `.sitecore/sites.json` — typically generated by the Sitecore CLI or deployment. Used by middleware and API route handlers. Avoid hand-editing unless you know the format.
+- **Site list:** `.sitecore/sites.json` — generated by the Sitecore CLI (`generateSites` in `sitecore.cli.config.ts`). Contains sites from Edge when multisite is enabled; prepends the configured default site **only** when `scConfig.defaultSite` is explicitly set (`NEXT_PUBLIC_DEFAULT_SITE_NAME`). Do not synthesize a fake site when env is unset. Used by middleware and API route handlers. Avoid hand-editing unless you know the format.
 - **Edge middleware:** Implemented in **`src/proxy.ts`**. Next.js only runs middleware from a file named `middleware.ts` at root or in `src/`. If this app has only `proxy.ts`, add `src/middleware.ts` that re-exports it (e.g. `export { default } from './proxy';`) so the proxy runs.
 - **Proxy chain (order is critical):** `defineProxy(preview, botTracking, locale, multisite, redirects, personalize).exec(req)`:
   - **PreviewProxy** — authorizes preview requests on the internal editing host; no-op elsewhere.
@@ -148,8 +149,8 @@ These are the main head-app–specific concepts. Details are in the sections bel
 - **Page data:** In the page (or a Server Component), use `getSitecorePage({ site, locale, path: path ?? [] })` from `src/lib/cache/get-sitecore-page.ts`. For preview, use `draftMode()`; if `draft.isEnabled`, call `client.getPreview(editingParams)` or `client.getDesignLibraryData(editingParams)` **directly on the SDK client** (preview must stay dynamic, not cached).
 - **Dictionary:** Use `getSitecoreDictionary({ site, locale })` from `src/lib/cache/get-sitecore-dictionary.ts` (not `client.getDictionary` directly). This applies the `sc:dict:{site}:{locale}` tag so dictionary updates can be invalidated by webhook.
 - **404 content:** Use `getSitecoreErrorPage({ site, locale, code: ErrorPage.NotFound })` from `src/lib/cache/get-sitecore-error-page.ts`. 500 content (in `global-error.tsx`) calls `client.getErrorPage(ErrorPage.InternalServerError, ...)` directly since `global-error.tsx` is a Client Component.
-- **SSG:** `generateStaticParams` — use `client.getAppRouterStaticParams(sites, routing.locales)` (sites from `.sitecore/sites.json`). Return at least one default param when not generating full paths (e.g. dev or when `generateStaticPaths` is off).
-- **Metadata:** `generateMetadata` in the same segment calls `getSitecorePage` so it hits the same cache entry as the page.
+- **SSG:** In `generateStaticParams`, call `client.getAppRouterStaticParams(sites, routing.locales)` (sites from `.sitecore/sites.json`) only when `process.env.NODE_ENV !== 'development'` and `scConfig.generateStaticPaths` is true. When `generateStaticPaths` is false, return one param `{ site: BUILD_VALIDATION_SITE, locale, path: [] }` from `src/lib/sitecore-build-validation.ts` (`_DEFAULT_`) — a **build-only placeholder**, not a real Sitecore site. Cache Components forbids `return []` ([empty-generate-static-params](https://nextjs.org/docs/messages/empty-generate-static-params)). The catch-all page must call `isBuildValidationSite(site)` and skip Edge (seed `setCachedPageParams`, then `notFound()`); `generateMetadata` must skip Edge for the same site. Do not use `sites[0]` or hardcoded `'default'` for this fallback.
+- **Metadata:** `generateMetadata` in the same segment calls `getSitecorePage` (except for `BUILD_VALIDATION_SITE`) so it hits the same cache entry as the page render. Segment `not-found.tsx` skips Edge when `isBuildValidationSite(resolvedSite)`.
 
 ### On-demand revalidation (`POST /api/revalidate`)
 
@@ -169,8 +170,8 @@ These are the main head-app–specific concepts. Details are in the sections bel
 This template ships **two** not-found components and a segment layout that ties them together while staying compatible with SSG and Cache Components:
 
 - **Root not-found:** `src/app/not-found.tsx`. Used as the fallback when no segment handles the route (e.g. unknown site/locale). Falls back to `scConfig.defaultSite` / `scConfig.defaultLanguage` and calls `getSitecoreErrorPage({ site, locale, code: ErrorPage.NotFound })`, so 404 content gets the same Sitecore cache tags as a normal page.
-- **Segment not-found:** `src/app/[site]/[locale]/[[...path]]/not-found.tsx`. Triggered when the catch-all page calls `notFound()` (e.g. the requested path resolves to no Sitecore page). Reads site/locale via `getCachedPageParams()` (set by the segment layout below) and calls `getSitecoreErrorPage(...)`. Wrapped in `NextIntlClientProvider` to keep i18n working in 404 markup.
-- **Segment layout:** `src/app/[site]/[locale]/[[...path]]/layout.tsx`. Calls `setCachedPageParams({ site, locale })` on every request for this segment. This uses the SDK's React `cache()` based `set/getCachedPageParams` helpers (from `@sitecore-content-sdk/nextjs`) so the segment `not-found.tsx` can read `{ site, locale }` **without** calling `headers()` — which would opt the route out of SSG. **Do not** call `headers()` in the segment not-found; keep using `getCachedPageParams()`.
+- **Segment not-found:** `src/app/[site]/[locale]/[[...path]]/not-found.tsx`. Triggered when the catch-all page calls `notFound()`. Reads site/locale via `getCachedPageParams()` (set by the segment layout and by the page before `notFound()`). If site is empty or `isBuildValidationSite(resolvedSite)` (`_DEFAULT_`), returns static fallback HTML without calling Edge. Otherwise calls `getSitecoreErrorPage(...)`. Wrapped in `NextIntlClientProvider` to keep i18n working in 404 markup.
+- **Segment layout:** `src/app/[site]/[locale]/[[...path]]/layout.tsx`. Calls `setCachedPageParams({ site, locale })` on every request for this segment. The catch-all **page** also calls `setCachedPageParams` immediately before `notFound()` so early 404s during SSG still pass site/locale to segment not-found. Uses the SDK's React `cache()` based `set/getCachedPageParams` helpers (from `@sitecore-content-sdk/nextjs`) so segment `not-found.tsx` can read `{ site, locale }` **without** calling `headers()` — which would opt the route out of SSG. **Do not** call `headers()` in the segment not-found; keep using `getCachedPageParams()`.
 - **Root global error:** `src/app/global-error.tsx` is a Client Component (`'use client'`) that fetches `client.getErrorPage(ErrorPage.InternalServerError, ...)` on the client; it is not cached (the cache helpers are server-side).
 
 ### API route handlers
@@ -216,7 +217,8 @@ This template ships **two** not-found components and a segment layout that ties
 | Set `SITECORE_REVALIDATE_SECRET` and send `x-revalidate-secret` when you want the endpoint protected | Hardcode the revalidate secret or expose it client-side |
 | Keep `sitecore.config.ts` dictionary cache disabled | Re-enable the SDK in-process dictionary cache (bypasses `revalidateTag`) |
 | Use Server Components for async data fetching | Put async data fetching in client components when SSR is intended |
-| Set site/locale via `setCachedPageParams` in `[site]/[locale]/[[...path]]/layout.tsx` and read with `getCachedPageParams()` in the segment `not-found.tsx` | Call `headers()` in not-found (opts out of SSG) or hardcode site/locale |
+| Set site/locale via `setCachedPageParams` in segment layout **and** in the page before `notFound()`; read with `getCachedPageParams()` in segment `not-found.tsx` | Call `headers()` in not-found (opts out of SSG) or hardcode site/locale |
+| Use `BUILD_VALIDATION_SITE` (`_DEFAULT_`) when `generateStaticPaths` is false (Cache Components); skip Edge for that site in page/metadata/not-found | `return []` from `generateStaticParams`, or use `sites[0]` / `'default'` as build fallback |
 | Use createXRouteHandler and `.sitecore/sites.json` for sitemap/robots | Hardcode site list or commit `.env` |
 | Use Sitecore field components and validate fields | Expose API keys or editing secret in client code |
 | Document required env vars in `.env.example` only | Commit `.env` or `.env.local` |
@@ -226,7 +228,7 @@ This template ships **two** not-found components and a segment layout that ties
 
 ## Guardrails for agentic AI
 
-- **Preserve behavior:** Do not change the proxy order (PreviewProxy → BotTrackingProxy → LocaleProxy → AppRouterMultisiteProxy → …), the `[site]/[locale]/[[...path]]` route shape, the `{site}_{locale}` next-intl convention, the cache-helper boundary (cache helpers wrap non-preview Sitecore reads; preview/editing use `client.*` directly), or the `setCachedPageParams` → `getCachedPageParams` flow between the segment layout and segment `not-found.tsx` (this is what keeps the 404 SSG-safe). Preserve `draftMode` handling in layout and page.
+- **Preserve behavior:** Do not change the proxy order (PreviewProxy → BotTrackingProxy → LocaleProxy → AppRouterMultisiteProxy → …), the `[site]/[locale]/[[...path]]` route shape, the `{site}_{locale}` next-intl convention, the cache-helper boundary (cache helpers wrap non-preview Sitecore reads; preview/editing use `client.*` directly), the `BUILD_VALIDATION_SITE` build-validation flow, or the `setCachedPageParams` → `getCachedPageParams` flow between the segment layout, page, and segment `not-found.tsx` (this is what keeps the 404 SSG-safe). Preserve `draftMode` handling in layout and page.
 - **Do not expand scope:** Limit edits to the app (app router, components, API routes, cache helpers, i18n, config). Do not modify SDK packages or monorepo tooling unless explicitly asked. Do not change CI, lockfiles, or root config.
 - **Follow existing patterns:** When adding routes, layouts, or components, mirror the existing structure. Use the same Sitecore client, cache helpers, component maps, and env-based config. Do not introduce a different way to resolve site/locale, a second client, or a parallel cache layer.
 - **Verify and stay safe:** After edits, the app should build with `npm run build`. Do not commit secrets or `.env`; only document variables in `.env.example`. Do not add npm dependencies without explicit approval. When in doubt, prefer the existing implementation and ask for clarification.

package/dist/templates/nextjs-app-router-cache-components/Skills.md

@@ -32,11 +32,11 @@ Using SDK field components: `<Text>`, `<RichText>`, `<Image>`, `<Link>`, with pr
 
 ### content-sdk-graphql-data-fetching
 
-Page and dictionary fetching via the cache helpers in `src/lib/cache/`. Use `getSitecorePage({ site, locale, path })`, `getSitecoreDictionary({ site, locale })`, `getSitecoreErrorPage({ site, locale, code })` for cached reads with Sitecore tags. Use `client.getPreview` / `client.getDesignLibraryData` directly for preview, and `client.getAppRouterStaticParams` for SSG.
+Page and dictionary fetching via the cache helpers in `src/lib/cache/`. Use `getSitecorePage({ site, locale, path })`, `getSitecoreDictionary({ site, locale })`, `getSitecoreErrorPage({ site, locale, code })` for cached reads with Sitecore tags. Use `client.getPreview` / `client.getDesignLibraryData` directly for preview. In `generateStaticParams`, call `client.getAppRouterStaticParams` when `scConfig.generateStaticPaths` is true; when false, return `{ site: BUILD_VALIDATION_SITE, locale, path: [] }` from `src/lib/sitecore-build-validation.ts` (not `return []`). Skip Edge in page/metadata/not-found when `isBuildValidationSite(site)`.
 
 ### content-sdk-route-configuration
 
-Routing: single catch-all at `src/app/[site]/[locale]/[[...path]]/page.tsx`. Layout chain: `app/layout.tsx` → `app/[site]/layout.tsx` (Bootstrap, draftMode) → `app/[site]/[locale]/[[...path]]/layout.tsx` (calls `setCachedPageParams({ site, locale })`) → page. Call `setRequestLocale(\`${site}_${locale}\`)` at the top of the page. **Two not-founds**: the segment `[[...path]]/not-found.tsx` reads `getCachedPageParams()` (set by the segment layout) and calls `getSitecoreErrorPage` — staying SSG-safe because it never calls `headers()`. The root `src/app/not-found.tsx` falls back to `scConfig.defaultSite` / `scConfig.defaultLanguage` for unrouted requests. `global-error.tsx` uses `client.getErrorPage` directly (it's a Client Component, not cached).
+Routing: single catch-all at `src/app/[site]/[locale]/[[...path]]/page.tsx`. Layout chain: `app/layout.tsx` → `app/[site]/layout.tsx` (Bootstrap, draftMode) → `app/[site]/[locale]/[[...path]]/layout.tsx` (calls `setCachedPageParams({ site, locale })`) → page. Call `setRequestLocale(\`${site}_${locale}\`)` in the page. **Two not-founds**: segment `[[...path]]/not-found.tsx` reads `getCachedPageParams()` (set by layout and by the page before `notFound()`); skips Edge for `BUILD_VALIDATION_SITE` (`_DEFAULT_`) on site, or when site is empty; otherwise calls `getSitecoreErrorPage`. Root `src/app/not-found.tsx` falls back to `scConfig.defaultSite` / `scConfig.defaultLanguage`. `global-error.tsx` uses `client.getErrorPage` directly (Client Component, not cached).
 
 ### content-sdk-site-setup-and-env
 
@@ -44,7 +44,7 @@ Site and environment: `sitecore.config.ts`, environment variables, default site
 
 ### content-sdk-multisite-management
 
-Multisite: `.sitecore/sites.json`, proxy in `src/proxy.ts`. Chain order is **fixed:** PreviewProxy → BotTrackingProxy → LocaleProxy → AppRouterMultisiteProxy → RedirectsProxy → PersonalizeProxy. Do not change proxy order.
+Multisite: `.sitecore/sites.json` (CLI `generateSites` — Edge sites plus configured `defaultSite` only when `NEXT_PUBLIC_DEFAULT_SITE_NAME` is set), proxy in `src/proxy.ts`. Chain order is **fixed:** PreviewProxy → BotTrackingProxy → LocaleProxy → AppRouterMultisiteProxy → RedirectsProxy → PersonalizeProxy. Do not change proxy order.
 
 ### content-sdk-dictionary-and-i18n
 

package/dist/templates/nextjs-app-router-cache-components/copilot-instructions.md

@@ -44,7 +44,8 @@ src/
 ## Library Usage
 
 ### @sitecore-content-sdk
-- Use `SitecoreClient` for content fetching (directly for preview/editing/static-params, indirectly via cache helpers for cached reads)
+- Use `SitecoreClient` for content fetching (directly for preview/editing and `getAppRouterStaticParams` when `scConfig.generateStaticPaths` is true; when false return `BUILD_VALIDATION_SITE` from `src/lib/sitecore-build-validation.ts` for Cache Components build validation; indirectly via cache helpers for cached reads)
+- **Build validation:** `_DEFAULT_` is build-only — skip Edge in page/metadata when `isBuildValidationSite(site)`; segment `not-found.tsx` skips Edge when site is `_DEFAULT_`. Call `setCachedPageParams` before `notFound()` on real routes; read with `getCachedPageParams()` in segment not-found (do not use `headers()` there).
 - Implement proper error handling with try/catch blocks
 - Handle content preview vs. published content scenarios — preview must remain **dynamic** (do not wrap preview in `'use cache'`)
 

package/dist/templates/nextjs-app-router-cache-components/src/app/[site]/[locale]/[[...path]]/not-found.tsx

@@ -2,16 +2,29 @@ import Link from 'next/link';
 import { ErrorPage, getCachedPageParams } from '@sitecore-content-sdk/nextjs';
 import { getSitecoreErrorPage } from 'lib/cache/get-sitecore-error-page';
 import scConfig from 'sitecore.config';
+import { isBuildValidationSite } from 'src/lib/sitecore-build-validation';
 import Layout from 'src/Layout';
 import Providers from 'src/Providers';
 import { NextIntlClientProvider } from 'next-intl';
 import { setRequestLocale } from 'next-intl/server';
 
+const staticNotFound = (
+  <div style={{ padding: 10 }}>
+    <h1>Page not found</h1>
+    <p>This page does not exist.</p>
+    <Link href="/">Go to the Home page</Link>
+  </div>
+);
+
 export default async function NotFound() {
   const { site, locale } = getCachedPageParams();
-  const resolvedSite = site || scConfig.defaultSite;
+  const resolvedSite = (site || scConfig.defaultSite)?.trim();
   const resolvedLocale = locale || scConfig.defaultLanguage;
 
+  if (!resolvedSite || isBuildValidationSite(resolvedSite)) {
+    return staticNotFound;
+  }
+
   const page = await getSitecoreErrorPage({
     site: resolvedSite,
     locale: resolvedLocale,
@@ -32,11 +45,5 @@ export default async function NotFound() {
     );
   }
 
-  return (
-    <div style={{ padding: 10 }}>
-      <h1>Page not found</h1>
-      <p>This page does not exist.</p>
-      <Link href="/">Go to the Home page</Link>
-    </div>
-  );
+  return staticNotFound;
 }

package/dist/templates/nextjs-app-router-cache-components/src/app/[site]/[locale]/[[...path]]/page.tsx

@@ -1,4 +1,5 @@
 import { isDesignLibraryPreviewData } from '@sitecore-content-sdk/nextjs/editing';
+import { setCachedPageParams } from '@sitecore-content-sdk/nextjs';
 import { notFound } from 'next/navigation';
 import { draftMode } from 'next/headers';
 <% if (prerender === 'SSG') { -%>
@@ -9,6 +10,7 @@ import scConfig from 'sitecore.config';
 <% } -%>
 import client from 'src/lib/sitecore-client';
 import { getSitecorePage } from 'src/lib/cache/get-sitecore-page';
+import { BUILD_VALIDATION_SITE, isBuildValidationSite } from 'src/lib/sitecore-build-validation';
 import Layout, { RouteFields } from 'src/Layout';
 import Providers from 'src/Providers';
 import { NextIntlClientProvider } from 'next-intl';
@@ -22,10 +24,16 @@ type PageProps = {
 export default async function Page({ params, searchParams }: PageProps) {
   const { site, locale, path } = await params;
 
+  if (isBuildValidationSite(site)) {
+    setCachedPageParams({ site, locale });
+    notFound();
+  }
+
   // Cached fetch first so missing routes can notFound() without dynamic APIs in the ancestor tree.
   const cachedPage = await getSitecorePage({ site, locale, path: path ?? [] });
 
   if (!cachedPage) {
+    setCachedPageParams({ site, locale });
     notFound();
   }
 
@@ -49,6 +57,7 @@ export default async function Page({ params, searchParams }: PageProps) {
 
   // If the page is not found, return a 404
   if (!page) {
+    setCachedPageParams({ site, locale });
     notFound();
   }
 
@@ -71,11 +80,9 @@ export const generateStaticParams = async () => {
       routing.locales.slice()
     );
   }
-  // Next.js 16 requires at least one result
-  // Return a default param for the root page
   return [
     {
-      site: sites[0]?.name || 'default',
+      site: BUILD_VALIDATION_SITE,
       locale: routing.defaultLocale || scConfig.defaultLanguage,
       path: [],
     },
@@ -86,6 +93,10 @@ export const generateStaticParams = async () => {
 export const generateMetadata = async ({ params, searchParams }: PageProps) => {
   const { path, site, locale } = await params;
 
+  if (isBuildValidationSite(site)) {
+    return { title: 'Page' };
+  }
+
   const draft = await draftMode();
 
   let page;

package/dist/templates/nextjs-app-router-cache-components/src/lib/sitecore-build-validation.ts

@@ -0,0 +1,14 @@
+/**
+ * This is a placeholder `[site]` segment used only for Next.js Cache Components build-time validation
+ * when `generateStaticPaths` is false. Not a real Sitecore site — routes using this value
+ * skip Edge fetches and render the static not-found fallback so `next build` can succeed
+ * without a configured default site or content configured in Sitecore AI.
+ * One use case for this is running your application as an editing host when no sites are configured.
+ *
+ * @see https://nextjs.org/docs/messages/empty-generate-static-params
+ */
+export const BUILD_VALIDATION_SITE = '_DEFAULT_' as const;
+
+export function isBuildValidationSite(site: string | undefined): boolean {
+  return site === BUILD_VALIDATION_SITE;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-content-sdk-app",
-  "version": "2.2.0-canary.20260625092313",
+  "version": "2.2.0",
   "description": "Sitecore Content SDK initializer",
   "bin": "./dist/index.js",
   "scripts": {
@@ -38,11 +38,11 @@
     "minimist": "^1.2.8"
   },
   "devDependencies": {
-    "@sitecore-content-sdk/analytics-core": "2.1.1-canary.20260625092313",
-    "@sitecore-content-sdk/cli": "2.2.0-canary.20260625092313",
-    "@sitecore-content-sdk/events": "2.1.1-canary.20260625092313",
-    "@sitecore-content-sdk/nextjs": "2.2.0-canary.20260625092313",
-    "@sitecore-content-sdk/personalize": "2.1.1-canary.20260625092313",
+    "@sitecore-content-sdk/analytics-core": "^2.1.0",
+    "@sitecore-content-sdk/cli": "^2.2.0",
+    "@sitecore-content-sdk/events": "^2.1.0",
+    "@sitecore-content-sdk/nextjs": "^2.2.0",
+    "@sitecore-content-sdk/personalize": "^2.1.0",
     "@stylistic/eslint-plugin": "^5.2.2",
     "@types/chai": "^5.2.2",
     "@types/cross-spawn": "^6.0.6",