@mikulgohil/ai-kit 1.2.1 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikulgohil/ai-kit",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "AI-assisted development setup kit. Auto-detects your tech stack and generates tailored CLAUDE.md, .cursorrules, hooks, agents, context modes, slash commands, and developer guides.",
   "type": "module",
   "bin": {

package/templates/claude-md/nextjs-app-router.md

@@ -22,8 +22,42 @@ app/
   api/                ← Route Handlers
 ```
 
+## Server Actions
+- Use `'use server'` directive at the top of the file or inline in a function
+- For form handling: pass Server Action directly to `<form action={myAction}>`
+- Use `useActionState` (React 19) for form state management with pending/error states
+- Always validate input with Zod before processing
+- Call `revalidatePath()` or `revalidateTag()` after mutations to update cached data
+- Return structured results `{ success, error, data }` — do not throw from Server Actions
+
+## Streaming & Suspense
+- Use `loading.tsx` for route-level loading states (automatic Suspense boundary)
+- Wrap slow data-fetching components in `<Suspense fallback={...}>` for granular streaming
+- Nested Suspense boundaries enable progressive page rendering
+- `loading.tsx` applies to the entire route segment; `<Suspense>` is per-component
+
+## Route Groups & Layouts
+- Use `(groupName)/` directories to organize routes without affecting URL structure
+- Route groups can have their own `layout.tsx` for section-specific layouts
+- Example: `(marketing)/about/page.tsx` → URL is `/about`, not `/(marketing)/about`
+- Use parallel routes (`@slot/`) for independent loading states within a layout
+
+## Middleware
+- Place `middleware.ts` in the project root (next to `app/`)
+- Use `matcher` config to scope middleware to specific routes
+- Common uses: authentication guards, redirects, i18n locale detection, Sitecore preview mode
+- Middleware runs on the Edge — use only Edge-compatible APIs (no Node.js fs, path, etc.)
+
+## ISR (Incremental Static Regeneration)
+- Set `revalidate` in `fetch()` options: `fetch(url, { next: { revalidate: 60 } })`
+- Use `export const revalidate = 60` at the page/layout level for time-based ISR
+- Use `revalidateTag(tag)` or `revalidatePath(path)` in Server Actions for on-demand ISR
+- Tag fetches with `fetch(url, { next: { tags: ['posts'] } })` for targeted revalidation
+
 ## Common Mistakes to Avoid
 - Don't use `useEffect` for data fetching in Server Components
 - Don't import server-only code in Client Components
 - Don't use `router.push` for simple navigation — use `<Link>`
-- Don't forget to add `loading.tsx` for route transitions
+- Don't forget to add `loading.tsx` for route transitions
+- Don't throw errors from Server Actions — return error objects instead
+- Don't use Node.js APIs in Middleware — it runs on the Edge runtime

package/templates/claude-md/sitecore-xmc.md

@@ -6,8 +6,9 @@
 - Use `@sitecore-jss/sitecore-jss-nextjs` or `@sitecore-content-sdk/nextjs` for component bindings
 
 ## Component Patterns
+
+### JSS-based (v21.x)
 ```typescript
-// Standard Sitecore component pattern
 import { Text, RichText, Image, Link } from '@sitecore-jss/sitecore-jss-nextjs';
 import type { ComponentRendering, ComponentFields } from '@sitecore-jss/sitecore-jss-nextjs';
 
@@ -31,6 +32,100 @@ const MyComponent = ({ fields }: MyComponentProps): JSX.Element => (
 export default MyComponent;
 ```
 
+### Content SDK v2.x
+```typescript
+import { Text, RichText, Image, Link } from '@sitecore-content-sdk/nextjs';
+import type { ComponentRendering, ComponentFields, Field } from '@sitecore-content-sdk/nextjs';
+
+interface MyComponentFields extends ComponentFields {
+  heading: Field<string>;
+  body: Field<string>;
+}
+
+type MyComponentProps = {
+  rendering: ComponentRendering;
+  fields: MyComponentFields;
+};
+
+const MyComponent = ({ fields }: MyComponentProps): JSX.Element => (
+  <div>
+    <Text field={fields.heading} tag="h2" />
+    <RichText field={fields.body} />
+  </div>
+);
+
+export default MyComponent;
+```
+
+## Experience Edge GraphQL
+- Use Experience Edge for cross-page queries: navigation, search indexes, content listings
+- Endpoint: `https://edge.sitecorecloud.io/api/graphql/v1`
+- Authenticate with `sc_apikey` header
+- Paginate with `first` and `after` parameters
+- Cache responses with appropriate TTL — Edge content is published/read-only
+
+```graphql
+query NavigationQuery($rootPath: String!, $language: String!) {
+  search(
+    where: {
+      AND: [
+        { name: "_path", value: $rootPath, operator: CONTAINS }
+        { name: "_language", value: $language }
+        { name: "_templatename", value: "Navigation Item" }
+      ]
+    }
+    first: 50
+  ) {
+    results {
+      name
+      url { path }
+      ... on NavigationItem {
+        title { value }
+        link { jsonValue }
+      }
+    }
+  }
+}
+```
+
+## Sitecore Image Optimization
+- Use `next/image` with Sitecore image fields for responsive images
+- Extract `src`, `alt`, `width`, `height` from the Sitecore `ImageField` value
+- Configure Sitecore CDN domain in `next.config.js` `images.remotePatterns`
+
+```typescript
+import NextImage from 'next/image';
+import type { ImageField } from '@sitecore-jss/sitecore-jss-nextjs';
+
+function OptimizedImage({ field }: { field: ImageField }) {
+  if (!field?.value?.src) return null;
+  const { src, alt, width, height } = field.value;
+  return (
+    <NextImage
+      src={src}
+      alt={alt || ''}
+      width={Number(width) || 800}
+      height={Number(height) || 600}
+    />
+  );
+}
+```
+
+## Personalization & Variants
+- Sitecore delivers personalized component variants via Layout Service
+- Personalized pages require SSR — they cannot be statically generated
+- Component variants are transparent to the React component — same props, different data
+- Test both default and personalized rendering in development
+
+## Environment Setup
+Required `.env.local` variables for XM Cloud:
+```
+SITECORE_API_KEY=your-api-key
+SITECORE_API_HOST=https://your-instance.sitecorecloud.io
+GRAPH_QL_ENDPOINT=https://edge.sitecorecloud.io/api/graphql/v1
+SITECORE_SITE_NAME=your-site-name
+```
+
 ## Rules
 - Always use Sitecore field helpers (`<Text>`, `<RichText>`, `<Image>`, `<Link>`) — never render field values directly
 - This enables Experience Editor / Pages inline editing
@@ -43,4 +138,6 @@ export default MyComponent;
 - Don't render `fields.heading.value` directly — use `<Text field={fields.heading} />`
 - Don't hardcode content that should come from Sitecore fields
 - Don't forget to register new components in the component factory
-- Don't use `getStaticProps` directly — use Sitecore's built-in SSG/SSR integration
+- Don't use `getStaticProps` directly — use Sitecore's built-in SSG/SSR integration
+- Don't statically generate personalized pages — they need SSR
+- Don't forget to configure Sitecore CDN domain in `next.config.js` for image optimization

package/templates/claude-md/typescript.md

@@ -11,9 +11,87 @@
 - Use `satisfies` for type-safe object literals when the type is known
 - Use discriminated unions for state management (loading/success/error)
 - Prefer `as const` for literal type inference
+- Use branded types for domain identifiers: `type UserId = string & { readonly __brand: 'UserId' }`
+
+## Sitecore Field Typing
+```typescript
+// Typed component props with Sitecore fields
+import type { Field, ImageField, LinkField, ComponentRendering } from '@sitecore-jss/sitecore-jss-nextjs';
+
+interface HeroBannerFields {
+  heading: Field<string>;
+  body: Field<string>;
+  image: ImageField;
+  cta: LinkField;
+}
+
+type HeroBannerProps = {
+  rendering: ComponentRendering;
+  fields: HeroBannerFields;
+};
+
+// Type guard for checking if a field has a value
+function hasFieldValue<T>(field: Field<T> | undefined): field is Field<T> & { value: T } {
+  return field !== undefined && field.value !== undefined && field.value !== null;
+}
+```
+
+## Next.js Typing
+```typescript
+// Page props (App Router)
+type PageProps = {
+  params: Promise<{ slug: string }>;
+  searchParams: Promise<Record<string, string | string[] | undefined>>;
+};
+
+// Layout props
+type LayoutProps = {
+  children: React.ReactNode;
+  params: Promise<{ locale: string }>;
+};
+
+// Server Action return type
+type ActionResult<T = void> =
+  | { success: true; data: T }
+  | { success: false; error: string };
+
+// Metadata generation
+import type { Metadata } from 'next';
+export async function generateMetadata({ params }: PageProps): Promise<Metadata> { ... }
+```
+
+## Tailwind Type Safety
+```typescript
+// Typed Tailwind config extensions
+import type { Config } from 'tailwindcss';
+
+const config: Config = {
+  content: ['./src/**/*.{ts,tsx}'],
+  theme: {
+    extend: {
+      colors: { brand: { primary: '#...', secondary: '#...' } },
+    },
+  },
+};
+```
+
+## Validation with Zod
+```typescript
+import { z } from 'zod';
+
+// Define schema once — derive TypeScript type from it
+const ContactFormSchema = z.object({
+  name: z.string().min(1, 'Name is required'),
+  email: z.string().email('Invalid email'),
+  message: z.string().min(10, 'Message too short'),
+});
+
+type ContactForm = z.infer<typeof ContactFormSchema>;
+```
 
 ## Common Mistakes to Avoid
 - Don't use `any` to bypass type errors — fix the underlying type issue
 - Don't create unnecessary generic types — use them only when the type genuinely varies
 - Don't duplicate types — import from a shared types file
-- Don't use optional chaining as a substitute for proper null checking
+- Don't use optional chaining as a substitute for proper null checking
+- Don't use `as` type assertions when a type guard or `satisfies` would be safer

package/templates/cursorrules/nextjs-app-router.md

@@ -5,4 +5,9 @@
 - Colocate `loading.tsx`, `error.tsx`, `not-found.tsx` with pages
 - Data fetching: use `fetch()` in Server Components, Server Actions for mutations
 - Use `<Link>` for navigation, `next/image` for images
-- No `useEffect` for data fetching in Server Components
+- No `useEffect` for data fetching in Server Components
+- Server Actions: validate with Zod, return `{ success, error }`, call `revalidatePath`/`revalidateTag` after mutations
+- Streaming: wrap slow components in `<Suspense fallback={...}>` for progressive rendering
+- ISR: use `fetch(url, { next: { revalidate: N } })` or `export const revalidate = N`
+- Middleware: place `middleware.ts` at project root, use `matcher` config, Edge-compatible APIs only
+- Route Groups: use `(groupName)/` for organization without affecting URL paths

package/templates/cursorrules/sitecore-xmc.md

@@ -6,4 +6,8 @@
 - Register new components in the component factory
 - GraphQL queries go in `.graphql` files alongside components
 - Don't use `getStaticProps` directly — use Sitecore's SSG/SSR integration
-- Don't hardcode content that should come from Sitecore fields
+- Don't hardcode content that should come from Sitecore fields
+- Content SDK v2.x: import from `@sitecore-content-sdk/nextjs` instead of `@sitecore-jss/sitecore-jss-nextjs`
+- Experience Edge: use `first`/`after` for pagination, cache responses appropriately
+- Personalized pages require SSR — do not statically generate them
+- Use `next/image` with Sitecore image fields — configure CDN domain in `next.config.js`

package/templates/cursorrules/typescript.md

@@ -5,4 +5,9 @@
 - Use `unknown` over `any` — narrow with type guards
 - No `@ts-ignore` without explanation comments
 - Use `satisfies` for type-safe literals, `as const` for inference
-- Import types from shared files — don't duplicate
+- Import types from shared files — don't duplicate
+- Sitecore: type component fields with `Field<string>`, `ImageField`, `LinkField`
+- Next.js: use `Promise<{ slug: string }>` for `params` in App Router page props
+- Server Actions: return `{ success: true; data: T } | { success: false; error: string }`
+- Validation: define Zod schemas, derive TS types with `z.infer<typeof Schema>`
+- Prefer type guards and `satisfies` over `as` type assertions