Quickstart (Tutorial)

We treat this quickstart like a live control-room rehearsal: wire the environment, light up the feed, run a smoke test, and breathe easy.

Pre-flight checklist

  • macOS, Linux, or WSL2 with a trusty shell
  • Node.js ≥ 20 (we ship on v22.17.1)
  • npm ≥ 10 (v10.9.2 in our pod)
  • Supabase CLI (optional but delightful for migrations + Edge deploys)

Step 0 — Clone the newsroom

git clone <your-repo-url> news-hud && cd news-hud

Step 1 — Hand the HUD its credentials

Drop these lines into web/.env.local. They’re copied verbatim from the main project README so both docs and app stay in sync.

NEXT_PUBLIC_SUPABASE_URL=               your_supabase_database_url
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=   your_supabase_publishable_key
NEXT_PUBLIC_SUPABASE_ANON_KEY=          your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=              your_supabase_service_role_key
SUPABASE_PROJECT_REF=                   your_supabase_project_reference

NEXT_PUBLIC_DEFAULT_RSS=                a_link_to_rss
NEXT_PUBLIC_DEFAULT_TWITTER_HANDLE=     @your_profile_name

NEXT_PUBLIC_X_BEARER_TOKEN=             your_x_api_bearer_token
CRON_SECRET=                            optional_shared_secret_for_cron

GEMINI_API_KEY=                         optional_default_key (leave blank for user-supplied)

Tip Keep a scrubbed .env.example for teammates, but never commit real secrets. Rotating Supabase service keys isn’t hard, hunting down leaks is.

Step 2 — Install and ignite Turbopack

cd web
npm install
npm run dev
# Visit http://localhost:3000 once Turbopack says “ready”

Optional: install the Supabase CLI so you can run migrations or redeploy Edge workers without leaving the terminal.

brew install supabase/tap/supabase
supabase --version

Step 3 — First signal check

  1. Hit /auth, request a magic link, and sign in.
  2. Jump to /hud and add a source. Our demo pairing:
    • RSS: https://hnrss.org/frontpage
    • X: @openai (the normalization helpers live in web/src/lib/utils/twitter.ts).
  3. Within seconds you’ll see cards land. That’s the blend in web/src/app/api/feed/route.ts pushing 70% focus-weighted items and 30% popularity spikes.

Smoke tests we actually run

# Healthcheck — app root responds with 200
curl -sS -o /dev/null -w "%{http_code}\n" http://localhost:3000/

# API audit — make sure handlers exist and are typed
rg "export async function (GET|POST|DELETE)" web/src/app/api -n || grep -R "export async function" web/src/app/api

# Feed endpoint (needs an authenticated cookie)
open http://localhost:3000/api/feed

# Cron endpoints (no secret in dev)
curl -sS http://localhost:3000/api/cron/rss | jq . 2>/dev/null || true
curl -sS http://localhost:3000/api/cron/x | jq . 2>/dev/null || true

Expect the cron routes to warn about missing Supabase credentials. That’s our guardrail until the production keys land.

Flow: request → response

flowchart LR
Dev-->Build-->Run-->Healthcheck-->OK

Next moves

  • Bring your Supabase project online (supabase login && supabase projects list).
  • Deploy the ingestion duo: supabase functions deploy rss-fetch twitter-fetch.
  • On Vercel, schedule /api/cron/rss and /api/cron/x with the CRON_SECRET header.
  • Bonus: run npm install && npm run dev inside astro-book/ to read this guide with the glassmorphic UI you’re looking at right now.