Documentation Index
Fetch the complete documentation index at: https://grantmaster.dev/llms.txt
Use this file to discover all available pages before exploring further.
Environment & Local Setup
This guide details how to get GrantMaster running locally and how the various environments (Local, Staging, Production) are configured.
1. Prerequisites
- Node.js: v20 or later (enforced via
engines in package.json).
- Firebase CLI:
npm install -g firebase-tools.
- Java: Required for Firebase Emulators (JRE 11+).
- npm workspaces: The repo uses npm workspaces (
packages/*, functions).
2. Environment Variables
The application uses Vite’s environment handling. Create a .env.local file based on .env.example.
| Variable | Requirement | Purpose |
|---|
VITE_FIREBASE_API_KEY | Required | Web SDK browser key. |
VITE_GEMINI_API_KEY | Optional | Browser-side Gemini key used only as a legacy/local fallback for some AI flows. Missing it should not block app startup. |
VITE_SENTRY_DSN | Optional | Client-side error tracking. |
VITE_STRIPE_PUBLISHABLE_KEY | Optional | Client-side payment integration. |
VITE_USE_EMULATORS | Optional | Set to true to connect to local Firebase. |
VITE_TYPESENSE_HOST | Optional | Typesense Cloud host (required for direct client search mode). |
VITE_TYPESENSE_SEARCH_API_KEY | Optional | Typesense read-only key (required for direct client search mode). |
VITE_TYPESENSE_USE_CLOUD_FUNCTIONS | Optional | Set to true to route command palette search through callable searchTypesenseSecure. |
Note: Secret keys (like STRIPE_SECRET_KEY) are stored in Firebase Secret Manager and are only accessible to Cloud Functions.
3. Local Development
GrantMaster is designed to be developed entirely offline using the Firebase Local Emulator Suite.
Quick Start (Recommended)
# Start everything — emulators + seed data + Vite dev server
npm run dev:all
# Same but clears emulator data first
npm run dev:all:fresh
Alternative (Two Terminals)
# Terminal 1: Firebase emulators + seed data
npm run dev:start
# Terminal 2: Vite dev server
npm run dev
Other Dev Commands
| Command | Purpose |
|---|
npm run dev:fresh | Emulators with fresh data (clears existing) |
npm run dev:seed | Seed emulators only (no dev server) |
npm run emulators | Emulators with persistence (import/export) |
npm run emulators:no-persist | Emulators without persistence |
npm run seed:emulators | Run seeding script against emulators |
Ports
| Service | Port |
|---|
| Vite Dev Server | 3000 |
| Firebase Emulator UI | 4000 |
| Firestore Emulator | 8080 |
| Auth Emulator | 9099 |
| Storage Emulator | 9199 |
| Functions Emulator | 5001 |
Note: Never override the Vite port (3000) — it is hardcoded for Firebase integration.
4. Troubleshooting
- Port Conflicts: Ensure ports 3000, 4000, 5001, 8080, 9099, and 9199 are not in use by other processes.
- CORS Issues: When running locally, ensure your Vite dev server is running on the authorized domain configured in Firebase (usually
localhost:3000).
- Function Errors: Check
functions/firebase-debug.log for execution errors in background tasks.
- Emulator Health: Run
npm run health:emulators to check emulator status.
Maintenance
Update this document when:
- Adding a new emulator (e.g., Pub/Sub).
- Reconfiguring the standard developer ports.
- Adding mandatory environment variables.
