decoupled-demo Cursor Rules

# Cursor Rules for Decoupled Drupal + Next.js Demo Project

## Project Context

This is a modern decoupled CMS demo project with:
- **Backend**: Drupal 11 (or 10.3+) serving JSON:API
- **Frontend**: Next.js 14+ with App Router, TypeScript, TailwindCSS
- **Architecture**: Two separate repositories (drupal-backend, next-frontend)
- **Local Dev**: DDEV for Drupal, native Node.js for Next.js
- **Purpose**: Demo/showcase project demonstrating headless CMS best practices

## Code Style & Standards

### TypeScript
- Use strict mode
- Prefer type inference where possible
- Use interfaces for component props
- Avoid `any` - use `unknown` if needed
- Export types/interfaces explicitly

### React/Next.js
- Use Server Components by default (App Router)
- Only use Client Components (`'use client'`) when necessary (interactivity, hooks, browser APIs)
- Prefer async Server Components for data fetching
- Use `next/image` for all images
- Use `next/link` for internal navigation
- Follow Next.js 14+ App Router conventions

### TailwindCSS
- Use utility classes, avoid custom CSS when possible
- Follow mobile-first responsive design
- Use Tailwind config for design tokens (colors, spacing, typography)
- Keep component CSS modules minimal (only for complex animations or when utilities aren't sufficient)

### File Naming
- Components: PascalCase (`ArticleCard.tsx`)
- Utilities: camelCase (`formatDate.ts`)
- Pages: Next.js conventions (`page.tsx`, `layout.tsx`, `error.tsx`)
- Types: PascalCase (`Article.ts`, `DrupalNode.ts`)

## Architecture Patterns

### Data Fetching
- Use `next-drupal` client from `lib/drupal.ts` for all Drupal API calls
- Fetch data in Server Components, not Client Components
- Use `drupal.getResourceCollection()` for lists
- Use `drupal.getResourceByPath()` for single resources
- Handle errors with error.tsx boundaries
- Use ISR with `revalidate` for content pages

### Component Structure
- Follow atomic design principles (atoms → molecules → organisms)
- Keep components focused and single-purpose
- Extract reusable logic into custom hooks or utilities
- Use TypeScript interfaces for all component props

### Error Handling
- Use Next.js error boundaries (`error.tsx`)
- Provide fallback UI for missing content
- Log errors appropriately (console in dev, proper logging in prod)
- Show user-friendly error messages

## Drupal Integration

### JSON:API Usage
- Always use `next-drupal` library, not raw fetch
- Handle JSON:API response structure correctly
- Include necessary fields in API requests
- Use proper error handling for API failures

### Content Modeling
- Keep content types simple and focused
- Use descriptive field names
- Ensure all fields are exposed via JSON:API
- Use path aliases for clean URLs

## Development Guidelines

### Git Workflow
- Commit frequently with clear messages
- Use conventional commit messages when possible
- Keep commits focused (one feature/fix per commit)
- Write meaningful commit messages

### Code Organization
- Group related files together
- Keep `lib/` utilities focused and well-documented
- Use consistent import ordering (external → internal → relative)
- Keep components in appropriate directories (atoms/molecules/organisms)

### Performance
- Use Next.js Image component for all images
- Implement proper loading states
- Use ISR for content pages
- Minimize client-side JavaScript
- Optimize bundle size

### Accessibility
- Use semantic HTML
- Ensure proper heading hierarchy
- Add alt text to images
- Use ARIA labels when needed
- Test keyboard navigation

## Documentation

### Code Comments
- Comment complex logic, not obvious code
- Use JSDoc for exported functions/types
- Explain "why" not "what" in comments
- Keep comments up-to-date with code changes

### README Files
- Each repo should have a clear README
- Include setup instructions
- Document environment variables
- Provide examples of common tasks

## Testing & Quality

### Code Quality
- Use ESLint and Prettier
- Fix linting errors before committing
- Use TypeScript strict mode
- Avoid console.log in production code (use proper logging)

### Manual Testing
- Test on multiple screen sizes
- Test error scenarios
- Verify all links work
- Check image loading
- Test form submissions (if any)

## Dependencies

### Adding Dependencies
- Prefer well-maintained packages
- Check bundle size impact
- Read documentation before adding
- Keep dependencies up-to-date
- Remove unused dependencies

### Key Libraries
- `next-drupal`: Drupal integration (required)
- `swr`: Client-side data fetching (optional, for Phase 2+)
- `tailwindcss`: Styling (required)
- `typescript`: Type safety (required)

## Common Patterns

### Fetching Drupal Content
```typescript
import { drupal } from '@/lib/drupal'

// In Server Component
const articles = await drupal.getResourceCollection('node--article', {
  params: {
    'filter[status]': '1',
    'sort': '-created',
  },
})
```

### Error Handling
```typescript
// Use error.tsx for route-level errors
// Use try/catch in Server Components
// Provide fallback UI
```

### Image Handling
```typescript
import Image from 'next/image'

<Image
  src={drupal.buildUrl(node.field_hero_image.uri.url).toString()}
  alt={node.field_hero_image.resourceIdObjMeta.alt}
  width={1200}
  height={600}
/>
```

## Questions to Ask

When implementing features, consider:
- Is this a Server Component or Client Component?
- Should this be SSG, ISR, or SSR?
- Is this accessible?
- Does this follow the atomic design pattern?
- Is error handling in place?
- Are images optimized?
- Is TypeScript happy?

## Anti-Patterns to Avoid

- ❌ Fetching data in Client Components when Server Components can do it
- ❌ Using `useEffect` for data fetching in Server Components
- ❌ Ignoring TypeScript errors
- ❌ Using `any` types
- ❌ Hardcoding URLs or configuration
- ❌ Skipping error handling
- ❌ Using `<img>` instead of `<Image>`
- ❌ Not handling loading states
- ❌ Creating overly complex components
- ❌ Ignoring accessibility

## Project-Specific Notes

- This is a demo/showcase project - prioritize clarity and best practices
- Keep it simple - don't over-engineer
- Focus on demonstrating decoupled architecture patterns
- Make it easy to understand and demo
- Document decisions and trade-offs