Local Development Setup

Install tools, configure accounts, clone repos, and run smoke tests.

This guide covers the shared UXDL toolchain. Project-specific steps live in each repo's README — use this page for the company-wide baseline.

Prerequisites

Tool	Version	Purpose
Node.js	20 LTS	Frontend and backend runtime
pnpm	9.x	Package manager (all JS repos)
Git	Latest	Source control
GitHub CLI	Latest	PRs, auth, repo access
Docker Desktop	Latest	Local PostgreSQL, MongoDB, Redis
AWS CLI v2	Latest	SSO login, S3, ECS (optional locally)

Install (macOS)

bash

# Homebrew baseline
brew install git gh node pnpm watchman docker awscli
 
# Enable pnpm via corepack
corepack enable
corepack prepare pnpm@latest --activate
 
# Authenticate GitHub
gh auth login
 
# Verify
node --version    # v20.x
pnpm --version  # 9.x
docker --version
gh auth status

Windows

Use WSL2 with Ubuntu, then follow the macOS steps inside WSL. Install Docker Desktop with WSL2 integration enabled.

AWS SSO (optional for day one)

Required when you need to pull secrets, access S3, or deploy:

bash

aws configure sso
aws sso login --profile uxdl-dev
export AWS_PROFILE=uxdl-dev

Your manager assigns the SSO profile and permission sets during onboarding.

Clone repositories

bash

mkdir -p ~/uxdl && cd ~/uxdl
 
# Replace with your team's repos from the welcome email
gh repo clone uxdl/uxdl-web
gh repo clone uxdl/uxdl-api

Each repo uses pnpm. Always install from the repo root:

bash

cd uxdl-web && pnpm install --frozen-lockfile
cd ../uxdl-api && pnpm install --frozen-lockfile

Local services (Docker)

Backend services typically need PostgreSQL. Some also use MongoDB. Start only what your repo requires:

yaml

# docker-compose.yml (keep in your backend repo or run standalone)
services:
  postgres:
    image: postgres:16-alpine
    ports: ["5432:5432"]
    environment:
      POSTGRES_USER: uxdl
      POSTGRES_PASSWORD: uxdl
      POSTGRES_DB: uxdl_local
    volumes: [pg_data:/var/lib/postgresql/data]
 
  mongo:
    image: mongo:7
    ports: ["27017:27017"]
    volumes: [mongo_data:/data/db]
 
volumes:
  pg_data:
  mongo_data:

bash

docker compose up -d

Environment files

Copy templates — never commit filled-in env files:

bash

cp .env.example .env.local   # frontend or backend

Frontend (Next.js) — common keys

dotenv

NEXT_PUBLIC_APP_ENV=local
NEXT_PUBLIC_API_URL=http://localhost:4000
NEXT_PUBLIC_COGNITO_USER_POOL_ID=
NEXT_PUBLIC_COGNITO_CLIENT_ID=
NEXT_PUBLIC_COGNITO_DOMAIN=
NEXT_PUBLIC_FIREBASE_API_KEY=
NEXT_PUBLIC_FCM_VAPID_KEY=

Full reference: Environment Variables.

Backend (Express) — common keys

dotenv

NODE_ENV=development
PORT=4000
DATABASE_URL=postgres://uxdl:uxdl@localhost:5432/uxdl_local
COGNITO_REGION=us-east-1
COGNITO_USER_POOL_ID=
CORS_ORIGIN=http://localhost:3000
AWS_REGION=us-east-1
S3_BUCKET=uxdl-uploads-alpha
EMAIL_PROVIDER=ses
EMAIL_FROM=noreply@uxdl.com

Full reference: Environment Variables.

Smoke test

Run these in each cloned repo before opening your first PR:

bash

pnpm install --frozen-lockfile
pnpm lint
pnpm typecheck
pnpm test        # if the repo has tests
pnpm dev         # confirm the app starts

Repo type	Success looks like
Frontend	`http://localhost:3000` loads without console errors
Backend	`curl http://localhost:4000/health` returns `{ "status": "ok" }`

Run UXDL Docs (this portal)

bash

cd uxdl-documentation
npm install
npm run dev

Set port in .env or .env.local:

dotenv

PORT=3010

npm run dev loads env via scripts/next.mjs then starts Next on that port (default 3010).

Health check: curl http://localhost:3010/api/health

Next steps

Work through the Onboarding Checklist — access, learning, first PR.
Read Frontend Overview or Backend Overview for your team.
Review Development Workflow before your first PR.