Skip to content
Vox Pop Core

Quick start

This guide gets you from a fresh clone to a running /api/v1/* service against the Firebase emulators in about 5 minutes.

Prerequisites

Section titled “Prerequisites”
  • Node.js 22+
  • Firebase CLI — npm install -g firebase-tools
  • (Optional) A Firebase project if you want to run against real Firebase instead of the emulators.

1. Clone and install

Section titled “1. Clone and install”
Terminal window
git clone https://github.com/bbthorson/vox-pop-core.git
cd vox-pop-core
npm install

2. Start the Firebase emulators

Section titled “2. Start the Firebase emulators”

In one terminal:

Terminal window
npx firebase emulators:start --only auth,firestore,storage --project demo-vox-pop

The demo- project prefix tells the CLI not to require credentials — the emulators run entirely locally.

3. Start core-api in emulator mode

Section titled “3. Start core-api in emulator mode”

In a second terminal:

Terminal window
VOXPOP_USE_EMULATOR=true npm run dev -w @vox-pop/core-api

The service listens on http://localhost:8080. Smoke test:

Terminal window
curl http://localhost:8080/health
# → {"ok":true}


curl http://localhost:8080/
# → {"service":"vox-pop-core-api", ...}

4. Hit a real endpoint

Section titled “4. Hit a real endpoint”

Most /api/v1/* endpoints require an authenticated bearer token. For local exploration, mint an emulator ID token via the Firebase Auth emulator UI (http://localhost:9099), then:

Terminal window
curl http://localhost:8080/api/v1/users/me \
  -H "Authorization: Bearer $ID_TOKEN"

Next steps

Section titled “Next steps”