create-content-sdk-app 2.0.0 → 2.0.1

package/dist/templates/nextjs/CLAUDE.md

@@ -1,173 +1,9 @@
-# Claude Code Agent Guide for Sitecore Content SDK Next.js Project
+# Claude Code — Sitecore Content SDK Next.js (Pages Router) App
 
-## Project Purpose and Tech Stack
+At the start of every session, read these files for full project guidance:
 
-This is a **Sitecore Content SDK** application built with **Next.js** and **TypeScript**. The project follows Sitecore best practices for XM Cloud development and provides a modern, performant web application framework.
+1. **`AGENTS.md`** — Canonical source of truth for this app: overview, commands, application structure, middleware, SitecoreClient, catch-all route, i18n, DO/DON'T, guardrails, boundaries
+2. **`.cursor/rules/`** — Coding rules for this template: general, javascript, sitecore, project-setup
+3. **`Skills.md`** and **`.agents/skills/`** — Capability-specific guidance (component registration, data fetching, editing, i18n, etc.) for tools that support the [Agent Skills](https://agentskills.io) standard.
 
-### Key Technologies
-- **Next.js** - React framework with SSR/SSG capabilities
-- **Sitecore Content SDK** - Official SDK for Sitecore XM Cloud integration
-- **TypeScript** - Type-safe JavaScript development
-- **Sitecore XM Cloud** - Headless CMS platform
-- **React** - Component-based UI library
-
-## Coding Standards
-
-### TypeScript Standards
-- Use **strict mode** in tsconfig.json
-- Prefer type assertions over `any`: `value as ContentItem`
-- Use discriminated unions for complex state management
-- Enable strict null checks and strict function types
-
-### Naming Conventions
-- **Variables/Functions**: camelCase (`getUserData()`, `isLoading`, `currentUser`)
-- **Components**: PascalCase (`SitecoreComponent`, `PageLayout`, `ContentBlock`)
-- **Constants**: UPPER_SNAKE_CASE (`API_ENDPOINT`, `DEFAULT_TIMEOUT`)
-- **Directories**: kebab-case (`src/components`, `src/api-clients`)
-- **Types/Interfaces**: PascalCase (`ContentItem`, `LayoutProps`, `SitecoreConfig`)
-
-### Modular Layout
-```
-src/
-  components/          # UI components (React)
-  lib/                 # Configuration and utilities
-  pages/               # Next.js pages
-  assets/              # Static assets and styles
-  types/               # TypeScript type definitions
-  hooks/               # Custom React hooks
-```
-
-## Library Usage
-
-### @sitecore-content-sdk
-- Use `SitecoreClient` for content fetching
-- Implement proper error handling with try/catch blocks
-- Cache API responses using React Query or SWR
-- Handle content preview vs. published content scenarios
-
-```typescript
-import { SitecoreClient } from '@sitecore-content-sdk/nextjs/client';
-import scConfig from 'sitecore.config';
-
-const client = new SitecoreClient({
-  ...scConfig,
-});
-```
-
-### React Patterns
-- Use **Server Components** for data fetching and static content
-- Use **Client Components** for interactivity (use 'use client')
-- Implement proper error boundaries
-- Use React.memo for expensive components
-- Leverage useCallback and useMemo for performance optimization
-
-### Sitecore Field Components
-- Always use Sitecore field components: `<Text>`, `<RichText>`, `<Image>`
-- Validate field existence before rendering
-- Handle empty/null fields gracefully
-- Prefer Sitecore field components over manual rendering
-
-```typescript
-// Good: Using Sitecore field components
-<Text field={fields?.title} tag="h1" />
-<RichText field={fields?.content} />
-<Image field={fields?.backgroundImage} />
-
-// Avoid: Manual field value extraction unless necessary
-```
-
-## Example Patterns and Prompts
-
-### Component Development
-```typescript
-// Component props interface
-interface HeroProps {
-  fields: {
-    title: Field;
-    subtitle: Field;
-    backgroundImage: Field;
-  };
-}
-
-export default function Hero({ fields }: HeroProps) {
-  return (
-    <div>
-      <Text field={fields?.title} tag="h1" />
-      <Text field={fields?.subtitle} tag="p" />
-      <Image field={fields?.backgroundImage} />
-    </div>
-  );
-}
-```
-
-### Error Handling
-```typescript
-async function fetchPageData(path: string): Promise<Page | null> {
-  if (!path) {
-    throw new Error('Page path is required');
-  }
-
-  try {
-    const pageData = await client.getPage(path);
-    return pageData;
-  } catch (error) {
-    throw new SitecoreFetchError(`Failed to fetch page data for ${path}`, error);
-  }
-}
-```
-
-### Configuration
-```typescript
-// sitecore.config.ts
-import { defineConfig } from '@sitecore-content-sdk/nextjs/config';
-
-export default defineConfig({
-  api: {
-    edge: {
-      contextId: process.env.SITECORE_EDGE_CONTEXT_ID || '',
-      clientContextId: process.env.NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID,
-      edgeUrl:
-        process.env.NEXT_PUBLIC_SITECORE_EDGE_PLATFORM_HOSTNAME ||
-        process.env.SITECORE_EDGE_PLATFORM_HOSTNAME ||
-        'https://edge-platform.sitecorecloud.io',
-    },
-    local: {
-      apiKey: process.env.SITECORE_API_KEY || '',
-      apiHost: process.env.SITECORE_API_HOST || '',
-    },
-  },
-  defaultSite: process.env.NEXT_PUBLIC_DEFAULT_SITE_NAME || 'default',
-  defaultLanguage: process.env.NEXT_PUBLIC_DEFAULT_LANGUAGE || 'en',
-  editingSecret: process.env.SITECORE_EDITING_SECRET,
-});
-```
-
-## Development Workflow
-
-1. **Install dependencies**: `npm install`
-2. **Configure environment**: Copy `.env.example` to `.env.local`
-3. **Start development**: `npm run dev`
-4. **Build for production**: `npm run build`
-
-## Best Practices
-
-### Performance
-- Optimize images using Next.js Image component
-- Implement proper loading states
-- Cache expensive operations appropriately
-- Consider server-side rendering implications
-- Lazy-load non-critical modules
-
-### Security
-- Sanitize user inputs before processing
-- Validate data at application boundaries
-- Use HTTPS for all Sitecore connections
-- Never expose sensitive configuration in client-side code
-- Escape content when rendering to prevent XSS
-
-### Code Quality
-- Follow DRY principle - extract common functionality
-- Use SOLID principles for maintainable code
-- Write self-documenting code with clear intent
-- Implement proper error boundaries
-- Test behavior, not implementation details
+This file applies to **this scaffolded head application only**. For the Content SDK monorepo (packages, CLI, templates source), use that repo's root `AGENTS.md` and `.cursor/rules/`.

package/dist/templates/nextjs/Skills.md

@@ -0,0 +1,79 @@
+# Skills.md — Capability groupings for this app (Next.js Pages Router)
+
+This file describes **this application** in terms of **capability-style groupings**: high-level areas that help AI tools and developers map tasks to the right part of the app. This is a Pages Router app with `pages/[[...path]].tsx`, Next.js i18n, and a single component map. For concrete steps and patterns, see [AGENTS.md](AGENTS.md) and the [official Content SDK documentation](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html).
+
+**Agent Skills:** Each grouping is also available as a skill in [.agents/skills/](.agents/skills/) in the standard [Agent Skills](https://agentskills.io) format (`SKILL.md` per capability). Tools that support this standard load skills from `.agents/skills/`; Cursor's built-in skills use `.cursor/skills/` unless it also supports the Agent Skills standard. The skills here are tailored for **Pages Router** (e.g. extractPath, context.locale, getComponentData, single component-map.ts).
+
+---
+
+## Why capability grouping
+
+Grouping related capabilities makes it easier to know which area of the app applies to a given task and to point to the right docs and patterns. Map the task to one or more of the groupings below; use AGENTS.md and the official docs for concrete steps.
+
+---
+
+## Capability groupings
+
+### content-sdk-component-scaffold
+
+Creating new Sitecore components: file structure, props interface, and placement under `src/components/`. Use when adding a new component from scratch. Register in `.sitecore/component-map.ts`.
+
+### content-sdk-component-registration
+
+Registering components in `.sitecore/component-map.ts` only. Required so layout and editing can resolve and render components. Used by getComponentData and editing API routes. Pages Router has a single map.
+
+### content-sdk-editing-safe-rendering
+
+Safe rendering in XM Cloud editing and preview: `context.preview` and `context.previewData`, editing chromes, and design library. Use when ensuring components work in the Sitecore editor and preview. Use `client.getPreview(context.previewData)` or `client.getDesignLibraryData(context.previewData)` when in preview.
+
+### content-sdk-field-usage-image-link-text
+
+Using SDK field components: `<Text>`, `<RichText>`, `<Image>`, `<Link>`, with proper validation and fallbacks. Use when rendering Sitecore fields.
+
+### content-sdk-graphql-data-fetching
+
+Page, dictionary, and component data via the single Sitecore client in `src/lib/sitecore-client.ts`. Use `getPage(path, { locale: context.locale })`, then `getDictionary({ site: page.siteName, locale: page.locale })` and `getComponentData(page.layout, context, components)`. For SSG use `getPagePaths(sites, context?.locales)`.
+
+### content-sdk-route-configuration
+
+Routing: single catch-all at `src/pages/[[...path]].tsx`. Path from `extractPath(context)`; locale from `context.locale`. Layout and page data flow via getStaticProps/getServerSideProps to _app and Layout.tsx. No [site]/[locale] in path; site resolved by middleware.
+
+### content-sdk-site-setup-and-env
+
+Site and environment: `sitecore.config.ts`, environment variables, default site and language. Document vars in `.env.example` only; never commit `.env` or `.env.local`.
+
+### content-sdk-multisite-management
+
+Multisite: `.sitecore/sites.json`, proxy in `src/proxy.ts`. Chain order is **fixed:** MultisiteProxy → RedirectsProxy → PersonalizeProxy. Do not change proxy order.
+
+### content-sdk-dictionary-and-i18n
+
+Dictionary and i18n: Next.js i18n in `next.config.js` (i18n.locales, defaultLocale). Per-request locale is `context.locale` in getStaticProps/getServerSideProps. Fetch dictionary with `client.getDictionary({ site: page.siteName, locale: page.locale })` after getPage.
+
+### content-sdk-sitemap-robots
+
+Sitemap and robots: `src/pages/api/sitemap.ts` and `src/pages/api/robots.ts` with `SitemapMiddleware(scClient, sites).getHandler()` and `RobotsMiddleware(scClient, sites).getHandler()`. Rewrites in next.config.js for /sitemap*.xml and /robots.txt.
+
+### content-sdk-component-variants
+
+Component variants: different renderings or data-driven variants of the same component type. Use when one component has multiple presentations. Register in `.sitecore/component-map.ts`; getComponentData resolves props.
+
+### content-sdk-troubleshoot-editing
+
+Troubleshooting XM Cloud editing, preview, and design library. Use when editing or preview does not behave as expected. Check context.preview, context.previewData, and editing API routes (config, render, feaas/render).
+
+### content-sdk-upgrade-assistant
+
+Upgrading @sitecore-content-sdk/* packages: version bumps, breaking changes, migration steps. Use when moving to a newer SDK version. Check the Content SDK repo CHANGELOG and upgrade guides.
+
+### content-sdk-component-data-strategy
+
+Component data: after getPage, use `client.getComponentData(page.layout, context, components)` to resolve component props; pass result to layout renderer. All Sitecore-driven component data goes through this flow. BYOC must be registered in `.sitecore/component-map.ts`.
+
+---
+
+## How to use this
+
+Map the task to one or more groupings above. Use [AGENTS.md](AGENTS.md) for app-level instructions and the [official documentation](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html) for APIs.
+
+**If your tool supports Agent Skills:** Load skills from [.agents/skills/](.agents/skills/) (one folder per capability). They provide when-to-use, hard rules, and stop conditions tailored for this Pages Router app.

package/dist/templates/nextjs/package.json

@@ -22,9 +22,9 @@
   },
   "license": "Apache-2.0",
   "dependencies": {
-    "@sitecore-cloudsdk/core": "^0.5.1",
-    "@sitecore-cloudsdk/events": "^0.5.1",
     "@sitecore-content-sdk/nextjs": "<%- version %>",
+    "@sitecore-content-sdk/analytics-core": "<%- version %>",
+    "@sitecore-content-sdk/events": "<%- version %>",
     "@sitecore-feaas/clientside": "^0.6.0",
     "@sitecore/components": "~2.1.0",
     "next": "^16.1.1",

package/dist/templates/nextjs/src/Bootstrap.tsx

@@ -1,8 +1,8 @@
 import { useEffect, JSX } from 'react';
-import { CloudSDK } from '@sitecore-cloudsdk/core/browser';
-import { SitecorePageProps } from '@sitecore-content-sdk/nextjs';
-import '@sitecore-cloudsdk/events/browser';
+import { SitecorePageProps, initContentSdk } from '@sitecore-content-sdk/nextjs';
 import config from 'sitecore.config';
+import { eventsPlugin } from '@sitecore-content-sdk/events';
+import { analyticsBrowserAdapter, analyticsPlugin } from '@sitecore-content-sdk/analytics-core';
 
 /**
  * The Bootstrap component is the entry point for performing any initialization logic
@@ -26,16 +26,23 @@ const Bootstrap = (props: SitecorePageProps): JSX.Element | null => {
       console.debug('Browser Events SDK is not initialized in edit and preview modes');
     } else {
       if (config.api.edge?.clientContextId) {
-        CloudSDK({
-          sitecoreEdgeUrl: config.api.edge.edgeUrl,
-          sitecoreEdgeContextId: config.api.edge.clientContextId,
-          siteName: page.siteName || config.defaultSite,
-          enableBrowserCookie: true,
-          // Replace with the top level cookie domain of the website that is being integrated e.g ".example.com" and not "www.example.com"
-          cookieDomain: window.location.hostname.replace(/^www\./, ''),
-        })
-          .addEvents()
-          .initialize();
+        initContentSdk({
+          config: {
+            contextId: config.api.edge.clientContextId,
+            edgeUrl: config.api.edge.edgeUrl,
+            siteName: page.siteName || config.defaultSite,
+          },
+          plugins: [
+            analyticsPlugin({
+              options: {
+                enableCookie: true,
+                cookieDomain: window.location.hostname.replace(/^www\./, ''),
+              },
+              adapter: analyticsBrowserAdapter(),
+            }),
+            eventsPlugin(),
+          ],
+        });
       } else {
         console.error('Client Edge API settings missing from configuration');
       }

package/dist/templates/nextjs/src/byoc/index.tsx

@@ -1,6 +1,6 @@
 import React, { JSX } from 'react';
 import * as FEAAS from '@sitecore-feaas/clientside/react';
-import * as Events from '@sitecore-cloudsdk/events/browser';
+import * as Events from '@sitecore-content-sdk/events';
 import { LayoutServicePageState, SitecoreProviderReactContext } from '@sitecore-content-sdk/nextjs';
 import '@sitecore/components/context';
 import dynamic from 'next/dynamic';

package/dist/templates/nextjs/src/components/content-sdk/CdpPageView.tsx

@@ -1,6 +1,6 @@
 import { CdpHelper, useSitecore } from '@sitecore-content-sdk/nextjs';
 import { useEffect, JSX } from 'react';
-import { pageView } from '@sitecore-cloudsdk/events/browser';
+import { pageView } from '@sitecore-content-sdk/events';
 import config from 'sitecore.config';
 
 /**

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

@@ -0,0 +1,37 @@
+---
+name: content-sdk-component-data-strategy
+description: Component data for App Router: layout data from getPage (or getPreview/getDesignLibraryData in editing). No getComponentData; pass site and locale from route params. Server Components use the client in server context; Client Components receive serializable props. Use when wiring component data or BYOC.
+---
+
+# Content SDK Component Data Strategy (App Router)
+
+This app does **not** use getComponentData. Page and layout data come from **getPage** (or getPreview/getDesignLibraryData in editing). Component props are derived from the layout/placeholders; pass site and locale from route params.
+
+## When to Use
+
+- User asks how to pass data to components, wire component props, or integrate custom/BYOC components.
+- Task involves component props, server vs client components, or BYOC.
+- User mentions "component data," "props," "BYOC," "server component," or "client component."
+
+## How to perform
+
+- Fetch at page/layout with getPage (or getPreview/getDesignLibraryData in draft). Pass site and locale from route params. Server Components use the client in server context; Client Components receive serializable props only. Register BYOC in the correct component map and pass props from layout.
+
+## Hard Rules
+
+- **Data source:** Page and layout from `client.getPage(path ?? [], { site, locale })` in the catch-all page (or getPreview/getDesignLibraryData when draftMode() is enabled). All Sitecore-driven data flows from this single fetch at the route level.
+- **Server Components:** Use the same SitecoreClient in server context (e.g. in the page or layout). Pass data as props to children.
+- **Client Components:** Receive **serializable** props from parent (no functions or non-serializable values). Do not create a new client inside components. Pass data from page/layout level into components.
+- **BYOC or custom components:** Must be registered in the appropriate component map (.sitecore/component-map.ts or component-map.client.ts) and receive props in the shape the layout expects (e.g. fields, params).
+- Do not fetch layout or page data inside a child component (e.g. another getPage call); fetch at page/layout level and pass props.
+
+## Stop Conditions
+
+- Stop if the user wants to fetch page/layout data inside a child component; recommend fetching at page/layout level and passing props.
+- Stop if server/client boundary is ambiguous and the change could cause "use client" or serialization issues; clarify and follow Next.js and app conventions.
+- Do not introduce getComponentData or duplicate getPage logic; this app uses getPage-only data flow.
+
+## References
+
+- content-sdk-graphql-data-fetching and [AGENTS.md](../../../AGENTS.md) for getPage and data flow.
+- [Official Content SDK docs](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html).

package/dist/templates/nextjs-app-router/.agents/skills/content-sdk-component-registration/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: content-sdk-component-registration
+description: Registers Sitecore components in the component map so layout and editing can resolve them. App Router uses .sitecore/component-map.ts (Server) and .sitecore/component-map.client.ts (Client). Use when registering a new component or when layout/editor cannot find a component.
+---
+
+# Content SDK Component Registration (App Router)
+
+Register components in the Sitecore component maps so the layout and editing pipeline can resolve and render them. This app has **two** maps: server and client.
+
+## When to Use
+
+- After scaffolding or adding a new Sitecore component (must be registered).
+- User reports a component not rendering, "component not found," or layout/placeholder showing raw component name.
+- Task involves `.sitecore/component-map.ts` or `.sitecore/component-map.client.ts`.
+- User asks how to register a component or fix component resolution.
+
+## How to perform
+
+- Open `.sitecore/component-map.ts` (Server) or `.sitecore/component-map.client.ts` (Client). Add an entry mapping the layout component name to the React component import. Keep keys consistent with layout and existing map entries.
+
+## Hard Rules
+
+- Every component rendered from Sitecore layout must be registered. Keep the maps in sync with `src/components/`.
+- **Server components** (no `'use client'`): Register in `.sitecore/component-map.ts` only.
+- **Client components** (`'use client'`): Register in `.sitecore/component-map.client.ts` only. Editing API routes use both maps (e.g. `clientComponents` from the client map).
+- Use consistent component names (same key in map as used in layout). Follow existing naming in the maps.
+- Do not remove or rename registrations without updating all references (layout, editing routes).
+
+## Stop Conditions
+
+- Stop if it is unclear whether the new component is Server or Client; ask or follow app convention.
+- Stop if modifying the maps would break existing layout or editing; suggest a safe change or ask for confirmation.
+- Do not edit `.sitecore/metadata.json` or import-map unless the task explicitly requires it.
+
+## References
+
+- [AGENTS.md](../../../AGENTS.md) for component maps and editing routes.
+- [Official Content SDK docs](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html).

package/dist/templates/nextjs-app-router/.agents/skills/content-sdk-component-scaffold/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: content-sdk-component-scaffold
+description: Creates new Sitecore components with correct file structure, props interface, and placement under src/components/. Use when adding a new component from scratch or scaffolding a component. App Router: decide Server vs Client and register in the appropriate map.
+---
+
+# Content SDK Component Scaffold (App Router)
+
+Scaffold new Sitecore components so they integrate with the layout and editing pipeline. This app uses App Router with separate server and client component maps.
+
+## When to Use
+
+- User asks to add a new Sitecore component, create a component from scratch, or scaffold a component.
+- Task involves creating a new React component that will be rendered from Sitecore layout/placeholders.
+- User mentions "new component," "add component," or "component file structure."
+
+## How to perform
+
+- Create a new file under `src/components/` (or existing feature folder). Define props (fields, params), export a single default component.
+- Decide Server vs Client: default Server; add `'use client'` only if the component needs hooks or event handlers.
+- Register the component in the correct map (content-sdk-component-registration). Run `npm run build` to verify.
+
+## Hard Rules
+
+- Place components under `src/components/`. Use existing folder conventions.
+- Define a props interface with the component's fields (e.g. `fields: { title: Field; ... }`) and any params. Use types from `@sitecore-content-sdk/react` or the app's types.
+- Export a single default component; one component per file unless the app pattern differs.
+- **Server vs Client:** Use Server Components by default. Add `'use client'` only for interactivity (hooks, event handlers). Register Server components in `.sitecore/component-map.ts`; Client components in `.sitecore/component-map.client.ts`.
+- After creating the component file, register it in the correct component map (see content-sdk-component-registration). Do not leave the component unregistered.
+
+## Stop Conditions
+
+- Stop and ask if the component should be a Server or Client Component when the app does not have a clear convention.
+- Do not create components in `.next/`, `node_modules/`, or build output.
+
+## References
+
+- [AGENTS.md](../../../AGENTS.md) for app structure and component maps.
+- [Skills.md](../../../Skills.md) for capability map. [Official Content SDK docs](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html).

package/dist/templates/nextjs-app-router/.agents/skills/content-sdk-component-variants/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: content-sdk-component-variants
+description: Implements component variants: different renderings or data-driven variants of the same component type. App Router: register in component-map.ts or component-map.client.ts as appropriate. Use when one component has multiple presentations.
+---
+
+# Content SDK Component Variants (App Router)
+
+One component definition can have multiple presentations or data-driven variants. Keep registration and layout aligned. This app does not use getComponentData; layout/placeholder data comes from getPage.
+
+## When to Use
+
+- User asks for different "variants," "versions," or "presentations" of a component.
+- Task involves rendering the same component type with different layouts or props based on data (e.g. variant field or style).
+- User mentions "component variants," "variations," or "multiple renderings."
+
+## How to perform
+
+- Prefer one component that accepts variant/style via props and branches internally; or multiple map entries if the app pattern uses one key per variant. Use layout/fields/params for variant; register in the correct component map (Server or Client). Align with existing app convention.
+
+## Hard Rules
+
+- Prefer a single component registration that accepts variant/style data (e.g. params or fields) and branches internally, over multiple map entries for the same logical component unless the app pattern uses separate registrations per variant.
+- Use props (fields, params) from layout to decide variant; do not rely on global state or URL for variant selection when data comes from Sitecore.
+- Register in `.sitecore/component-map.ts` (Server) or `.sitecore/component-map.client.ts` (Client) as appropriate. If the app uses one key per variant, register each; if one key with variant param, single registration. Follow existing app convention.
+- Keep component maps in sync with src/components/.
+
+## Stop Conditions
+
+- Stop if the variant model (one registration vs many) is unclear; ask or follow the app's existing pattern.
+- Do not add new component map entries without ensuring layout and editing can provide the corresponding data.
+- Do not assume variant field names (e.g. "variant," "style") without checking the layout definition.
+
+## References
+
+- [AGENTS.md](../../../AGENTS.md) and content-sdk-component-registration for maps.
+- [Official Content SDK docs](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html).

package/dist/templates/nextjs-app-router/.agents/skills/content-sdk-dictionary-and-i18n/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: content-sdk-dictionary-and-i18n
+description: Dictionary and i18n for App Router: next-intl with src/i18n/routing.ts and request.ts. Request locale is site_locale; call setRequestLocale in the page; in request.ts parse and load dictionary with client.getDictionary. Use when adding or changing translated content or locale behavior.
+---
+
+# Content SDK Dictionary and i18n (App Router)
+
+This app uses **next-intl**. Locale is in the URL as [locale]. Request locale is encoded as `${site}_${locale}` for next-intl.
+
+## When to Use
+
+- User asks to add or change translated content, locale, or dictionary.
+- Task involves getDictionary, next-intl, or locale in URL/request.
+- User mentions "dictionary," "i18n," "locale," "translation," or "next-intl."
+
+## How to perform
+
+- Locales and routing: `src/i18n/routing.ts`. Request config: `src/i18n/request.ts` — parse `requestLocale` (e.g. `${site}_${locale}`), call `client.getDictionary({ locale, site })`, return `{ locale, messages }`. In the page, call `setRequestLocale(\`${site}_${locale}\`)` at the top. Use a single getDictionary per request.
+
+## Hard Rules
+
+- **Config:** `src/i18n/routing.ts` — `defineRouting({ locales, defaultLocale, localePrefix })`. Align `locales` with Sitecore languages (e.g. from sitecore.config.ts defaultLanguage).
+- **Request config:** `src/i18n/request.ts` — `getRequestConfig` receives `requestLocale`. This app uses `${site}_${locale}` (set by `setRequestLocale(\`${site}_${locale}\`)` in the page). Parse requestLocale (e.g. `split('_')`) to get site and locale; load dictionary with `client.getDictionary({ locale, site })` and return `{ locale, messages }`.
+- **In the page:** Call `setRequestLocale(\`${site}_${locale}\`)` at the **top** of the page so next-intl and request config see the correct locale. Do not omit when adding new page branches.
+- **Do not** change the `${site}_${locale}` convention without updating request.ts and all pages that call setRequestLocale.
+- Use a single client.getDictionary per request for the active site/locale. Never assume locale from headers or global state; use route params (site, locale).
+
+## Stop Conditions
+
+- Stop if the user wants to change to a different encoding for requestLocale; this affects request.ts and all setRequestLocale call sites.
+- Stop if adding a new locale without confirming it exists in Sitecore and in routing.ts.
+- Do not duplicate dictionary fetching (e.g. in layout and page) without a clear need.
+
+## References
+
+- [AGENTS.md](../../../AGENTS.md) for next-intl, setRequestLocale, and getDictionary usage.
+- [Official Content SDK docs](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html).

package/dist/templates/nextjs-app-router/.agents/skills/content-sdk-editing-safe-rendering/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: content-sdk-editing-safe-rendering
+description: Ensures components render safely in XM Cloud editing and preview. App Router uses draftMode() and getPreview/getDesignLibraryData from searchParams. Use when making components work in the Sitecore editor or fixing preview/editing behavior.
+---
+
+# Content SDK Editing-Safe Rendering (App Router)
+
+Ensure components behave correctly in XM Cloud editing, preview, and design library. This app uses **draftMode()** and **searchParams** for editing data.
+
+## When to Use
+
+- User asks about editing, preview, design library, or "component not working in editor."
+- Task involves draft mode, editing chromes, or design library integration.
+- Fixing issues where components render differently or break in editor vs published.
+- User mentions getPreview, getDesignLibraryData, or editing API routes.
+
+## How to perform
+
+- In the page or layout: call `draftMode()`; when enabled, read editing params from searchParams, use `isDesignLibraryPreviewData(editingParams)` to choose getDesignLibraryData vs getPreview; otherwise use getPage. Editing routes: config route uses `createEditingConfigRouteHandler`, render route uses `createEditingRenderRouteHandlers`; set `dynamic = 'force-dynamic'` on both.
+
+## Hard Rules
+
+- Use `draftMode()` in Server Components (e.g. in the page or [site] layout). When `draft.isEnabled`, get editing params from **searchParams** and use `isDesignLibraryPreviewData(editingParams)` to distinguish: if true, use `client.getDesignLibraryData(editingParams)`; otherwise use `client.getPreview(editingParams)`. When not in draft mode, use `getPage(path ?? [], { site, locale })`.
+- Do not assume editing/preview context in components that might run in static or non-editing contexts; guard on `draftMode()`.
+- Editing API routes: `src/app/api/editing/config/route.ts` uses `createEditingConfigRouteHandler({ components, clientComponents, metadata })` (import from `.sitecore/component-map`, `.sitecore/component-map.client`, `.sitecore/metadata.json`). `src/app/api/editing/render/route.ts` uses `createEditingRenderRouteHandlers({})`. Set `export const dynamic = 'force-dynamic'` on both. Do not duplicate client creation; config and render routes use the same component maps as the app.
+- Never commit editing secrets; use environment variables and document in .env.example only.
+
+## Stop Conditions
+
+- Stop and clarify if the issue is preview vs design library vs published; behavior differs.
+- Do not change proxy or middleware order to "fix" editing; editing is driven by API routes and draft/preview data.
+- Do not recommend disabling secret validation without explicit user request and warning.
+
+## References
+
+- [AGENTS.md](../../../AGENTS.md) for data fetching, preview flow, and editing routes.
+- [Official Content SDK docs](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html).

package/dist/templates/nextjs-app-router/.agents/skills/content-sdk-field-usage-image-link-text/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: content-sdk-field-usage-image-link-text
+description: Renders Sitecore fields using SDK field components (Text, RichText, Image, Link) with proper validation and fallbacks. Use when rendering content fields or when the user mentions Text, RichText, Image, Link, or field components.
+---
+
+# Content SDK Field Usage (App Router)
+
+Use SDK field components to render Sitecore fields with proper validation and fallbacks.
+
+## When to Use
+
+- User asks how to render a title, body, image, or link from Sitecore.
+- Task involves displaying content fields, fixing empty/broken images or links, or using RichText/Text/Image/Link components.
+- User mentions "field," "Image," "Link," "Text," "RichText," or "field value."
+
+## How to perform
+
+- Use SDK field components: `<Text field={fields?.title} />`, `<RichText field={fields?.content} />`, `<Image field={fields?.image} />`, `<Link field={fields?.link} />`. Guard with `fields?.` when optional; use tag prop on Text when needed. Do not hardcode media or link URLs from Sitecore.
+
+## Hard Rules
+
+- Prefer SDK field components over manual field value extraction: `<Text field={fields?.title} />`, `<RichText field={fields?.content} />`, `<Image field={fields?.image} />`, `<Link field={fields?.link} />`. Use tag prop for Text when needed (e.g. tag="h1").
+- Validate or guard field existence before rendering when fields can be optional (e.g. `fields?.title`). Handle null/undefined and empty fields gracefully.
+- Do not hardcode image or link URLs when the data comes from Sitecore; use the field components or helpers that resolve media/URLs.
+- Follow the app's import pattern (e.g. from lib or components).
+
+## Stop Conditions
+
+- Stop if the field structure (name or type) is unknown; suggest checking the layout/data shape or asking the user.
+- Do not assume field names (e.g. "title") without confirmation when the template might use different names.
+- Do not commit or log raw field values that might contain PII or secrets.
+
+## References
+
+- [AGENTS.md](../../../AGENTS.md) for component and Sitecore patterns.
+- [Official Content SDK docs](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html).

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

@@ -0,0 +1,37 @@
+---
+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.
+---
+
+# Content SDK GraphQL Data Fetching (App Router)
+
+All Sitecore data fetching goes through the single client in `src/lib/sitecore-client.ts`. Use getPage, getDictionary, and related methods correctly. This app does **not** use getComponentData; layout data comes from getPage.
+
+## When to Use
+
+- User asks how to fetch page data, layout, or dictionary phrases.
+- Task involves getPage, getDictionary, getErrorPage, getPreview, getDesignLibraryData, or getAppRouterStaticParams.
+- User mentions "sitecore client," "Layout Service," "page data," or "dictionary."
+
+## 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.
+
+## Hard Rules
+
+- Use the single SitecoreClient instance in `src/lib/sitecore-client.ts`. Do not create a second client or instantiate SitecoreClient elsewhere.
+- 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: [] }`).
+- Config for the client comes from `sitecore.config.ts`; use environment variables, never hardcode secrets.
+
+## Stop Conditions
+
+- Stop if the task requires moving the client to another folder without clear requirement; suggest keeping a single instance in lib.
+- Do not add direct GraphQL or fetch to Layout Service bypassing the client unless the task explicitly requires it.
+
+## References
+
+- [AGENTS.md](../../../AGENTS.md) for SitecoreClient, getPage, getDictionary, and SSG.
+- [Official Content SDK docs](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html).