← setup-guides

Local Dev Setup (new contributors)

Get the app running locally without any production secrets. You use your own free Supabase project as a sandbox; we never pass the real .env around (it holds live service-role + API keys — sharing those in chat is a leak). See SECRETS_HANDLING.md for what's secret vs public and why.

1. Clone + install

git clone --recurse-submodules <repo-url>
cd hivejournal-2026
npm install        # installs both apps (workspaces)

2. Your own Supabase project

  1. Create a free project at supabase.com.
  2. Grab your keys from Project Settings → API: the project URL, the anon key (public), the service_role key (secret), and the JWT secret.

Never use the production project (pfyocleyejmtxmbxrdcm…) for local dev. Your own project is your sandbox — break it freely.

2a. Apply the schema — use the CLI, don't hand-run the files

There are 300+ migration files in supabase/migrations/. Don't paste them into the SQL Editor one by one — it's slow and a few older ones can fail out of order on a fresh DB. Let the Supabase CLI apply them all, in order:

brew install supabase/tap/supabase          # or: npm i -g supabase
supabase login
supabase link --project-ref <your-project-ref>   # YOUR sandbox, never prod
supabase db push                              # applies supabase/migrations/ in order

(<your-project-ref> is the slug in your project URL: https://<ref>.supabase.co.)

Do you need the full schema? Those 300+ migrations build every feature on the platform; a given task usually touches a handful of tables.

  • Public / unauthenticated page, or a pure component? You can often skip the database — the app boots and you build the UI against empty or mocked data. Frontend acceptance is npm run check + npm run build + the visual result.
  • Authenticated page (anything under /dashboard)? You still need the schema stood up to log in — signup writes a profiles row via a trigger defined in the migrations. Run supabase db push once; logging in then works. You can still mock the page's own data in the component to render states that are hard to create by hand (e.g. every status badge) — revert the mock before committing.
  • Either way, ask in your issue which tables/data your task actually needs.

3. Environment files

Each app has a documented template. Copy and fill in:

cp apps/backend/.env.example   apps/backend/.env
cp apps/frontend/.env.example  apps/frontend/.env.local
  • Backend (apps/backend/.env.example) — the ~6 vars under "MINIMAL TO BOOT" (Supabase URL/keys + the localhost URLs) are all you need to start. Everything else gates a specific integration (OpenAI, Stripe, Resend, …) and can stay blank until you work on it. Set DISABLE_CRONS=true so background jobs stay quiet while you develop.
  • Frontend (apps/frontend/.env.example) — 4 vars to boot (your Supabase URL + anon key, the API URL, the site URL). NEXT_PUBLIC_* values are baked into the browser bundle, so they're public by definition — never hide a secret behind that prefix.

Feature-specific third-party keys (OpenAI, ElevenLabs, Stripe, etc.) are handed out per-feature as you need them — ask in the contributor channel. Most tasks don't need them.

4. Run

# terminal 1 — backend API (http://localhost:3001)
cd apps/backend && npm run dev

# terminal 2 — frontend (http://localhost:3000)
cd apps/frontend && npm run dev

5. Before opening a PR

cd apps/frontend && npm run check     # lint + typecheck (Vercel-blocking rules)

Backend-only changes: cd apps/backend && npx tsc --noEmit. If you touched a page that uses useSearchParams or a dynamic [param] route, also run cd apps/frontend && npm run build (those failures only show in a real build).

See docs/README.md for the rest of the docs and CONTRIBUTING / contributor issues for picking up a task.

LOCAL DEV SETUP — Docs | HiveJournal