Expensify Coding Standards

Coding standards for the Expensify App. Each standard is a standalone file in rules/ with reasoning, examples, and applicability conditions.

Categories

Quick Reference

Performance

• PERF-1 — No spread in renderItem
• PERF-2 — Return early before expensive work
• PERF-3 — Use OnyxListItemProvider in renderItem
• PERF-5 — Shallow over deep comparisons
• PERF-6 — Derive state from props
• PERF-7 — Reset via key prop
• PERF-8 — Handle events in handlers
• PERF-9 — No useEffect chains
• PERF-10 — No useEffect parent communication
• PERF-11 — Optimize data selection
• PERF-12 — Prevent memory leaks
• PERF-13 — Hoist iterator-independent calls
• PERF-14 — Use useSyncExternalStore
• PERF-15 — Clean up async Effects
• PERF-16 — Guard double initialization
• PERF-17 — Pass raw source, index on demand (no pre-built digest)
• PERF-18 — Use usePreMountDestination for RHP pre-mounting
• PERF-19 — Collection selectors return only what the consumer uses

Consistency

• CONSISTENCY-1 — No platform-specific checks in components
• CONSISTENCY-2 — No magic numbers/strings
• CONSISTENCY-3 — No code duplication
• CONSISTENCY-4 — No unused props
• CONSISTENCY-5 — Justify ESLint disables
• CONSISTENCY-6 — Proper error handling
• CONSISTENCY-7 — Localize all user-visible copy
• CONSISTENCY-8 — Localize numbers, amounts, dates and phone numbers
• CONSISTENCY-9 — Name files after what they export
• CONSISTENCY-10 — Follow the JSDoc style guidelines
• CONSISTENCY-11 — Track future work in an issue, not a TODO comment
• CONSISTENCY-12 — Name callbacks for what they do, not the event they handle
• CONSISTENCY-13 — Document component props with a JSDoc block comment
• CONSISTENCY-14 — Non-trivial new files start with a header description
• CONSISTENCY-15 — Comments explain why the code exists, not what it does
• CONSISTENCY-16 — Write comments as plain, natural sentences
• CONSISTENCY-17 — No AI-generated jargon in code or comments
• CONSISTENCY-18 — Pluralize with PluralForm, not ternaries on a count

Clean React Patterns

• CLEAN-REACT-PATTERNS-0 — React Compiler compliance
• CLEAN-REACT-PATTERNS-1 — Composition over configuration
• CLEAN-REACT-PATTERNS-2 — Components own their behavior
• CLEAN-REACT-PATTERNS-3 — Context-free component contracts
• CLEAN-REACT-PATTERNS-4 — No side-effect spaghetti
• CLEAN-REACT-PATTERNS-5 — Keep state narrow
• CLEAN-REACT-PATTERNS-6 — Import the exported prop type instead of ComponentProps
• CLEAN-REACT-PATTERNS-7 — Do not inline prop types on exported components
• CLEAN-REACT-PATTERNS-8 — Use function components, not class components
• CLEAN-REACT-PATTERNS-9 — Use TypeScript types, not propTypes or defaultProps

UI

• UI-1 — Use the correct loading indicator based on navigation context
• UI-2 — New pages must be scrollable
• UI-3 — Do not use inline style objects

Usage

During development: When writing or modifying src/ files, consult the relevant standard files for detailed conditions, examples, and exceptions.

During review: The code-inline-reviewer agent loads all standards from this directory. See .claude/agents/code-inline-reviewer.md.