file-organization

File Organization Standards

Project Structure

src/
├── app/                 # Next.js app directory
│   ├── (auth)/         # Route group
│   ├── (dashboard)/    # Route group
│   ├── api/            # API routes
│   ├── layout.tsx
│   └── page.tsx
├── components/
│   ├── ui/             # Reusable UI components
│   │   ├── Button.tsx
│   │   ├── Input.tsx
│   │   └── Card.tsx
│   └── features/       # Feature-specific components
│       ├── auth/
│       └── dashboard/
├── hooks/              # Custom React hooks
│   ├── useAuth.ts
│   └── useDebounce.ts
├── lib/                # Utilities and helpers
│   ├── api.ts
│   ├── utils.ts
│   └── constants.ts
├── server/             # Server-side code
│   ├── db.ts
│   └── actions/
├── types/              # Shared TypeScript types
│   └── index.ts
└── styles/             # Global styles
    └── globals.css

Naming Conventions

Files

• Components: PascalCase - UserProfile.tsx, Button.tsx
• Hooks: camelCase with 'use' prefix - useAuth.ts, useDebounce.ts
• Utilities: camelCase - formatDate.ts, api.ts
• Types: camelCase or PascalCase - types.ts, User.types.ts
• Tests: Match source file - Button.test.tsx

Variables and Functions

• Components: PascalCase - UserProfile, Button
• Functions: camelCase - fetchUser, formatDate
• Hooks: camelCase with 'use' - useAuth, useDebounce
• Constants: UPPER_SNAKE_CASE - API_BASE_URL, MAX_RETRY_COUNT
• Types/Interfaces: PascalCase - User, UserProfile, ApiResponse

Component File Structure

Single Component File:

// 1. Imports - React, Next.js, external, internal
import { useState } from 'react';
import Link from 'next/link';
import { cn } from '@/lib/utils';
import { Button } from '@/components/ui/Button';

// 2. Types/Interfaces
interface UserCardProps {
  user: User;
  onEdit?: () => void;
}

// 3. Component
export function UserCard({ user, onEdit }: UserCardProps) {
  const [isExpanded, setIsExpanded] = useState(false);
  
  return (
    <div>
      {/* JSX */}
    </div>
  );
}

// 4. Sub-components (if small)
function UserAvatar({ src }: { src: string }) {
  return <img src={src} alt="Avatar" />;
}