Existing 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 main branch:

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

# Pull latest changes
git pull origin main

# 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:

Note: DATABASE_URL is not needed locally. The database is only available in PR preview environments (via Neon branching). See Database in Preview Environments below.

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

Database in Preview Environments

Local development runs without database access. This is by design — use mock data or UI-only mode when developing locally.

When you open a PR to main, a preview environment is automatically created with:

• A staging Railway deployment of your app
• An isolated Neon database branch (a copy of the production database)

DATABASE_URL is automatically injected into the preview environment — no manual setup needed. After the PR is merged, the Neon database branch is deleted.

To test database features:

1. Push your changes to your feature branch
2. Open a PR to main
3. Wait for the preview deploy (a comment with the preview URL will be posted on the PR)
4. Use the preview URL to test database functionality

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 features not working locally

This is expected — the database is not available in local development. Database features only work in PR preview environments.

To test database features:

1. Push your branch and open a PR to main
2. Use the preview URL posted in the PR comments
3. See Branching & PRs for more details on preview deploys

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 Workflow to make your first contribution