Local Development Setup
Prerequisites
| Tool | Version | Why |
|---|---|---|
| Node.js | 20 LTS | Web app + mobile build |
| npm | 10+ | Package manager (we don't use yarn/pnpm) |
| Postgres | 14+ (or Cloud SQL Proxy) | Local DB for testing |
| Java JDK | 17 | Android build (brew install openjdk@17) |
| Android SDK | latest | Mobile APK build (~/Library/Android/sdk) |
gcloud CLI | latest | Production access |
gh CLI | latest | GitHub auth + workflow runs |
Clone + install
git clone git@github.com:sidgk/ka26-marketplace.git
cd ka26-marketplace
npm ci
cp .env.example .env # then fill in DATABASE_URL etc
npx prisma generate
Run web
npm run dev # localhost:3000
Run mobile
cd mobile
npm ci
npx expo start # opens Expo Dev Tools
For an actual APK build:
cd mobile
ANDROID_HOME=/Users/siddu/Library/Android/sdk npx expo prebuild --platform android --clean
cd android
ANDROID_HOME=/Users/siddu/Library/Android/sdk JAVA_HOME=/opt/homebrew/opt/openjdk@17 ./gradlew assembleRelease
# Output: android/app/build/outputs/apk/release/app-release.apk
Full mobile release process: Mobile → Build & Release.
Connecting to production DB (use sparingly)
PGPASSWORD=<secret> psql -h 34.123.40.64 -U ka26user -d ka26
Credentials in 1Password (org vault → "KA26 Production DB"). Never log queries that contain PII.
Running tests
npm test # Web (1874 tests, <1s)
npm run test:smoke # Web E2E vs production (~20s)
cd mobile && npx vitest run # Mobile vitest (321 tests)
cd mobile && npx jest --forceExit --detectOpenHandles # Mobile Jest (103 tests)
CI runs all of these on every push. See Deploy & CI/CD.
Common local-dev gotchas
- Prisma "Cannot connect to database" → Cloud SQL proxy isn't running.
cloud-sql-proxy school-mgmt-saas:us-central1:school-db & - Mobile build "JAVA_HOME not set" → use the full env-var prefix shown above. The Expo prebuild needs both ANDROID_HOME and JAVA_HOME explicitly.
- Port 3000 in use →
lsof -ti:3000 | xargs kill - Tests pass locally, fail in CI → 99% of the time it's a node version mismatch; CI uses Node 20.