@riverbankcms/sdk 0.129.1 → 0.130.0

package/README.md

@@ -340,7 +340,7 @@ When a path might resolve to either a page or a content entry (blog post, produc
 ### Server-Side: loadContent
 
 ```tsx
-import { loadContent, isPageContent, Page } from '@riverbankcms/sdk';
+import { loadContent, isPageContent, MissingSdkThemeError, Page } from '@riverbankcms/sdk/rendering';
 
 export default async function DynamicRoute({ params }) {
   const path = `/${params.slug?.join('/') || ''}`;
@@ -354,6 +354,9 @@ export default async function DynamicRoute({ params }) {
 
   // Pages get rendered with the Page component
   if (isPageContent(content)) {
+    if (!content.theme) {
+      throw new MissingSdkThemeError(content.siteId, 'cms_theme_absent');
+    }
     return <Page {...content} />;
   }
 
@@ -386,6 +389,7 @@ export function DynamicContent({ path }: { path: string }) {
   if (content.error) return <div>Error: {content.error.message}</div>;
 
   if (isPageContentResult(content)) {
+    if (!content.theme) return <div>This site needs a theme before it can be displayed.</div>;
     return <Page page={content.page} theme={content.theme} siteId={content.siteId} resolvedData={content.resolvedData} />;
   }
 
@@ -405,12 +409,15 @@ export function DynamicContent({ path }: { path: string }) {
 Route entries to different components based on their content type:
 
 ```tsx
-import { loadContent, isPageContent, Page } from '@riverbankcms/sdk';
+import { loadContent, isPageContent, MissingSdkThemeError, Page } from '@riverbankcms/sdk/rendering';
 
 export default async function DynamicRoute({ params }) {
   const content = await loadContent({ client, siteId, path: `/${params.slug?.join('/') || ''}` });
 
   if (isPageContent(content)) {
+    if (!content.theme) {
+      throw new MissingSdkThemeError(content.siteId, 'cms_theme_absent');
+    }
     return <Page {...content} />;
   }
 
@@ -2671,7 +2678,9 @@ In this mode the SDK does not resolve, parse, normalize, or build tokens from th
 
 The optional theme-independent wrapper belongs inside `rendering`: use `runtime: { kind: 'responsive-only' }` (the default) for Riverbank's generated responsive utility scope, or `runtime: { kind: 'none' }` when the host owns that too. Do not combine override-only rendering with top-level `themeRuntime`, `theme`, `themes`, or `getTheme`. If you use SDK `Layout` directly, its header and footer must both be custom or disabled. Preview receives the same rendering selection and registry.
 
-The content response still carries a compatibility theme field for now; override-only rendering deliberately ignores it. Wire-level theme nullability is tracked separately in #1290.
+`SiteResponse.theme` is required but nullable: `Theme | null`. A null value means the CMS has no theme; it does not select a rendering mode. Override-only rendering deliberately ignores it. Themed catch-all rendering first prefers explicit `theme`, `themes`, or `getTheme` inputs, then uses the CMS theme. If none resolves, it throws the exported `MissingSdkThemeError` with code `missing_sdk_theme` before theme parsing or token construction.
+
+The nullable contract must be published before the server stops supplying its temporary fallback. Externally pinned hosts must upgrade to this SDK contract and either opt into override-only rendering or provide a real local/CMS theme before that server cutover.
 
 Keep the `server-only` marker at the top of the registry so Next.js turns an accidental Client Component import into a build error. `generateMetadata()` never receives or runs host loaders—even with `customMetadata`—so a normal request does not repeat host queries for metadata and rendering.
 
@@ -3252,27 +3261,32 @@ export { generateMetadata };
 
 ### Production ISR Setup
 
-For production SDK sites, wire the catch-all route to Next ISR and let Riverbank discover published routes at build time. Preview deployments should set `RIVERBANK_PREVIEW_MODE=true`; `getISRConfig()` then returns `revalidate: 0` so draft previews stay dynamic.
+For production SDK sites, wire the catch-all route to Next ISR and let Riverbank discover published routes at build time. Next.js statically analyzes route configuration, so `revalidate` must be a literal rather than a function call or imported constant. Preview deployments should set `RIVERBANK_PREVIEW_MODE=true` and use the SDK preview integration, whose request-bound session handling keeps draft previews dynamic.
 
 ```tsx
 // src/app/[[...slug]]/page.tsx
 import {
   createCatchAllPage,
-  generateAllStaticParams,
-  getISRConfig,
+  createGenerateStaticParams,
 } from '@riverbankcms/sdk/next';
 
 import config from '@/riverbank.config';
 import { blockOverrides } from '@/lib/block-overrides';
 import { getRiverbankClient } from '@/lib/riverbank-client';
 
-export const revalidate = getISRConfig().revalidate;
+// Next.js route config values must remain statically analyzable literals.
+export const revalidate = 300;
 export const dynamicParams = true;
-export { generateAllStaticParams as generateStaticParams };
+export const generateStaticParams = createGenerateStaticParams({
+  getClient: getRiverbankClient,
+  siteId: config.siteId,
+  failureMode: 'throw',
+});
 
 const { Page, generateMetadata } = createCatchAllPage({
   getClient: getRiverbankClient,
   config,
+  searchParamsMode: 'ignore',
   blockOverrides,
 });
 
@@ -3280,7 +3294,12 @@ export default Page;
 export { generateMetadata };
 ```
 
-`generateAllStaticParams()` reads `RIVERBANK_API_KEY`, `RIVERBANK_SITE_ID`, and `NEXT_PUBLIC_DASHBOARD_URL`. By default it falls back to the homepage when route discovery fails, which keeps deploys from publishing an empty static route set silently. For strict production CI, fail the build instead:
+`searchParamsMode: 'ignore'` is required for this ISR shape because Next.js treats
+the page `searchParams` prop as a Dynamic API. Keep the default `dynamic` mode only
+when server-rendered themes, data loaders, redirects, or metadata genuinely depend
+on URL query parameters.
+
+If a site uses the SDK's generic environment variable names, `generateAllStaticParams()` is also available. It reads `RIVERBANK_API_KEY`, `RIVERBANK_SITE_ID`, and `NEXT_PUBLIC_DASHBOARD_URL`. By default it falls back to the homepage when route discovery fails. For strict production CI, fail the build instead:
 
 ```tsx
 import { generateAllStaticParams } from '@riverbankcms/sdk/next';
@@ -3627,7 +3646,7 @@ type CatchAllContext = {
 For maximum customization, skip `createCatchAllPage` and use the underlying helpers:
 
 ```tsx
-import { loadContent, isPageContent, Page } from '@riverbankcms/sdk/rendering';
+import { loadContent, isPageContent, MissingSdkThemeError, Page } from '@riverbankcms/sdk/rendering';
 import { generatePageMetadata } from '@riverbankcms/sdk/metadata';
 
 export default async function CustomPage({ params }) {
@@ -3642,6 +3661,9 @@ export default async function CustomPage({ params }) {
   });
 
   if (isPageContent(content)) {
+    if (!content.theme) {
+      throw new MissingSdkThemeError(content.siteId, 'cms_theme_absent');
+    }
     return <Page {...content} />;
   }