create-content-sdk-app 2.0.0 → 2.0.2-canary.0

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

@@ -1,274 +1,9 @@
-# Claude Code Agent Guide for Sitecore Content SDK Next.js App Router Project
+# Claude Code — Sitecore Content SDK Next.js (App 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 App Router** and **TypeScript**. The project follows Sitecore best practices for XM Cloud development and leverages the latest Next.js App Router features for improved performance and developer experience.
+1. **`AGENTS.md`** — Canonical source of truth for this app: overview, commands, App Router structure, middleware, SitecoreClient, [site]/[locale]/[[...path]], next-intl, DO/DON'T, guardrails, boundaries
+2. **`.cursor/rules/`** — Coding rules for this template: general, javascript, sitecore, app-router-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 App Router** - React framework with Server Components and modern routing
-- **Sitecore Content SDK** - Official SDK for Sitecore XM Cloud integration
-- **TypeScript** - Type-safe JavaScript development
-- **Sitecore XM Cloud** - Headless CMS platform
-- **React Server Components** - Server-side rendering for better performance
-- **next-intl** - Internationalization support
-
-## 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 (App Router)
-```
-src/
-  app/                 # App Router pages and layouts
-  components/          # UI components (React)
-  lib/                 # Configuration and utilities
-  i18n/                # Internationalization setup
-  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 App Router Patterns
-- Use **Server Components** for data fetching and static content (default)
-- Use **Client Components** for interactivity (use 'use client' directive)
-- Implement proper error boundaries with error.tsx
-- Use loading.tsx for loading states
-- Leverage layout.tsx for shared page structure
-
-### 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
-
-### Server Component Development
-```typescript
-// Server Component example (default in App Router)
-import { SitecoreClient } from '@sitecore-content-sdk/nextjs/client';
-import scConfig from 'sitecore.config';
-
-const client = new SitecoreClient({
-  ...scConfig,
-});
-
-export default async function SitecorePage({ params }: { params: { path: string[] } }) {
-  try {
-    const pageData = await client.getPage(params.path.join('/'));
-    return <SitecoreLayout layoutData={pageData?.layout} />;
-  } catch (error) {
-    return <div>Content not found</div>;
-  }
-}
-```
-
-### Client Component Integration
-
-Interactive Sitecore Components:
-
-- Use 'use client' directive when needed
-- Keep client components focused on interactivity
-- Pass server-fetched data as props
-- Handle hydration mismatches carefully
-
-```typescript
-'use client';
-
-interface InteractiveSitecoreComponentProps {
-  fields: {
-    title: Field;
-    content: Field;
-  };
-}
-
-export default function InteractiveSitecoreComponent({
-  fields,
-}: InteractiveSitecoreComponentProps) {
-  // Client-side interactivity here
-  return (
-    <div>
-      <Text field={fields?.title} tag="h2" />
-      <RichText field={fields?.content} />
-    </div>
-  );
-}
-```
-
-### 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
-
-API Calls:
-
-- Always wrap in try/catch blocks
-- Throw custom errors with context: `SitecoreFetchError`, `ConfigurationError`
-- Handle edge cases with guard clauses
-
-```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,
-});
-```
-
-### Internationalization
-
-Multi-language Support:
-
-- Configure next-intl for language routing
-- Handle Sitecore language contexts
-- Implement language switching
-- Use proper locale-based data fetching
-
-```typescript
-// Language-aware data fetching
-import { getTranslations } from 'next-intl/server';
-
-export default async function LocalizedPage() {
-  const t = await getTranslations('common');
-  // Fetch Sitecore content for current locale
-}
-```
-
-## 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`
-
-## App Router Best Practices
-
-### Server vs Client Components
-- Use Server Components for Sitecore content rendering (default)
-- Use Client Components for user interactions
-- Minimize client-side JavaScript
-- Leverage server-side data fetching
-
-### Routing and Layouts
-- Use layout.tsx for shared page structure
-- Implement loading.tsx for loading states
-- Create error.tsx for error boundaries
-- Use page.tsx for route content
-- Use [...path] for Sitecore catch-all routes
-
-### Performance Optimization
-- Leverage Server Components for better performance
-- Use streaming for improved loading experience
-- Implement proper caching strategies
-- Optimize images with Next.js Image component
-
-## 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
-- Use Server Components for better performance
-
-### 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-app-router/README.md

@@ -5,39 +5,3 @@
 -->
 
 [Documentation](https://doc.sitecore.com/xmc/en/developers/xm-cloud/sitecore-javascript-rendering-sdk--jss--for-next-js.html)
-
-## Next.js Cache Components
-
-Cache Components is **disabled by default** in this template. To enable it:
-
-1. **Enable in `next.config.ts`**:
-   ```typescript
-   const nextConfig: NextConfig = {
-     cacheComponents: true,
-     // ... rest of config
-   };
-   ```
-
-2. **Add uncached data access** in all server components that call client methods:
-   
-   Next.js 16 with Cache Components requires accessing uncached data (`draftMode()`, `cookies()`, `headers()`, or `searchParams`) before any operations that might use `new Date()` or other time-related functions.
-   
-   Example:
-   ```typescript
-   export default async function Page({ params, searchParams }: PageProps) {
-     // Access uncached data first
-     await draftMode();
-     
-     const { site, locale, path } = await params;
-     // ... rest of component
-   }
-   ```
-   
-   Apply this pattern to:
-   - Page components that call `client.getPage()`, `client.getPreview()`, etc.
-   - `generateMetadata` functions
-   - Layout components that call client methods
-   - Not-found handlers
-   - Any server component calling Sitecore client methods
-
-3. **See the sample app** (`samples/nextjs-app-router`) for a working example with Cache Components enabled.

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

@@ -0,0 +1,79 @@
+# Skills.md — Capability groupings for this app (Next.js App 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 an App Router app with `[site]`/`[locale]` segments, next-intl, and separate server/client component maps. 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 **App Router** (e.g. setRequestLocale, draftMode(), component-map.ts + component-map.client.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. In App Router, decide Server vs Client and register in the appropriate map.
+
+### content-sdk-component-registration
+
+Registering components in `.sitecore/component-map.ts` (Server) and `.sitecore/component-map.client.ts` (Client). Required so layout and editing can resolve and render components. App Router has separate server and client maps.
+
+### content-sdk-editing-safe-rendering
+
+Safe rendering in XM Cloud editing and preview: `draftMode()`, editing chromes, and design library. Use when ensuring components work in the Sitecore editor and preview. Use `client.getPreview(searchParams)` or `client.getDesignLibraryData(searchParams)` when draft mode is enabled.
+
+### 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 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.
+
+### content-sdk-route-configuration
+
+Routing: single catch-all at `src/app/[site]/[locale]/[[...path]]/page.tsx`. Layout: app/layout.tsx → app/[site]/layout.tsx → page. Call `setRequestLocale(\`${site}_${locale}\`)` at top of page. Use placeholders and Layout.tsx as in AGENTS.md.
+
+### 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:** LocaleProxy → AppRouterMultisiteProxy → RedirectsProxy → PersonalizeProxy. Do not change proxy order.
+
+### content-sdk-dictionary-and-i18n
+
+Dictionary and i18n: next-intl with `src/i18n/routing.ts` and `src/i18n/request.ts`. Request locale is `${site}_${locale}`; call `setRequestLocale(\`${site}_${locale}\`)` in the page; in request.ts parse and load dictionary with `client.getDictionary({ locale, site })`.
+
+### content-sdk-sitemap-robots
+
+Sitemap and robots: `src/app/api/sitemap/route.ts` and `src/app/api/robots/route.ts` with `createSitemapRouteHandler` and `createRobotsRouteHandler`. Rewrites in next.config.ts 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 the appropriate component map (server or client).
+
+### content-sdk-troubleshoot-editing
+
+Troubleshooting XM Cloud editing, preview, and design library. Use when editing or preview does not behave as expected. Check draftMode(), getPreview/getDesignLibraryData from searchParams, and component maps.
+
+### 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: layout data from getPage (or getPreview/getDesignLibraryData in editing). Pass site and locale from route params; Server Components use the client in server context; Client Components receive serializable props from parent. BYOC must be registered in the component map.
+
+---
+
+## 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 App Router app.

package/dist/templates/nextjs-app-router/eslint.config.mjs

@@ -1,29 +1,29 @@
-import { dirname } from "path";
-import { fileURLToPath } from "url";
-import { FlatCompat } from "@eslint/eslintrc";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-const compat = new FlatCompat({
-  baseDirectory: __dirname,
-});
-
-const eslintConfig = [
-  ...compat.extends("next/core-web-vitals", "next/typescript"),
-  { 
-    rules: {
-      // Don't force alt for <Image/> (sourced from Sitecore media)
-      "jsx-a11y/alt-text": "off",
-    },
-    ignores: [
-      "node_modules/**",
-      ".next/**",
-      "out/**",
-      "build/**",
-      "next-env.d.ts",
-    ],
-  },
-];
-
-export default eslintConfig;
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { FlatCompat } from "@eslint/eslintrc";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const compat = new FlatCompat({
+  baseDirectory: __dirname,
+});
+
+const eslintConfig = [
+  ...compat.extends("next/core-web-vitals", "next/typescript"),
+  { 
+    rules: {
+      // Don't force alt for <Image/> (sourced from Sitecore media)
+      "jsx-a11y/alt-text": "off",
+    },
+    ignores: [
+      "node_modules/**",
+      ".next/**",
+      "out/**",
+      "build/**",
+      "next-env.d.ts",
+    ],
+  },
+];
+
+export default eslintConfig;

package/dist/templates/nextjs-app-router/gitignore

@@ -1,31 +1,31 @@
-# See https://help.github.com/ignore-files/ for more about ignoring files.
-
-# dependencies
-/node_modules
-
-# next.js
-/.next*/
-/out/
-
-# misc
-.DS_Store
-
-# local env files
-.env.local
-.env.*.local
-.env
-
-# Log files
-*.log*
-
-# vercel
-.vercel
-
-# sitecore temp files
-.sitecore/*
-# except for component-map
-!.sitecore/component-map.ts
-!.sitecore/component-map.client.ts
-!.sitecore/import-map.ts
-!.sitecore/import-map.server.ts
-!.sitecore/import-map.client.ts
+# See https://help.github.com/ignore-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+
+# next.js
+/.next*/
+/out/
+
+# misc
+.DS_Store
+
+# local env files
+.env.local
+.env.*.local
+.env
+
+# Log files
+*.log*
+
+# vercel
+.vercel
+
+# sitecore temp files
+.sitecore/*
+# except for component-map
+!.sitecore/component-map.ts
+!.sitecore/component-map.client.ts
+!.sitecore/import-map.ts
+!.sitecore/import-map.server.ts
+!.sitecore/import-map.client.ts

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

@@ -1,55 +1,56 @@
-{
-  "name": "content-sdk-nextjs-app-router",
-  "description": "Application utilizing Content SDK and Next.js",
-  "version": "0.1.0",
-  "private": true,
-  "author": {
-    "name": "Sitecore Corporation",
-    "url": "https://doc.sitecore.com/xmc/en/developers/content-sdk/index.html"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/sitecore/content-sdk.git"
-  },
-  "bugs": {
-    "url": "https://github.com/sitecore/content-sdk/issues"
-  },
-  "license": "Apache-2.0",
-  "scripts": {
-    "build": "cross-env NODE_ENV=production npm-run-all --serial sitecore-tools:generate-map sitecore-tools:build next:build",
-    "lint": "eslint ./src/**/*.tsx ./src/**/*.ts",
-    "next:build": "next build",
-    "next:dev": "cross-env NODE_OPTIONS='--inspect' next dev",
-    "next:start": "next start",
-    "sitecore-tools:generate-map": "sitecore-tools project component generate-map",
-    "sitecore-tools:generate-map:watch": "sitecore-tools project component generate-map --watch",
-    "sitecore-tools:build": "sitecore-tools project build",
-    "dev": "cross-env NODE_ENV=development npm-run-all --serial sitecore-tools:generate-map sitecore-tools:build --parallel next:dev sitecore-tools:generate-map:watch",
-    "start": "cross-env-shell NODE_ENV=production npm-run-all --serial build next:start"
-  },
-  "dependencies": {
-    "@sitecore-cloudsdk/core": "^0.5.4",
-    "@sitecore-cloudsdk/events": "^0.5.4",
-    "@sitecore-content-sdk/nextjs": "<%- version %>",
-    "@sitecore-feaas/clientside": "^0.6.0",
-    "@sitecore/components": "~2.1.0",
-    "next": "^16.1.1",
-    "react": "^19.2.1",
-    "react-dom": "^19.2.1",
-    "next-intl": "^4.3.5"
-  },
-  "devDependencies": {
-    "@eslint/eslintrc": "^3",
-    "@sitecore-content-sdk/cli": "<%- version %>",
-    "@tailwindcss/postcss": "^4",
-    "@types/node": "^24.10.4",
-    "@types/react": "^19.2.7",
-    "@types/react-dom": "^19.2.3",
-    "cross-env": "^10.0.0",
-    "eslint": "^9.33.0",
-    "eslint-config-next": "15.5.3",
-    "npm-run-all2": "^8.0.4",
-    "tailwindcss": "^4",
-    "typescript": "~5.8.3"
-  }
+{
+  "name": "content-sdk-nextjs-app-router",
+  "description": "Application utilizing Content SDK and Next.js",
+  "version": "0.1.0",
+  "private": true,
+  "author": {
+    "name": "Sitecore Corporation",
+    "url": "https://doc.sitecore.com/xmc/en/developers/content-sdk/index.html"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sitecore/content-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sitecore/content-sdk/issues"
+  },
+  "license": "Apache-2.0",
+  "scripts": {
+    "build": "cross-env NODE_ENV=production npm-run-all --serial sitecore-tools:generate-map sitecore-tools:build next:build",
+    "lint": "eslint ./src/**/*.tsx ./src/**/*.ts",
+    "next:build": "next build",
+    "next:dev": "cross-env NODE_OPTIONS='--inspect' next dev",
+    "next:start": "next start",
+    "sitecore-tools:generate-map": "sitecore-tools project component generate-map",
+    "sitecore-tools:generate-map:watch": "sitecore-tools project component generate-map --watch",
+    "sitecore-tools:build": "sitecore-tools project build",
+    "dev": "cross-env NODE_ENV=development npm-run-all --serial sitecore-tools:generate-map sitecore-tools:build --parallel next:dev sitecore-tools:generate-map:watch",
+    "start": "cross-env-shell NODE_ENV=production npm-run-all --serial build next:start"
+  },
+  "dependencies": {
+    "@sitecore-content-sdk/nextjs": "<%- version %>",
+    "@sitecore-content-sdk/analytics-core": "<%- version %>",
+    "@sitecore-content-sdk/personalize": "<%- version %>",
+    "@sitecore-content-sdk/events": "<%- version %>",
+    "@sitecore-feaas/clientside": "^0.6.0",
+    "@sitecore/components": "~2.1.0",
+    "next": "^16.1.1",
+    "react": "^19.2.1",
+    "react-dom": "^19.2.1",
+    "next-intl": "^4.3.5"
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "^3",
+    "@sitecore-content-sdk/cli": "<%- version %>",
+    "@tailwindcss/postcss": "^4",
+    "@types/node": "^24.10.4",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "cross-env": "^10.0.0",
+    "eslint": "^9.33.0",
+    "eslint-config-next": "15.5.3",
+    "npm-run-all2": "^8.0.4",
+    "tailwindcss": "^4",
+    "typescript": "~5.8.3"
+  }
 }

package/dist/templates/nextjs-app-router/postcss.config.mjs

@@ -1,5 +1,5 @@
-const config = {
-  plugins: ["@tailwindcss/postcss"],
-};
-
-export default config;
+const config = {
+  plugins: ["@tailwindcss/postcss"],
+};
+
+export default config;