​
Getting Started

This guide will help you set up your development environment for the Billy monorepo.

​
Welcome Fellow Dev

As a Billy developer, you should have an email xxx@pennylane.com and access to the following accounts:

​
Essential Services

​
Development Tools

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Node.js (v24 or higher)
  • pnpm package manager
  • Git
You can install them with brew.

​
Initial Setup

​
1. Clone and Install Dependencies

# Clone the repository
git clone git@github.com:pennylane-hq/billy.git
cd billy

# Install dependencies
pnpm install

​
2. Install Global Tools

# Install Vercel CLI
pnpm i -g vercel@latest

# Ensure you have version > 44.7.3
vercel --version

# Install Supabase CLI
brew install supabase/tap/supabase
brew upgrade supabase

# Ensure you have version > 2.34.3
supabase -v
If you don’t have access to Vercel, contact any Billy developer to get access. 
# Login to Vercel
vercel login

# Link to the Billy project
vercel link

# Pull environment variables
vercel env pull .env.local

​
4. Login to Turbo

npx turbo login

​
Local Development Environment

​
Setting Up Local Supabase

Billy uses Supabase for local development. Follow these steps to set up your local database:

​
1. Install Podman

# Install Podman Desktop
brew install podman-desktop

# Enable Docker compatibility
# Follow the guide at: https://podman-desktop.io/docs/migrating-from-docker/managing-docker-compatibility

​
2. Start Supabase

# Navigate to the app directory
cd apps/app

# Start Supabase (ignore health check for first run)
supabase start --ignore-health-check

​
3. Configure Environment Variables

After starting Supabase, add these variables to your .env.local: 
# Billy [Local]
NEXT_PUBLIC_SUPABASE_ANON_KEY=(anon key from supabase start output)
SUPABASE_SERVICE_ROLE_KEY=(service_role key from supabase start output)
NEXT_PUBLIC_SUPABASE_URL=http://localhost:54321
SUPABASE_JWT_SECRET=super-secret-jwt-token-with-at-least-32-characters-long
POSTGRES_HOST="localhost"
POSTGRES_PORT=54322
POSTGRES_DATABASE="postgres"
POSTGRES_PASSWORD="postgres"
POSTGRES_USER="postgres"

​
4. Access Local Supabase

​
5. Populate Database

# Import SQL schema and fixtures
pnpm populate

​
Setting Up Upstash (Redis)

For local development with Redis:
  1. Go to Upstash Console
  2. Create a new database named “billy dev” in “eu-central-1”
  3. Add these environment variables to .env.local:
# Billy [Local]
UPSTASH_REDIS_REST_URL=YOUR_SECRET_VALUE_GOES_HERE
UPSTASH_REDIS_REST_TOKEN=YOUR_SECRET_VALUE_GOES_HERE

​
Setting Up Pennylane Sandbox

To use your own Pennylane sandbox:
  1. Go to Pennylane Sandbox
  2. Create your own sandbox
  3. Get your API key from the developer settings
  4. Add to .env.local:
FIXTURES_BILLY_PENNYLANE_INTEGRATION_API_TOKEN=YOUR_SECRET_VALUE_GOES_HERE
  1. Reset your SQL schema and run pnpm populate

​
Starting Development

​
Basic Commands

# Start all development servers
pnpm dev

# Run tests
pnpm test

# Run linting
pnpm lint -- --quiet

# Type checking
pnpm ts

# Format code
pnpm format

​
Access Your Application

​
Development Tools

​
Cloudflare Workers

# Start workers in development mode
pnpm run workers-dev

​
Hookdeck (Webhook Testing)

# Login to Hookdeck
hookdeck login

# Listen to local port
hookdeck listen 3000

​
GraphQL Development

# Install watchman for file watching
brew install watchman

# Start GraphQL relay in watch mode
pnpm relay:watch

​
Database Management

​
Creating Migrations

# Create a new migration
supabase migration new "useful_name"

# Test migration locally
supabase migration up --local

​
Applying Migrations

# Apply migrations to production
supabase migration up --linked
View applied migrations at: Supabase Dashboard

​
Configure Slack GitHub Reminders

To stay updated on GitHub activities and receive real-time alerts:
  1. Join the Slack channel: #squad-billy-github-reminder
  2. Configure GitHub integration: Go to GitHub Settings > Reminders
  3. Enable real-time alerts: Follow the documentation at Pennylane Tooling GitHub
This will help you stay informed about:
  • Pull request reviews and comments
  • Issue updates and assignments
  • Repository activities
  • Team collaboration updates

​
Troubleshooting

​
Common Issues

  • Supabase won’t start: Ensure Podman is running and Docker compatibility is enabled
  • Port conflicts: Check if ports 3000, 54321-54324, 3045 are available
  • Environment variables: Ensure .env.local is properly configured

​
Next Steps

Once you have your environment set up:
  1. Read the Development Workflow guide
  2. Explore the Architecture Overview
  3. Review Contributing Guidelines
  4. Start developing! 🚀