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.examplefor 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
- Hit
/auth, request a magic link, and sign in. - Jump to
/hudand add a source. Our demo pairing:- RSS:
https://hnrss.org/frontpage - X:
@openai(the normalization helpers live inweb/src/lib/utils/twitter.ts).
- RSS:
- Within seconds you’ll see cards land. That’s the blend in
web/src/app/api/feed/route.tspushing 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/rssand/api/cron/xwith theCRON_SECRETheader. - Bonus: run
npm install && npm run devinsideastro-book/to read this guide with the glassmorphic UI you’re looking at right now.