create-content-sdk-app 2.0.2 → 2.1.0-canary.10

package/dist/templates/nextjs/.windsurfrules

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

package/dist/templates/nextjs/AGENTS.md

@@ -186,7 +186,7 @@ These are the main head-app–specific concepts. Details are in the sections bel
 - **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/** — Project and Sitecore rules.
-- [Sitecore Content SDK](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html) — Official docs.
+- [Sitecore Content SDK](https://doc.sitecore.com/sai/en/developers/content-sdk/sitecore-content-sdk-for-sitecoreai.html) — Official docs.
 - [Next.js Pages Router](https://nextjs.org/docs/pages) — Data fetching, API routes, i18n.
 
 **For head applications / empty starters:** If you use this template for your head application (e.g. empty starter), keep this AGENTS.md as that head application's guide. Do not replace it with the Content SDK monorepo root AGENTS.md — that file describes the SDK source tree, not the head application. Adjust only what is specific to your project (e.g. custom layout or workflow). See the Content SDK README "AI Development Support" section for more on which AGENTS.md to use.