App Setup

Set up an existing app for local development.

Overview

Before you start developing on an existing app, you need to:

1. Pull the latest code from the repository
2. Create and configure your environment file
3. Verify your environment variables
4. Run the app locally

Step 1: Pull Latest Code

First, make sure you have the latest code from the develop branch:

# Make sure you're on develop branch
git checkout develop

# Pull latest changes
git pull origin develop

# Install any new dependencies
pnpm install

Step 2: Create Environment File

Each app has its own environment file (.env) located in its app folder, not at the repository root.

# Navigate to the app directory
cd apps/my-app-name

# Copy the example env file
cp .env.example .env

# Open the file to edit
code .env

Common Environment Variables

Most apps require these variables:

Getting DATABASE_URL

The DATABASE_URL contains sensitive database credentials. To get it:

1. Ask an engineer on Slack or in your team channel
2. They will provide you with a connection string that looks like:

   postgresql://user:password@host:5432/database
   

3. Add it to your .env file

Important: Never commit your .env file to git. It's already in .gitignore.

App-Specific Variables

Some apps have additional variables. Check the app's .env.example or README.md for details:

Step 3: Verify Environment Setup

Before running the app, verify your environment is correctly configured:

# Check your env file exists
ls -la apps/my-app-name/.env

# View your env file (be careful not to share this output)
cat apps/my-app-name/.env

Verification Checklist

Step 4: Run the App Locally

Once your environment is configured, start the development server:

# From the repository root
pnpm dev:my-app-name

# The app will start at http://localhost:3000

Expected Output

You should see output like:

▲ Next.js 15.x.x
- Local: http://localhost:3000
- Environments: .env

✓ Ready in 2s

Open http://localhost:3000 in your browser to see the app.

Troubleshooting

"Missing environment variable" error

If you see an error about missing environment variables:

1. Check your .env file exists in apps/my-app-name/
2. Verify all required variables are set
3. Restart the development server

"Database connection failed" error

If you can't connect to the database:

1. Verify your DATABASE_URL is correct
2. Ask an engineer if the database is accessible
3. Check if you're on a VPN (some databases require it)

Port already in use

If port 3000 is already in use:

# Run on a different port
PORT=3001 pnpm dev:my-app-name

App Setup Quiz

Next Steps

Once your app is running locally:

• Review the app's README.md for app-specific documentation
• Check CLAUDE.md for AI development guidelines
• Read PLAN.md to understand current development status
• Start with the Basic Workflow to make your first contribution