Setup Guide

Development Setup Guide

This guide walks you through setting up a complete local development environment for Global Watch.

Prerequisites

Before you begin, ensure you have the following installed:

Required Software

Software	Version	Purpose
Node.js	20.x or later	JavaScript runtime
pnpm	9.x or later	Package manager
Docker	Latest	Required for local Supabase
Git	Latest	Version control

Installing Prerequisites

Node.js (using nvm recommended):

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install Node.js 20
nvm install 20
nvm use 20

pnpm:

# Install pnpm globally
npm install -g pnpm@latest

Docker:

macOS: Install Docker Desktop
Linux: Follow the Docker Engine installation guide
Windows: Install Docker Desktop with WSL2

Initial Setup

1. Clone the Repository

git clone https://github.com/your-org/globalwatch.git
cd globalwatch

2. Install Dependencies

pnpm install

This installs all dependencies for the entire monorepo, including:

apps/web - Main Next.js application
apps/mobile - Expo React Native app
apps/docs - Documentation site
packages/* - Shared packages

3. Start Local Supabase

Ensure Docker is running, then start the local Supabase instance:

pnpm supabase:web:start

This command:

Starts PostgreSQL database
Starts Supabase Auth
Starts Supabase Storage
Starts Supabase Studio (admin UI)
Applies all migrations
Seeds the database with test data

Supabase Studio will be available at: http://localhost.direct:54323

4. Start the Development Server

pnpm dev

This starts all applications in development mode with Turbopack for fast refresh.

Accessing the Application

Global Watch uses subdomain-based routing. Use localhost.direct (which resolves to 127.0.0.1):

URL	Description
http://localhost.direct:3000	Marketing site
http://app.localhost.direct:3000	Personal account dashboard
http://acme.localhost.direct:3000	Team account (replace `acme` with team slug)
http://localhost.direct:54323	Supabase Studio

Test Credentials

After seeding, you can log in with:

Email: test@example.com
Password: password123

Environment Variables

File Structure

All environment variables are centralized at the monorepo root:

/                           # Monorepo root
├── .env                    # Shared base config (committed)
├── .env.development        # Development defaults (committed)
├── .env.production         # Production template (committed)
├── .env.test               # Test environment (committed)
├── .env.local              # Local overrides (gitignored)
└── .env.example            # Template with documentation

Loading Order

Files are loaded in this order (later files override earlier):

.env - Base configuration
.env.development / .env.production / .env.test - Environment-specific
.env.local - Local overrides (highest priority)

Required Variables

The following variables are required for development:

# Supabase
NEXT_PUBLIC_SUPABASE_URL=http://localhost.direct:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=<your-anon-key>
SUPABASE_SERVICE_ROLE_KEY=<your-service-role-key>

# URLs
NEXT_PUBLIC_SITE_URL=http://localhost.direct:3000
NEXT_PUBLIC_APP_URL=http://app.localhost.direct:3000
NEXT_PUBLIC_BASE_DOMAIN=localhost.direct:3000

# Feature Flags
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS=true
NEXT_PUBLIC_ENABLE_THEME_TOGGLE=true

Variable Naming Conventions

Prefix	Framework	Exposed To
`NEXT_PUBLIC_*`	Next.js	Browser (client-side)
`EXPO_PUBLIC_*`	Expo	Mobile app (client-side)
No prefix	All	Server-side only

Creating Local Overrides

For local customizations, create .env.local:

# .env.local (gitignored)
NEXT_PUBLIC_ENABLE_DEBUG=true
MY_SECRET_API_KEY=your-secret-key

Important Rules:

NEVER create .env* files in apps/ directories
NEVER commit sensitive values
ALWAYS use localhost.direct (not localhost)

HTTPS Development

For features requiring HTTPS (OAuth, secure cookies), use Caddy:

1. Install Caddy

# macOS
brew install caddy

# Linux
sudo apt install caddy

2. Start with HTTPS

pnpm dev:https

3. Access via HTTPS

URL	Description
https://localhost.direct:3443	Marketing site
https://app.localhost.direct:3443	Personal account

4. Configure Environment

Create .env.local with HTTPS URLs:

NEXT_PUBLIC_BASE_DOMAIN=localhost.direct:3443
NEXT_PUBLIC_APP_URL=https://app.localhost.direct:3443
NEXT_PUBLIC_SUPABASE_URL=https://localhost.direct:54399

Database Management

Viewing the Database

Access Supabase Studio at http://localhost.direct:54323 to:

Browse tables and data
Run SQL queries
Manage authentication users
View storage buckets

Creating Migrations

When you modify the database schema:

# 1. Make changes to schema files in apps/web/supabase/schemas/

# 2. Generate a migration
pnpm --filter web supabase:db:diff my-migration-name

# 3. Reset database to apply changes
pnpm supabase:web:reset

Resetting the Database

To reset the database to a clean state:

pnpm supabase:web:reset

This will:

Drop all tables
Re-apply all migrations
Re-seed with test data

Generating TypeScript Types

After schema changes, regenerate types:

pnpm supabase:web:typegen

Running Tests

Unit Tests

# Run all unit tests
pnpm --filter web test:run

# Run tests in watch mode
pnpm --filter web test

# Run tests with coverage
pnpm --filter web test:coverage

E2E Tests

# Run E2E tests
pnpm --filter e2e test

# Run E2E tests with UI
pnpm --filter e2e test:ui

Troubleshooting

Common Issues

Port Already in Use

If port 3000 is already in use:

# Find the process
lsof -i :3000

# Kill it
kill -9 <PID>

Docker Not Running

If Supabase fails to start:

# Check Docker status
docker info

# Start Docker Desktop (macOS/Windows)
# or start Docker service (Linux)
sudo systemctl start docker

Database Connection Issues

If you can't connect to the database:

# Check Supabase status
pnpm supabase:web:status

# Restart Supabase
pnpm supabase:web:stop
pnpm supabase:web:start

Type Errors After Schema Changes

If you see type errors after database changes:

# Regenerate types
pnpm supabase:web:typegen

# Restart TypeScript server in your IDE

Getting Help

If you're still stuck:

Check the GitHub Issues
Search the codebase for similar patterns
Ask in the team communication channel

Next Steps

Coding Conventions - Learn our coding standards
Architecture Overview - Understand the system design
Database Design - Learn about the database schema

Setup Guide

On this page