Getting Started - New Expensify

Welcome Contributors!

Thank you for your interest in contributing to New Expensify! This guide will help you get started with your first contribution.

Before contributing, please read the Contributing Guidelines and Code of Conduct.

Prerequisites

Required Knowledge

JavaScript/TypeScript: Strong understanding required
React & React Native: Experience building React applications
Git: Familiarity with branching, commits, and pull requests
Command Line: Comfortable using terminal/command prompt

Environment Setup

See Development Setup for detailed instructions.

Quick Start

# 1. Install nvm (if not installed)
brew install nvm

# 2. Install Node.js and npm
nvm install

# 3. Install watchman
brew install watchman

# 4. Clone the repository
git clone https://github.com/Expensify/App.git
cd App

# 5. Install dependencies
npm install

# 6. Run the app
npm run web     # For web development
npm run ios     # For iOS (Mac only)
npm run android # For Android

Finding Issues to Work On

For External Contributors

Browse GitHub Issues: Look for issues with the Help Wanted label
Check Upwork: View available jobs on Upwork
Follow @ExpensifyOSS: Get notified of new jobs on Twitter

Before Proposing

Do not submit proposals before the Help Wanted label is added to an issue. Proposals submitted early will be ignored.

Check for existing proposals: Read other proposals to ensure yours is different
Reproduce the issue: Verify you can reproduce the problem
Test on all platforms: iOS, Android, Web, mWeb, macOS

Creating Test Accounts

You can create test accounts directly at new.expensify.com.

Important Guidelines

Use + in email addresses: e.g., yourname+test1@gmail.com
- Marks accounts as test accounts
- Prevents assignment of Expensify Guides
Do not chat with Concierge: This diverts to customer support
Do not interact with onboarding teams: Let them know you’re a contributor
Do not post in public rooms: Use test rooms or this staging room

Generating Multiple Test Accounts

Use the + postfix in emails:

test+1@example.com
test+2@example.com
test+123@example.com

All emails go to test@example.com but create separate accounts.

Making Your First Contribution

Step 1: Reproduce the Issue

# Ensure you're on the latest main branch
git checkout main
git pull origin main

# Start the app
npm run web

Follow the steps in the GitHub issue to reproduce the problem.

Step 2: Create a Proposal

Only after reproducing the issue and after the Help Wanted label is added.

Use the Proposal Template:

## Proposal

### Please re-state the problem that we are trying to solve in this issue
[Explain the problem in your own words]

### What is the root cause of that problem?
[Identify the root cause with file paths and line numbers]

### What changes do you think we should make in order to solve the problem?
[Detailed solution with code examples]

### What alternative solutions did you explore? (Optional)
[Other approaches you considered]

Proposal Guidelines

Be specific: Include file paths and line numbers
Be different: Don’t duplicate existing proposals
Be thorough: Explain root cause, not just symptoms
One proposal only: Don’t submit multiple proposals for same issue

Step 3: Wait for Selection

Once a Contributor+ (C+) or Expensify engineer reviews proposals:

If selected, you’ll be hired on Upwork
The GitHub issue will be assigned to you
You can then begin coding

New contributors: Work on one job at a time. Don’t propose on new jobs until your first PR is merged.

Step 4: Create a Branch

# Create a new branch from main
git checkout main
git pull origin main
git checkout -b fix/issue-description

# Example:
git checkout -b fix/chat-not-scrolling

Step 5: Make Your Changes

# Make code changes
# Test thoroughly on all platforms

# Format code with Prettier (REQUIRED)
npm run prettier

# Run linter
npm run lint

# Run type check
npm run typecheck-tsgo

Post-Edit Checklist: Always run Prettier, ESLint, and TypeScript checks before committing.

Step 6: Commit Changes

All commits must be signed. See Signing Commits below.

# Stage changes
git add .

# Commit with a clear message
git commit -m "Fix: Prevent chat from scrolling on new message"

# Push to your fork
git push origin fix/chat-not-scrolling

Step 7: Create Pull Request

Go to GitHub and create a pull request from your branch
Fill out every section of the PR template
Link the issue: Fixes https://github.com/Expensify/App/issues/12345
Provide test steps for each platform
Include screenshots for each platform

Incomplete PR checklists are a violation of Rule #2 and may result in warnings.

Step 8: Code Review

Your PR will be reviewed by:

A Contributor+ (C+) team member
An Expensify engineer

During Review:

Respond to feedback promptly
Make requested changes
Post “Updated” comment when ready for re-review
Provide daily updates on weekdays
Never force push after review starts

Step 9: Deployment & Payment

Once your PR is:

Merged: PR is merged to main
Deployed to Staging: Tested on staging environment
Deployed to Production: Released to all users
Regression Period: 7 days after production deploy
Payment: Issued 7+ days after production deploy (if no regressions)

Payment timing: Minimum 7 days after production deployment. If regressions occur, payment is delayed until they’re fixed.

Signing Commits

All commits must be signed with GPG.

Setup GPG Signing

# 1. Generate GPG key
gpg --full-generate-key
# Select RSA, 4096 bits, no expiration
# Use your GitHub email

# 2. Get your GPG key ID
gpg --list-secret-keys --keyid-format LONG
# Copy the key ID after "sec   rsa4096/"

# 3. Export public key
gpg --armor --export YOUR_KEY_ID
# Copy the output

# 4. Add to GitHub
# Go to GitHub Settings > SSH and GPG keys
# Click "New GPG key" and paste

# 5. Configure git
git config --global user.signingkey YOUR_KEY_ID
git config --global commit.gpgsign true
git config --global gpg.program gpg

Now all commits will be automatically signed.

Working on Beta Features

Some features are behind beta flags during development:

// Override in your local environment
// src/libs/Permissions.ts
export function canUseAllBetas(): boolean {
  return true; // Change from checking beta list
}

Communication Channels

Slack: #expensify-open-source

For general questions and discussions.

Do not DM Expensify team members. They cannot respond to direct messages.

To join:

Fill out this form
Include your email and Upwork profile
Wait for approval

GitHub Issues

For job-specific questions, always comment on the GitHub issue, not Slack.

Email

Security vulnerabilities: security@expensify.com (subject: “Vulnerability Report”)
General inquiries: contributors@expensify.com

Payment Information

Getting Paid

Create Upwork account: Ensure profile is fully verified
Add profile to GitHub: Link in your GitHub bio
Apply on Upwork: After proposal is selected on GitHub
Payment timeline: 7+ days after production deployment

Unverified Upwork profiles risk non-payment. Verify your profile before accepting jobs.

Payment via Expensify

Contributors can receive payment via Expensify 18 months after first assignment. See PAYMENT_VIA_EXPENSIFY.md for details.

Common Mistakes

1. Not Reading Documentation

Read CLAUDE.md, README.md, and CONTRIBUTING.md in full before asking questions.

2. Proposing Too Early

Wait for the Help Wanted label before proposing.

3. Not Testing All Platforms

Test on iOS, Android, Web, and mWeb before submitting.

4. Skipping Prettier

Always run npm run prettier before committing. CI will fail otherwise.

5. Not Signing Commits

Set up GPG signing before your first commit.

6. Force Pushing During Review

Never force push after review starts - it breaks review history.

Tips for Success

1. Start Small

Begin with smaller issues to learn the codebase.

2. Read Existing Code

Study similar features to understand patterns.

3. Ask Questions Early

If stuck reproducing an issue, ask in the GitHub issue.

4. Provide Daily Updates

Comment on your PR daily with progress updates.

5. Be Patient

Reviews take time. Use the waiting period to work on tests or documentation.

Next Steps

Development Setup

Detailed environment setup for all platforms

Coding Standards

Code style and best practices

Testing

Writing and running tests

Pull Requests

PR process and review guidelines

​Welcome Contributors!

​Prerequisites

​Required Knowledge

​Recommended Reading

​Environment Setup

​Quick Start

​Finding Issues to Work On

​For External Contributors

​Before Proposing

​Creating Test Accounts

​Important Guidelines

​Generating Multiple Test Accounts

​Making Your First Contribution

​Step 1: Reproduce the Issue

​Step 2: Create a Proposal

​Proposal Guidelines

​Step 3: Wait for Selection

​Step 4: Create a Branch

​Step 5: Make Your Changes

​Step 6: Commit Changes

​Step 7: Create Pull Request

​Step 8: Code Review

​Step 9: Deployment & Payment

​Signing Commits

​Setup GPG Signing

​Working on Beta Features

​Communication Channels

​Slack: #expensify-open-source

​GitHub Issues

​Email

​Payment Information

​Getting Paid

​Payment via Expensify

​Common Mistakes

​1. Not Reading Documentation

​2. Proposing Too Early

​3. Not Testing All Platforms

​4. Skipping Prettier

​5. Not Signing Commits

​6. Force Pushing During Review

​Tips for Success

​1. Start Small

​2. Read Existing Code

​3. Ask Questions Early

​4. Provide Daily Updates

​5. Be Patient

​Next Steps

Development Setup

Coding Standards

Testing

Pull Requests

​Additional Resources

Welcome Contributors!

Prerequisites

Required Knowledge

Recommended Reading

Environment Setup

Quick Start

Finding Issues to Work On

For External Contributors

Before Proposing

Creating Test Accounts

Important Guidelines

Generating Multiple Test Accounts

Making Your First Contribution

Step 1: Reproduce the Issue

Step 2: Create a Proposal

Proposal Guidelines

Step 3: Wait for Selection

Step 4: Create a Branch

Step 5: Make Your Changes

Step 6: Commit Changes

Step 7: Create Pull Request

Step 8: Code Review

Step 9: Deployment & Payment

Signing Commits

Setup GPG Signing

Working on Beta Features

Communication Channels

Slack: #expensify-open-source

GitHub Issues

Email

Payment Information

Getting Paid

Payment via Expensify

Common Mistakes

1. Not Reading Documentation

2. Proposing Too Early

3. Not Testing All Platforms

4. Skipping Prettier

5. Not Signing Commits

6. Force Pushing During Review

Tips for Success

1. Start Small

2. Read Existing Code

3. Ask Questions Early

4. Provide Daily Updates

5. Be Patient

Next Steps

Additional Resources