Temple
Gym management app — Expo (web target) on top of Supabase (Postgres + auth + storage + RLS).
Setup
Prereqs:
- Docker (for the local Supabase stack)
- Node 22
- Supabase CLI matching
package.json#supabase.cli_version. npm run dev warns if your local CLI doesn't match.
From a fresh clone:
npm install
npm run dev
npm run dev does, in order: start the local Supabase stack if it isn't running, write .env.local pointing at it (only if the file doesn't exist), then hand off to expo start --web. Open the URL it prints.
The local DB is seeded with two ready-made logins (run supabase db reset first if you started the stack before the seed existed):
Seeds run only on local supabase db reset — they never reach the hosted project. You can also sign up a fresh account and walk through Start a new gym.
To pull main + reinstall deps + replay migrations in one go:
npm run sync
Local vs hosted Supabase
.env.local is auto-generated to point at the local stack (http://127.0.0.1:54321). To debug against your hosted project, edit .env.local with the URL + anon key from dashboard.supabase.com → project → API:
EXPO_PUBLIC_SUPABASE_URL=https://<project>.supabase.co
EXPO_PUBLIC_SUPABASE_ANON_KEY=<anon-key>
.env.local is gitignored — never commit it.
Optional: in-app "talk to your AI" voice calls
The CRM dashboard, setup wizard, and Automation settings can open a live
browser voice call with a gym's AI assistant (no phone number needed).
This needs Vapi's public key (dashboard.vapi.ai → API Keys, not the
private key used server-side):
EXPO_PUBLIC_VAPI_KEY=<public-key>
Without it, those entry points show as unavailable rather than failing.
Migration flow
- Author SQL in
supabase/migrations/NNNN_description.sql.
supabase db reset replays every migration against the local DB. Catches order / syntax / RLS problems immediately.supabase test db runs the pgTAP suite. Author a _self_only.sql or similar for any RLS change.- Commit + push.
- Merging to
main runs the db-deploy CI job which sends the migration to the hosted project. No manual supabase db push needed.
CI contract
Three jobs in .github/workflows/ci.yml:
| Job | When | What |
|---|
check | every push + PR | tsc --noEmit + npm test |
db-tests | every push + PR | supabase start + supabase test db against a fresh local stack |
db-deploy | push to main only, after both gates pass | supabase db push --include-all against the hosted project |
db-deploy needs three repo secrets (Settings → Secrets and variables → Actions):
SUPABASE_ACCESS_TOKEN — personal access token from https://supabase.com/dashboard/account/tokensSUPABASE_PROJECT_REF — the hosted project ref (the slug in the dashboard URL)SUPABASE_DB_PASSWORD — hosted DB password (used by supabase db push)
Without these the job will fail loudly on first push to main; add them before merging anything that touches migrations.
Pre-commit hook
npm install wires a husky hook at .husky/pre-commit that:
- Sets
user.email + user.name on the local repo if not already configured (avoids unverified commits).
- Runs
tsc --noEmit and npm test.
Skip with git commit --no-verify if you really need to.
Claude Code sessions
.claude/settings.json registers a SessionStart hook (scripts/session-start.sh). On every session start it sets the git author if unset and fetches origin/main; if the workspace is sitting on a throwaway claude/* branch with a clean tree and every commit pushed, it switches to a synced main. Cloud containers reset onto stale branches between sessions — this keeps new sessions from building on weeks-old code. It never touches a branch with uncommitted or unpushed work.
Troubleshooting
| Symptom | Fix |
|---|
supabase start complains about port conflicts | supabase stop --all then retry, or check docker ps --filter publish=54322. |
Invalid db.major_version: 17 in CI | Bump package.json#supabase.cli_version to a release that supports Postgres 17 (≥ 2.40). |
Missing Supabase env vars page in browser | Delete .env.local and re-run npm run dev to regenerate. |
CLI mismatch warning from npm run dev | Either bump local CLI (brew upgrade supabase etc.) or change package.json#supabase.cli_version to match your local. |
Stuck on /welcome after creating a gym | Hard-reload the browser. The membership query is pinned to refetchOnMount: false; any flow that changes membership must await refreshMembership(queryClient) (exported from src/lib/auth.ts) before navigating. |
