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

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

@@ -1,290 +1,290 @@
-# Sitecore Content SDK Next.js App Router Project - Windsurf AI Rules
-
-## Project Purpose and Tech Stack
-
-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.
-
-### 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
+# Sitecore Content SDK Next.js App Router Project - Windsurf AI Rules
+
+## Project Purpose and Tech Stack
+
+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.
+
+### 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

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

@@ -120,15 +120,14 @@ These are the main head-app–specific concepts. Details are in the sections bel
 - **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 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 and PPR
+### Server vs Client components
 
 - **Default:** Components are Server Components. Use `'use client'` only for interactivity (e.g. hooks, event handlers).
-- **PPR (Partial Prerendering):** Dynamic work (e.g. `draftMode()`, data fetching) is wrapped in `<Suspense>` (e.g. `DynamicPageContent`, `DynamicLayoutContent`, `DynamicNotFoundContent`). Keep the same pattern when adding new dynamic branches so PPR and caching behave correctly.
 - **draftMode:** Used in layout and page; call `await draftMode()` in Server Components that need to know preview state.
 
 ### Not-found and error page
 
-- **Segment not-found:** `src/app/[site]/[locale]/[[...path]]/not-found.tsx`. For Sitecore-driven 404, read site/locale from the rewrite header: `parseRewriteHeader(headers())` from `@sitecore-content-sdk/nextjs/utils`, then `client.getErrorPage(ErrorPage.NotFound, { site, locale })` and render layout if a page is returned. Wrap in `Suspense` if using async logic.
+- **Segment not-found:** `src/app/[site]/[locale]/[[...path]]/not-found.tsx`. Uses `getCachedPageParams()` from `@sitecore-content-sdk/nextjs` for site/locale, then `client.getErrorPage(ErrorPage.NotFound, { site, locale })` and renders layout if a page is returned.
 - **Root not-found:** `src/app/not-found.tsx` — minimal fallback when no segment handles the route.
 
 ### API route handlers
@@ -154,7 +153,7 @@ These are the main head-app–specific concepts. Details are in the sections bel
 
 - **Quick checks:** If locale or dictionary is wrong, ensure `setRequestLocale(\`${site}_${locale}\`)` is called at the top of the page and `src/i18n/request.ts` parses `requestLocale` and calls `client.getDictionary`. If not-found doesn't show Sitecore content, use `parseRewriteHeader(headers())` for site/locale. Always `await params` (Next.js 15+).
 - **Security:** Use only environment variables in `sitecore.config.ts`; never hardcode API keys, editing secret, or host URLs. Do not expose secrets in client-side code or in logs. Validate and sanitize user input at boundaries.
-- **Performance:** Keep middleware lightweight; use the proxy `matcher` so it does not run on API routes, `_next`, sitemap, robots, or static assets. Use Server Components and Suspense for dynamic content; add `'use client'` only where interactivity is needed. Use `generateStaticParams` and caching as in the existing page.
+- **Performance:** Keep middleware lightweight; use the proxy `matcher` so it does not run on API routes, `_next`, sitemap, robots, or static assets. Use Server Components for data fetching; add `'use client'` only where interactivity is needed. Use `generateStaticParams` and caching as in the existing page.
 - **Sitecore patterns:** Use SDK field components (`<Text>`, `<RichText>`, `<Image>`) and validate field existence before render. Register new components in `.sitecore/component-map.ts` and `.sitecore/component-map.client.ts` as appropriate. Use the single Sitecore client in `lib/sitecore-client.ts` for all data fetching.
 - **Consistency:** Follow the existing patterns in `[site]/[locale]/[[...path]]/page.tsx`, layout hierarchy, `i18n/request.ts` (site_locale), and API route handlers. When adding routes or rewrites, keep the middleware matcher and next-intl config in sync.
 
@@ -168,7 +167,7 @@ These are the main head-app–specific concepts. Details are in the sections bel
 | Pass `{ site, locale }` to `client.getPage` and `getDictionary` | Assume site/locale from headers inside page without using params |
 | Run LocaleProxy before AppRouterMultisiteProxy in middleware | Change proxy order (locale must run first for i18n) |
 | Call `setRequestLocale(\`${site}_${locale}\`)` in the page for next-intl | Omit setRequestLocale when adding new page branches |
-| Use Suspense around async Server Components that use draftMode or fetch | Put async data fetching in client components when SSR is intended |
+| Use Server Components for async data fetching | Put async data fetching in client components when SSR is intended |
 | Use `parseRewriteHeader(headers())` in not-found for site/locale | Hardcode site/locale in not-found or error pages |
 | 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 |
@@ -179,7 +178,7 @@ These are the main head-app–specific concepts. Details are in the sections bel
 
 ## Guardrails for agentic AI
 
-- **Preserve behavior:** Do not change the proxy order (LocaleProxy → AppRouterMultisiteProxy → …), the `[site]/[locale]/[[...path]]` route shape, or the way `setRequestLocale` and `i18n/request.ts` use `{site}_{locale}`. Preserve PPR/Suspense boundaries and draftMode handling.
+- **Preserve behavior:** Do not change the proxy order (LocaleProxy → AppRouterMultisiteProxy → …), the `[site]/[locale]/[[...path]]` route shape, or the way `setRequestLocale` and `i18n/request.ts` use `{site}_{locale}`. Preserve draftMode handling in layout and page.
 - **Do not expand scope:** Limit edits to the app (app router, components, API routes, 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, component maps, and env-based config. Do not introduce a different way to resolve site/locale or a second client without clear need.
 - **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.
@@ -208,6 +207,7 @@ These are the main head-app–specific concepts. Details are in the sections bel
 
 ## References
 
+- **Skills.md** — Capability groupings for this app; [.agents/skills/](.agents/skills/) provides each capability as an Agent Skill (when-to-use, hard rules, stop conditions) for tools that support the [Agent Skills](https://agentskills.io) standard.
 - **CLAUDE.md** — Full coding standards and Sitecore patterns for this template.
 - **.cursor/rules/** — App Router and Sitecore rules.
 - [Sitecore Content SDK](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html) — Official docs.