​
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 [email protected] 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 [email protected]: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 pennylane

# Link your local directory to the Vercel project
vercel link --project=app

# Pull environment variables (root directory)
vercel env pull .env.local
Enable Remote Caching : 
npx turbo login --sso-team=pennylane
npx turbo link --scope=pennylane --yes

​
Local Development Environment

​
Setting Up Local Supabase

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

​
1. Install Docker

Option 1 : 
# 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
Option 2 : 
brew install orbstack

​
2. Start Supabase CLI

# Navigate to the app directory which contains supabase config
cd apps/app

# Start Supabase
supabase start
If running this command fails with an sql error during migrations like this: 
supabase start
Starting database...
Initialising schema...
Seeding globals from roles.sql...
Skipping migration before-supabase-migrations... (file name must match pattern "<timestamp>_name.sql")
Applying migration 20241226143947_magento_enc.sql...
Stopping containers...
ERROR: relation "organization_magento_integrations" does not exist (SQLSTATE 42P01)
At statement: 0
alter table organization_magento_integrations add column api_key_enc jsonb
Please retry after deleting the whole apps/app/supabase/migrations folder. The SQL schema already imported is probably not compatible with the successive changes of those migrations

​
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

For your first run, make sure to launch 
pnpm relay
This will build your graphQL schema (see below “GraphQL Development”) 
# 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)

Install the CLI from here: https://hookdeck.com/docs/cli 
brew install hookdeck/hookdeck/hookdeck

# 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

​
React Developer tools

Useful to find which components are on screen for example for better and quicker debugging. Install here: https://react.dev/learn/react-developer-tools

​
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
If you encounter an authentication error: 
failed to pull docker image: Error response from daemon: {"message":"denied: Your authorization token has expired. Reauthenticate and try again."}
Please retry after logging out of aws: 
docker logout public.ecr.aws

​
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! 🚀