create-content-sdk-app 1.2.0-canary.8 → 1.2.0

package/dist/templates/nextjs/.cursor/rules/project-setup.mdc

@@ -0,0 +1,100 @@
+---
+description: Getting started with your Sitecore Content SDK Next.js project
+alwaysApply: true
+globs: []
+---
+
+# Sitecore Content SDK Next.js Project
+
+## Project Overview
+
+This is a Sitecore Content SDK application built with Next.js. The project structure follows Sitecore best practices for XM Cloud development.
+
+Key Technologies:
+
+- Next.js (React framework)
+- Sitecore Content SDK
+- TypeScript
+- Sitecore XM Cloud
+
+## Getting Started
+
+Development Workflow:
+
+1. Install dependencies: `npm install`
+2. Configure environment variables (copy `.env.example` to `.env.local`)
+3. Start development server: `npm run dev`
+4. Build for production: `npm run build`
+
+Environment Configuration:
+
+- Copy `.env.example` to `.env.local`
+- Add your Sitecore API endpoint and key
+- Configure site name and other settings
+
+## Sitecore Integration
+
+Configuration:
+
+- Configure Sitecore connection in `sitecore.config.ts`
+- Register components in the component map
+- Use Sitecore field components for content rendering
+- Follow Sitecore's layout service patterns
+
+Component Development:
+
+- Create components in `src/components/`
+- Export from component files for registration
+- Use TypeScript interfaces for component props
+- Follow Sitecore field handling patterns
+
+## Project Structure
+
+```
+src/
+  components/          # React-specific SDK
+  lib/                 # Configuration and utilities
+  pages/               # Next.js pages
+  assets/              # Static assets and styles
+```
+
+## Best Practices
+
+Sitecore Components:
+
+- Use descriptive component names
+- Handle field validation gracefully
+- Implement proper error boundaries
+- Cache content when appropriate
+
+Performance:
+
+- Optimize images using Next.js Image component
+- Implement proper loading states
+- Use React.memo for expensive components
+- Consider server-side rendering implications
+
+## Development Commands
+
+```bash
+npm run dev          # Start development server
+npm run build        # Build for production
+npm run start        # Start production server
+npm run lint         # Run ESLint
+npm run type-check   # Run TypeScript compiler
+```
+
+## Next Steps
+
+1. Configure your Sitecore connection
+2. Create your first component
+3. Add content types and templates
+4. Set up your development workflow
+5. Deploy to your hosting platform
+
+Referenced:
+@src/components/
+@sitecore.config.ts
+@package.json
+@.env.example
+

package/dist/templates/nextjs/.cursor/rules/sitecore.mdc

@@ -0,0 +1,147 @@
+---
+description: Sitecore development patterns for your project
+alwaysApply: false
+globs:
+  - 'src/components/**'
+  - 'src/lib/**'
+  - 'sitecore.config.ts'
+  - '**/*sitecore*'
+  - '**/*content*'
+---
+
+# Sitecore Development Patterns
+
+## Component Development
+
+Sitecore Component Naming:
+
+- Use descriptive, feature-based names: `HeroWithContent`, `ProductListing`, `ContentBlockGrid`
+- Follow PascalCase convention
+- Include component type in name when helpful: `LayoutContainer`, `ContentRenderer`
+
+Component Registration:
+
+- Export component from component file
+- Use descriptive, PascalCase names
+- Include TypeScript interfaces for props
+- Handle missing fields gracefully
+
+```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>
+  );
+}
+```
+
+## Content Management
+
+Field Handling:
+
+- Always validate field existence before rendering
+- Use helper functions for common field operations
+- 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} />
+
+// Avoid: Manual field value extraction unless necessary
+```
+
+Layout Service:
+
+- Use the Layout Service for page data fetching
+- Implement proper error boundaries for layout rendering
+- Handle missing placeholder content gracefully
+- Cache layout data when appropriate
+
+## Configuration
+
+Environment Setup:
+
+- Use `.env.local` for local development
+- Never commit API keys to version control
+- Use `.env.example` to document required variables
+- Configure Sitecore endpoints in `sitecore.config.ts`
+
+```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.SITECORE_EDGE_URL || '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,
+});
+```
+
+## Security and Performance
+
+Security Best Practices:
+
+- Sanitize user inputs before processing
+- Validate content from Sitecore before rendering
+- Use HTTPS for all Sitecore connections
+- Never expose sensitive configuration in client-side code
+
+Content Fetching:
+
+- Implement caching strategy for content (React Query recommended)
+- Use GraphQL queries efficiently (avoid over-fetching)
+- Implement proper loading states and error handling
+- Consider content preview vs. published content scenarios
+
+## Development Patterns
+
+Error Handling:
+
+- Create custom error classes: `SitecoreFetchError`, `ComponentRenderError`
+- Log errors appropriately for debugging
+- Provide fallback content when components fail to render
+- Use error boundaries in React applications
+
+Placeholder Management:
+
+- Use strongly-typed placeholder names
+- Handle dynamic placeholders appropriately
+- Implement fallback rendering for missing placeholders
+- Follow Sitecore's placeholder naming conventions
+
+Testing:
+
+- Mock Sitecore services in unit tests
+- Test component rendering with various field configurations
+- Include tests for error scenarios (missing fields, API failures)
+- Use Sitecore's test data helpers when available
+
+Referenced:
+@src/components/
+@sitecore.config.ts
+@.env.example

package/dist/templates/nextjs/.env.container.example

@@ -1,27 +1,27 @@
-# This file should be copied to .env.local and modified with your environment variables to connect to your Sitecore container instance.
-
-# To secure the Sitecore editor endpoint exposed by your Next.js app
-# (`/api/editing/render` by default), a secret token is used. This (client-side)
-SITECORE_EDITING_SECRET=
-
-# Your Sitecore site name.
-# The value of the variable represents the default/configured site.
-NEXT_PUBLIC_DEFAULT_SITE_NAME=
-
-# Your default app language.
-NEXT_PUBLIC_DEFAULT_LANGUAGE=
-
-# Your Sitecore API key is needed to build the app.
-NEXT_PUBLIC_SITECORE_API_KEY=
-
-# Your Sitecore API hostname is needed to build the app.
-NEXT_PUBLIC_SITECORE_API_HOST=
-
-# Sitecore Content SDK npm packages utilize the debug module for debug logging.
-# https://www.npmjs.com/package/debug
-# Set the DEBUG environment variable to 'content-sdk:*' to see all logs:
-#DEBUG=content-sdk:*
-# Or be selective and show for example only layout service logs:
-#DEBUG=content-sdk:layout
-# Or everything BUT layout service logs:
-#DEBUG=content-sdk:*,-content-sdk:layout
+# This file should be copied to .env.local and modified with your environment variables to connect to your Sitecore container instance.
+
+# To secure the Sitecore editor endpoint exposed by your Next.js app
+# (`/api/editing/render` by default), a secret token is used. This (client-side)
+SITECORE_EDITING_SECRET=
+
+# Your Sitecore site name.
+# The value of the variable represents the default/configured site.
+NEXT_PUBLIC_DEFAULT_SITE_NAME=
+
+# Your default app language.
+NEXT_PUBLIC_DEFAULT_LANGUAGE=
+
+# Your Sitecore API key is needed to build the app.
+NEXT_PUBLIC_SITECORE_API_KEY=
+
+# Your Sitecore API hostname is needed to build the app.
+NEXT_PUBLIC_SITECORE_API_HOST=
+
+# Sitecore Content SDK npm packages utilize the debug module for debug logging.
+# https://www.npmjs.com/package/debug
+# Set the DEBUG environment variable to 'content-sdk:*' to see all logs:
+#DEBUG=content-sdk:*
+# Or be selective and show for example only layout service logs:
+#DEBUG=content-sdk:layout
+# Or everything BUT layout service logs:
+#DEBUG=content-sdk:*,-content-sdk:layout

package/dist/templates/nextjs/.env.remote.example

@@ -1,44 +1,44 @@
-# This file should be copied to .env.local and modified with your environment variables to connect to your remote Sitecore instance.
-
-# To secure the Sitecore editor endpoint exposed by your Next.js app
-# (`/api/editing/render` by default), a secret token is used. This (client-side)
-SITECORE_EDITING_SECRET=
-
-# Your Sitecore site name.
-# The value of the variable represents the default/configured site.
-NEXT_PUBLIC_DEFAULT_SITE_NAME=
-
-# Your default app language.
-NEXT_PUBLIC_DEFAULT_LANGUAGE=
-
-# Your unified Sitecore Edge Context Id for server-side use.
-# This will be used over any Sitecore Preview / Delivery Edge variables (above).
-SITECORE_EDGE_CONTEXT_ID=
-
-# Your Sitecore Edge Context Id for client-side use.
-# Will be used as a fallback if separate SITECORE_EDGE_CONTEXT_ID value is not provided
-NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID=
-
-# An optional Sitecore Personalize scope identifier.
-# This can be used to isolate personalization data when multiple XM Cloud Environments share a Personalize tenant.
-# This should match the PAGES_PERSONALIZE_SCOPE environment variable for your connected XM Cloud Environment.
-NEXT_PUBLIC_PERSONALIZE_SCOPE=
-
-# Timeout (ms) for Sitecore CDP requests to respond within. Default is 400.
-PERSONALIZE_MIDDLEWARE_CDP_TIMEOUT=
-
-# Timeout (ms) for Sitecore Experience Edge requests to respond within. Default is 400.
-PERSONALIZE_MIDDLEWARE_EDGE_TIMEOUT=
-
-# Sitecore Content SDK npm packages utilize the debug module for debug logging.
-# https://www.npmjs.com/package/debug
-# Set the DEBUG environment variable to 'content-sdk:*' to see all logs:
-#DEBUG=content-sdk:*
-# Or be selective and show for example only layout service logs:
-#DEBUG=content-sdk:layout
-# Or everything BUT layout service logs:
-#DEBUG=content-sdk:*,-content-sdk:layout
-
-# Client ID and Secret used for Design Library functionality
-SITECORE_AUTH_CLIENT_ID=
-SITECORE_AUTH_CLIENT_SECRET=
+# This file should be copied to .env.local and modified with your environment variables to connect to your remote Sitecore instance.
+
+# To secure the Sitecore editor endpoint exposed by your Next.js app
+# (`/api/editing/render` by default), a secret token is used. This (client-side)
+SITECORE_EDITING_SECRET=
+
+# Your Sitecore site name.
+# The value of the variable represents the default/configured site.
+NEXT_PUBLIC_DEFAULT_SITE_NAME=
+
+# Your default app language.
+NEXT_PUBLIC_DEFAULT_LANGUAGE=
+
+# Your unified Sitecore Edge Context Id for server-side use.
+# This will be used over any Sitecore Preview / Delivery Edge variables (above).
+SITECORE_EDGE_CONTEXT_ID=
+
+# Your Sitecore Edge Context Id for client-side use.
+# Will be used as a fallback if separate SITECORE_EDGE_CONTEXT_ID value is not provided
+NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID=
+
+# An optional Sitecore Personalize scope identifier.
+# This can be used to isolate personalization data when multiple XM Cloud Environments share a Personalize tenant.
+# This should match the PAGES_PERSONALIZE_SCOPE environment variable for your connected XM Cloud Environment.
+NEXT_PUBLIC_PERSONALIZE_SCOPE=
+
+# Timeout (ms) for Sitecore CDP requests to respond within. Default is 400.
+PERSONALIZE_MIDDLEWARE_CDP_TIMEOUT=
+
+# Timeout (ms) for Sitecore Experience Edge requests to respond within. Default is 400.
+PERSONALIZE_MIDDLEWARE_EDGE_TIMEOUT=
+
+# Sitecore Content SDK npm packages utilize the debug module for debug logging.
+# https://www.npmjs.com/package/debug
+# Set the DEBUG environment variable to 'content-sdk:*' to see all logs:
+#DEBUG=content-sdk:*
+# Or be selective and show for example only layout service logs:
+#DEBUG=content-sdk:layout
+# Or everything BUT layout service logs:
+#DEBUG=content-sdk:*,-content-sdk:layout
+
+# Client ID and Secret used for Design Library functionality
+SITECORE_AUTH_CLIENT_ID=
+SITECORE_AUTH_CLIENT_SECRET=

package/dist/templates/nextjs/.gitattributes

@@ -1,11 +1,11 @@
-# Line endings for this repository
-# See: https://help.github.com/en/articles/configuring-git-to-handle-line-endings
-# This should line up with the expectations from .eslintrc
-
-# Set the default behavior, in case people don't have core.autocrlf set.
-* text=crlf
-
-# Declare files that will always have CRLF line endings on checkout.
-*.ts text eol=crlf
-*.tsx text eol=crlf
-*.js text eol=crlf
+# Line endings for this repository
+# See: https://help.github.com/en/articles/configuring-git-to-handle-line-endings
+# This should line up with the expectations from .eslintrc
+
+# Set the default behavior, in case people don't have core.autocrlf set.
+* text=crlf
+
+# Declare files that will always have CRLF line endings on checkout.
+*.ts text eol=crlf
+*.tsx text eol=crlf
+*.js text eol=crlf

package/dist/templates/nextjs/.prettierrc

@@ -1,8 +1,8 @@
-{
-  "endOfLine": "crlf",
-  "semi": true,
-  "singleQuote": true,
-  "tabWidth": 2,
-  "trailingComma": "es5",
-  "printWidth": 100
-}
+{
+  "endOfLine": "crlf",
+  "semi": true,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "printWidth": 100
+}

package/dist/templates/nextjs/.vscode/extensions.json

@@ -1,8 +1,8 @@
-{
-  "recommendations": [
-    "GraphQL.vscode-graphql",
-    "dbaeumer.vscode-eslint",
-    "esbenp.prettier-vscode",
-    "mikestead.dotenv",
-  ]
-}
+{
+  "recommendations": [
+    "GraphQL.vscode-graphql",
+    "dbaeumer.vscode-eslint",
+    "esbenp.prettier-vscode",
+    "mikestead.dotenv",
+  ]
+}

package/dist/templates/nextjs/.vscode/launch.json

@@ -1,15 +1,15 @@
-{
-  // Use IntelliSense to learn about possible attributes.
-  // Hover to view descriptions of existing attributes.
-  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
-  "version": "0.2.0",
-  "configurations": [
-    {
-      "name": "Attach to Process",
-      "type": "node",
-      "request": "attach",
-      "skipFiles": ["<node_internals>/**"],
-      "port": 9229
-    }
-  ]
-}
+{
+  // Use IntelliSense to learn about possible attributes.
+  // Hover to view descriptions of existing attributes.
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Attach to Process",
+      "type": "node",
+      "request": "attach",
+      "skipFiles": ["<node_internals>/**"],
+      "port": 9229
+    }
+  ]
+}

package/dist/templates/nextjs/.windsurfrules

@@ -0,0 +1,183 @@
+# 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.SITECORE_EDGE_URL || '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