Best Practices & Conventions

9.1 File Naming

Type	Pattern	Example
Pages	page.tsx	app/admin/page.tsx
Layouts	layout.tsx	app/admin/layout.tsx
APIs	route.ts	app/api/clients/route.ts
Components	PascalCase	StatCard.tsx, AdminLayout.tsx
Utilities	camelCase	formatDate.ts, validateEmail.ts
Types	PascalCase	types/database.ts

9.2 Import Order

// 1. React/Next.js
import { useState, useEffect } from 'react';
import { NextRequest } from 'next/server';

// 2. Third-party libraries
import { Button } from 'lucide-react';

// 3. Absolute imports (@/)
import { Card } from '@/app/components/ui/Card';
import { ClientQueries } from '@/lib/db';

// 4. Relative imports (./)
import { useAuth } from './AuthProvider';

9.3 Error Handling

Always handle errors at boundaries:

// API routes: return JSON error
try {
  const data = await riskyOperation();
  return NextResponse.json({ data });
} catch (error) {
  console.error('Operation failed:', error);
  return NextResponse.json(
    { error: 'Operation failed' },
    { status: 500 }
  );
}

// Components: show error UI
try {
  await saveData();
} catch (error) {
  setError('Failed to save. Please try again.');
  // Or use error boundary
}

9.4 TypeScript Strictness

Always use types:

// BAD
function process(data) { ... }

// GOOD
interface ProcessData {
  id: string;
  value: number;
}

function process(data: ProcessData): Promise<Result> { ... }

9.5 Database Migrations

Never edit schema.sql directly on production!

Process:

1. Create migration file: database/migrations/014_add_new_table.sql
2. Test locally
3. Run migration: npx tsx scripts/run-migration.ts 014
4. Commit migration file
5. Deploy (migration runs automatically in CI/CD)