Nextjs Components

Server vs Client Component Decision

Use Server Component (default - no directive needed):

• Data display and fetching
• Static content rendering
• SEO-critical pages
• Layout components
• Components that only pass data down

Add "use client" only when ANY of these apply:

• Event handlers: onClick, onChange, onSubmit
• React hooks: useState, useEffect, useRef
• Browser APIs: localStorage, window, navigator
• Third-party client libraries: framer-motion animations, chart libraries

Props Design Rules

1. Always define props as a separate type (not inline)
2. Export the props type for reusability
3. Use optional props with defaults for variants
4. Always include className?: string for style extension
5. Use React.ReactNode for children, not JSX.Element
6. Prefer union types over boolean flags: variant: "sm" | "md" | "lg" not isLarge: boolean

Styling Rules

• Use Tailwind CSS exclusively, never inline styles
• Use cn() helper from @/lib/utils for conditional classes
• Mobile-first responsive: base → sm: → md: → lg: → xl:
• Use CSS variables for theme colors (defined in globals.css)
• Prefer shadcn/ui components and customize them
• Use Framer Motion for animations (when "use client" is already needed)

Composition Pattern

Prefer composition over prop drilling:

// GOOD - Composition
<Card>
  <Card.Header>
    <Card.Title>Title</Card.Title>
  </Card.Header>
  <Card.Content>Content</Card.Content>
</Card>

// AVOID - Too many props
<Card
  title="Title"
  subtitle="Sub"
  headerIcon={icon}
  footerAction={action}
  // ...20 more props
/>

Anti-Patterns (NEVER DO)

• Never use any type for props
• Never use index as key in lists
• Never use useEffect for data fetching (use Server Component or React Query)
• Never use inline styles
• Never use var keyword
• Never use default exports for components
• Never put "use client" on Server Components
• Never use barrel exports (index.ts re-exports) - breaks tree-shaking

Additional Resources

• references/patterns.md - Advanced component patterns catalog
• references/form-patterns.md - Form handling with react-hook-form + zod
• examples/ - Complete working component examples