Skip to main content

Local Development

1. Install dependencies​

From the repo root:

pnpm install

2. Start Convex​

In a dedicated terminal:

npx convex dev

This generates Convex types and serves the Convex functions used by the web app.

3. Start the Next.js app​

In another terminal:

pnpm dev

By default the app runs at http://localhost:3000.

4. Start the optional Python backend​

The FastAPI service is required for some proxied mobile endpoints, wallet pass operations, add-on routes, and backend-only integrations.

From backend/:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn server:app --reload --port 8001

Then set:

BACKEND_URL=http://127.0.0.1:8001

5. Run the docs site​

If you want the documentation locally:

pnpm docs:install
pnpm docs:dev

The docs app defaults to http://localhost:3001.

6. Verify the stack​

Useful checks:

  • Web app: http://localhost:3000
  • Platform health: http://localhost:3000/api/health
  • Mobile gateway root: http://localhost:3000/api/mobile/backend
  • Optional backend health: http://127.0.0.1:8001/health
  • Docs site: http://localhost:3001

Common local setups​

Web-only​

Use this when working on pages, components, Convex queries, or organizer flows:

  • npx convex dev
  • pnpm dev

Web plus mobile gateway​

Use this when exercising proxied backend flows from mobile/ or app/api/mobile/backend:

  • npx convex dev
  • pnpm dev
  • uvicorn server:app --reload --port 8001

Docs authoring​

Use this when updating documentation content or the docs theme:

  • pnpm docs:install
  • pnpm docs:dev