plan-forge frontend.instructions.md

TypeScript Frontend Patterns

Component Architecture

File Organization

src/
├── components/        # Reusable UI components
│   ├── Button/
│   │   ├── Button.tsx
│   │   ├── Button.test.tsx
│   │   └── Button.module.css
│   └── ...
├── pages/             # Route-level components
├── hooks/             # Custom React hooks
├── services/          # API client, auth, state
├── types/             # Shared TypeScript types
└── utils/             # Pure utility functions

Component Patterns

// ✅ Typed props with interface
interface UserCardProps {
  user: User;
  onEdit: (id: string) => void;
  isLoading?: boolean;
}

export function UserCard({ user, onEdit, isLoading = false }: UserCardProps) {
  if (isLoading) return <Skeleton />;
  
  return (
    <div className="user-card">
      <h3>{user.name}</h3>
      <button onClick={() => onEdit(user.id)}>Edit</button>
    </div>
  );
}

State Management

Server State (TanStack Query)

import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';

function useUsers() {
  return useQuery({
    queryKey: ['users'],
    queryFn: () => api.getUsers(),
  });
}

function useCreateUser() {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: (data: CreateUserInput) => api.createUser(data),
    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['users'] }),
  });
}

Non-Negotiable Rules

Type Safety

// ❌ NEVER: `any` in props or state
const [data, setData] = useState<any>(null);

// ✅ ALWAYS: Explicit types
const [data, setData] = useState<User | null>(null);

Error Boundaries

// ✅ Wrap route-level components
<ErrorBoundary fallback={<ErrorPage />}>
  <UserDashboard />
</ErrorBoundary>

Accessibility

// ✅ Always include aria attributes for interactive elements
<button aria-label="Delete user" onClick={handleDelete}>
  <TrashIcon />
</button>

CSS & Styling

CSS Modules (Recommended)

// ✅ Scoped styles — no class name collisions
import styles from './UserCard.module.css';

export function UserCard({ user }: UserCardProps) {
  return <div className={styles.card}>{user.name}</div>;
}