Expensify App Coding Standards

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

How to Use

This index lists rule titles only. Before writing or editing code, read the full rule file for every category that applies to the files you touch: each file holds the rule's conditions, exceptions, and the fix it expects.

Before committing, stage everything with git add -A. Then start a general-purpose subagent that follows .claude/agents/code-inline-reviewer.md and reviews git diff --cached $(git merge-base origin/main HEAD). CI runs the same check.

Categories

Quick Reference

Performance

• PERF-1 — No spread in renderItem
• PERF-2 — Return early before expensive work
• PERF-3 — Shared data in list rows comes from OnyxListItemProvider
• 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
• PERF-20 — Defer heavy work to happen after visual transitions
• PERF-21 — List rows read their own Onyx data
• PERF-22 — List rows subscribe to single collection members

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 and document props only where there is something to say
• 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 — Non-trivial new files start with a header description
• CONSISTENCY-14 — Comments explain why the code exists, not what it does
• CONSISTENCY-15 — Write comments as plain, natural sentences
• CONSISTENCY-16 — No AI-generated jargon in code or comments
• CONSISTENCY-17 — Pluralize with PluralForm, not ternaries on a count
• CONSISTENCY-18 — Comment code that is not self-explanatory
• CONSISTENCY-19 — User-facing copy is grammatical and sentence case
• CONSISTENCY-20 — Name functions with a verb that says what they do

Clean React Patterns

• 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
• UI-4 — Type and responsive insets come from tokens
• UI-5 — Reuse an existing style or StyleUtils helper instead of adding a new one

Onyx

• ONYX-1 — Keep Onyx reads off the render path and out of a written tick