Developer setup

Prerequisites

Tool	Version	How to get it
Node.js	22.x	`nvm install $(cat .nvmrc)`
pnpm	9.15.x	`corepack enable && corepack prepare pnpm@9.15.0 --activate`
Wrangler	via pnpm	Installed as a workspace dep — no global install needed
Xcode + iOS Simulator	latest	Mac App Store (mobile dev only)
Android Studio	latest	(optional, for Android emulator)
Maestro	latest	`curl -fsSL "https://get.maestro.mobile.dev" \| bash`

First-time setup

git clone https://github.com/emiliolanzalaco/gringo-pay.git
cd gringo-pay
pnpm install

You need environment/secret values for each app. Ask a maintainer for a .env bundle, or use test/sandbox credentials.

API (`apps/api`)

The API reads all config from Cloudflare bindings + secrets. For local dev, create apps/api/.dev.vars:

# Privy
PRIVY_APP_ID=cmml7h69l00kn0cjji6fskqcm
PRIVY_APP_SECRET=<from Privy dashboard>

# Bridge (sandbox)
BRIDGE_API_KEY=sk-test-<...>
BRIDGE_WEBHOOK_SECRET=<from Bridge dashboard>

# Postgres — a Neon branch DB for dev
NEON_DB_URL=postgresql://<user>:<pw>@<host>/<db>?sslmode=require

# For running vitest
TEST_NEON_DB_URL=postgresql://<user>:<pw>@<host>/<db>?sslmode=require

# Base RPC (default is fine)
BASE_RPC_URL=https://mainnet.base.org

Mobile (`apps/mobile`)

Copy apps/mobile/.env.example → apps/mobile/.env.local and fill in Privy + API base URL.

Run everything locally

# API on http://localhost:8787
pnpm --filter @gringo-pay/api dev

# Mobile — Metro dev server
pnpm --filter @gringo-pay/mobile dev
# then press i (iOS simulator) or a (Android emulator)

# Docs on http://localhost:3000
pnpm --filter @gringo-pay/docs dev

# Web on http://localhost:4321
pnpm --filter @gringo-pay/web dev

Or use Turbo to run them all in parallel:

pnpm dev

Sanity checks before opening a PR

The same checks CI runs, in the order they'll fail:

pnpm lint         # ESLint across all workspaces
pnpm typecheck    # tsc --noEmit
pnpm build        # Turbo build all workspaces
pnpm test         # Vitest / Jest — needs TEST_NEON_DB_URL

Or filter to what you touched:

pnpm --filter @gringo-pay/api typecheck
pnpm --filter @gringo-pay/mobile test

Editor setup

VS Code recommended. Install the recommended workspace extensions if prompted (ESLint, Prettier, Tailwind CSS IntelliSense).
On save: format with Prettier, run ESLint fix.
apps/api/worker-configuration.d.ts is generated by wrangler types — don't hand-edit. If you get type errors about missing Env bindings, run pnpm --filter @gringo-pay/api types (or wrangler types).

Prerequisites​

First-time setup​

API (apps/api)​

Mobile (apps/mobile)​

Run everything locally​

Sanity checks before opening a PR​

Editor setup​