Frontend Philosophy

Authoritative conventions for all React/Preact work. These are not suggestions — they are the standard. When in doubt, choose the simpler path.

"Every line of code is a liability. The best code is no code. The second best is simple, boring code that obviously works."

Core Principles

1. Simplicity over cleverness — Write code a junior dev understands
2. Convention over configuration — Follow existing patterns, don't invent
3. Optimize for understanding — Code is read 10x more than written
4. Embrace the monolith — Colocate related concerns, don't split prematurely
5. Performance through simplicity — Fastest code is code that doesn't run

Stack Defaults

Why No TypeScript

Speed over ceremony. Type gymnastics add grief, not joy. Runtime validation at system boundaries, shared constants, JSDoc for complex functions.

File Conventions

src/
├── components/
│   ├── ui/              # Base UI (shadcn pattern)
│   ├── billing/         # Feature-based grouping
│   ├── support/         # NOT type-based (lists/, forms/, displays/)
│   └── common/          # Shared across features
├── hooks/               # Custom hooks (use* prefix)
├── stores/              # Zustand stores
├── constants/           # Shared constants
├── lib/                 # Utilities (cn, formatters)
├── pages/               # Route-level components
└── api/                 # API client

Naming rules:

• .jsx components, .js utilities — always
• PascalCase component files, camelCase everything else
• handle* event handlers, use* hooks, render* render methods
• Feature-based folders, never type-based
• No barrel files (index.ts/js re-exports) — ever
• No comments unless logic is truly non-obvious

Component Structure (8 Sections)

Every component follows this order. See references/component-patterns.md for full examples.

const Component = ({ prop1, prop2 }) => {
  // 1. Server state (TanStack Query)
  const { data, isLoading, error } = useQuery({ ... });

  // 2. Global client state (Zustand/signals)
  const { theme } = useThemeStore();

  // 3. Local state (useState)
  const [isOpen, setIsOpen] = useState(false);

  // 4. Refs
  const formRef = useRef(null);

  // 5. Custom hooks
  const { isOnline } = useNetworkStatus();

  // 6. Derived values (compute in render, no useState)
  const isValid = email.includes("@");
  const fullName = `${data?.first} ${data?.last}`;

  // 7. Effects (DOM sync, subscriptions, analytics ONLY)
  useEffect(() => { ... }, [deps]);

  // 8. Event handlers
  const handleSubmit = () => { ... };

  // Return — early returns for loading/error first
  if (isLoading) return <Skeleton />;
  if (error) return <ErrorMessage error={error} />;

  return ( ... );
};

State Management Rules

Server State = TanStack Query ONLY

// CORRECT — single source of truth
const { data: users } = useQuery({
  queryKey: ["users", filters],
  queryFn: () => api.get("/users", { params: filters }),
  staleTime: 5 * 60 * 1000,
  gcTime: 60 * 60 * 1000,    // NOT cacheTime (v5)
});

// WRONG — duplicating server data in local state
const [users, setUsers] = useState([]);
useEffect(() => { fetchUsers().then(setUsers); }, []);

Client State = Zustand or Signals

Only for UI concerns: modals, theme, sidebar, filters, form inputs.

Derive, Don't Duplicate

// CORRECT — derive in render
const hasError = error !== null;
const activeUsers = users?.filter(u => u.isActive);

// WRONG — useState for derived values
const [hasError, setHasError] = useState(false);
useEffect(() => setHasError(error !== null), [error]);

Data Fetching Hierarchy

1. Pages fetch all required data
2. Pass data as props to children
3. Never refetch in children when parent has the data

Critical Anti-Patterns

These are hard rules, not guidelines.

Valid useEffect Uses

Only three:

1. DOM synchronization (focus, scroll, resize listeners)
2. External subscriptions (WebSocket, event emitters)
3. Analytics/logging (page views, tracking)

Everything else belongs in an event handler or TanStack Query.

Formatting

Prettier defaults:

• 2-space indent, double quotes, semicolons
• 100 char print width, trailing commas ES5
• Tailwind plugin for class ordering

UI Patterns

• Buttons: always rounded-full
• Cards: always rounded-xl
• Use cn() from @/lib/utils for class merging
• Use CVA (class-variance-authority) for component variants
• Composition over configuration — build with children and slots
• data-slot attributes for CSS targeting
• Early returns for loading/error states before main render

Code Review Questions

Before shipping, ask:

1. Can a junior dev understand this?
2. Is this the simplest solution that works?
3. Does this follow existing patterns in the codebase?