209 lines
5.4 KiB
Markdown
209 lines
5.4 KiB
Markdown
# Coding Standards
|
|
|
|
**Last Updated:** January 2025
|
|
**Project:** Moyos Wedding App
|
|
|
|
---
|
|
|
|
## File and Folder Naming
|
|
|
|
### Files
|
|
- **Components:** `kebab-case.tsx` (e.g., `rsvp-form.tsx`, `guest-card.tsx`)
|
|
- **Utilities:** `kebab-case.ts` (e.g., `request-id.ts`, `rate-limit.ts`)
|
|
- **API Routes:** `route.ts` (Next.js App Router convention)
|
|
- **Types:** `kebab-case.ts` or in feature folders as `types.ts`
|
|
|
|
### Folders
|
|
- **Feature folders:** `kebab-case` (e.g., `rsvp/`, `guestbook/`)
|
|
- **Component folders:** `kebab-case` (e.g., `features/`, `ui/`)
|
|
- **Utility folders:** `kebab-case` (e.g., `lib/`, `hooks/`)
|
|
|
|
---
|
|
|
|
## Type Definitions
|
|
|
|
### Location
|
|
- **Global types:** `src/types/index.ts`
|
|
- **Feature-specific types:** Co-located in feature folders (e.g., `src/components/features/rsvp/types.ts`)
|
|
- **API types:** Co-located with API routes or in `src/types/api.ts`
|
|
|
|
### Naming
|
|
- **Interfaces:** `PascalCase` (e.g., `GuestSession`, `RsvpFormData`)
|
|
- **Types:** `PascalCase` (e.g., `ApiResponse<T>`, `AuditEventType`)
|
|
- **Enums:** `PascalCase` (e.g., `ReportType`, `ExportFormat`)
|
|
|
|
---
|
|
|
|
## Hooks
|
|
|
|
### Naming
|
|
- **All hooks:** Must be prefixed with `use` (e.g., `useGuest`, `useRealtime`, `useMobile`)
|
|
- **File names:** `use-kebab-case.ts` (e.g., `use-guest.ts`, `use-realtime.ts`)
|
|
|
|
### Location
|
|
- **Global hooks:** `src/hooks/`
|
|
- **Feature-specific hooks:** Co-located in feature folders (e.g., `src/components/features/rsvp/use-rsvp.ts`)
|
|
|
|
---
|
|
|
|
## Components
|
|
|
|
### Naming
|
|
- **Component files:** `kebab-case.tsx` (e.g., `rsvp-form.tsx`)
|
|
- **Component names:** `PascalCase` (e.g., `RsvpForm`, `GuestCard`)
|
|
- **Props interfaces:** `ComponentNameProps` (e.g., `RsvpFormProps`)
|
|
|
|
### Organization
|
|
- **Feature components:** `src/components/features/{feature-name}/`
|
|
- **UI components:** `src/components/ui/`
|
|
- **Layout components:** `src/components/layout/`
|
|
|
|
---
|
|
|
|
## API Routes
|
|
|
|
### Structure
|
|
- **Route handlers:** `src/app/api/{route}/route.ts`
|
|
- **Request validation:** Use Zod schemas in `src/lib/validators/`
|
|
- **Error handling:** Standardized error responses
|
|
- **Logging:** Use `logger` with request ID context
|
|
|
|
### Naming
|
|
- **Route files:** `route.ts` (Next.js convention)
|
|
- **Validator files:** `{feature}-validators.ts` (e.g., `rsvp-validators.ts`)
|
|
|
|
---
|
|
|
|
## State Management
|
|
|
|
### Single Source of Truth
|
|
- **Guest state:** `src/context/guest-context.tsx`
|
|
- **Admin state:** To be centralized (currently scattered)
|
|
- **No duplicate state:** Avoid storing same data in multiple places
|
|
|
|
---
|
|
|
|
## Imports
|
|
|
|
### Order
|
|
1. React/Next.js imports
|
|
2. Third-party library imports
|
|
3. Internal component imports
|
|
4. Internal utility imports
|
|
5. Type imports (with `type` keyword)
|
|
6. Relative imports
|
|
|
|
### Example
|
|
```typescript
|
|
import { NextRequest, NextResponse } from 'next/server';
|
|
import { z } from 'zod';
|
|
import { verifyGuestSession } from '@/lib/auth';
|
|
import { logger } from '@/lib/logger';
|
|
import type { GuestSession } from '@/types';
|
|
```
|
|
|
|
---
|
|
|
|
## Code Style
|
|
|
|
### TypeScript
|
|
- **No `any` types:** Use proper types or `unknown`
|
|
- **Strict mode:** Enabled
|
|
- **Type imports:** Use `import type` for type-only imports
|
|
|
|
### Functions
|
|
- **Async functions:** Always handle errors with try-catch
|
|
- **Error logging:** Use `logger.error()` with context
|
|
- **Request ID:** Include in all log contexts
|
|
|
|
### Validation
|
|
- **All API inputs:** Must use Zod validation
|
|
- **Schemas:** Co-located in `src/lib/validators/`
|
|
|
|
---
|
|
|
|
## Testing
|
|
|
|
### File Naming
|
|
- **Unit tests:** `*.test.ts` or `*.test.tsx`
|
|
- **E2E tests:** `*.spec.ts`
|
|
- **Location:** Co-located with source files in `__tests__/` folders
|
|
|
|
### Coverage
|
|
- **Minimum:** 60% global coverage
|
|
- **Critical utilities:** 100% coverage (sanitize, csrf, rate-limit)
|
|
- **API routes:** 80%+ coverage
|
|
|
|
---
|
|
|
|
## Documentation
|
|
|
|
### Comments
|
|
- **Complex logic:** Add explanatory comments
|
|
- **API routes:** JSDoc comments for exported functions
|
|
- **Types:** Document complex types with comments
|
|
|
|
### README Files
|
|
- **Feature folders:** Optional `README.md` for complex features
|
|
- **Main docs:** In `docs/` folder
|
|
|
|
---
|
|
|
|
## Git Commits
|
|
|
|
### Format
|
|
- **Type:** `feat:`, `fix:`, `chore:`, `refactor:`, `docs:`, `test:`
|
|
- **Scope:** Optional feature name
|
|
- **Message:** Clear, concise description
|
|
|
|
### Examples
|
|
- `feat: add request ID tracking to middleware`
|
|
- `fix: correct Zod validation error handling`
|
|
- `chore: remove unused @sendgrid/mail dependency`
|
|
- `refactor: consolidate duplicate RSVP form components`
|
|
|
|
---
|
|
|
|
## Security
|
|
|
|
### Secrets
|
|
- **Never commit:** `.env.local`, `.env.production`
|
|
- **Always validate:** Use Zod schemas for env variables
|
|
- **No client-side secrets:** Never use `NEXT_PUBLIC_*` for secrets
|
|
|
|
### Input Validation
|
|
- **All inputs:** Validate with Zod
|
|
- **File uploads:** Validate magic bytes, size, type
|
|
- **Sanitization:** Use `sanitize.ts` utilities
|
|
|
|
---
|
|
|
|
## Performance
|
|
|
|
### Code Splitting
|
|
- **Large components:** Use `next/dynamic` for lazy loading
|
|
- **Admin components:** Always lazy loaded
|
|
- **Heavy libraries:** Lazy load when possible
|
|
|
|
### Caching
|
|
- **API responses:** Use SWR for client-side caching
|
|
- **Database queries:** Add indexes, optimize queries
|
|
- **Static data:** Cache in Redis when available
|
|
|
|
---
|
|
|
|
## Accessibility
|
|
|
|
### ARIA Labels
|
|
- **Interactive elements:** Always include aria-labels
|
|
- **Form inputs:** Associated labels
|
|
- **Error messages:** Announced to screen readers
|
|
|
|
### Keyboard Navigation
|
|
- **All interactive elements:** Keyboard accessible
|
|
- **Focus management:** Proper focus handling
|
|
|
|
---
|
|
|
|
**This document should be updated as patterns evolve.**
|