Quickstart

Clone and install

git clone git@github.com:sachio222/atlas.git && cd atlas
pnpm install

pnpm only. The lockfile and patchedDependencies are pnpm’s — switching to npm or yarn causes lockfile drift.

Start the dev server

pnpm web

Starts the Metro dev server for web at http://localhost:8081. For iOS/Android/web via Expo Go or a simulator, use:

pnpm exec expo start

Watch something

That’s it. Anonymous watch works with zero environment variables configured, and the codebase is written to keep it that way. Sign-in, sync, and the nightly recommendation jobs each turn on independently when their keys exist.

Environment variables

Copy .env.example to .env.local. Every variable is optional — none is required for anonymous watch.

Never put a secret in an EXPO_PUBLIC_* variable. Those ship in the client bundle, readable by anyone who loads the page.

Client (`EXPO_PUBLIC_*`, safe to ship in the bundle)

Variable	Turns on	Notes
`EXPO_PUBLIC_ATLAS_RELAY_URL`	Playback of CORS-blocked streams (Pluto, NASA+) on web	Already set in production. See Architecture.
`EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY`	Sign-in	Must be a `pk_` key; sign-in stays off until it is.
`EXPO_PUBLIC_SUPABASE_URL`	Sync, recommendations (read side)	GitHub-linked Bytestream Supabase org.
`EXPO_PUBLIC_SUPABASE_PUBLISHABLE_KEY`	Sync, recommendations (read side)
`EXPO_PUBLIC_SUPABASE_ANON_KEY`	Sync, recommendations (read side)
`BYTESTREAM_API`	Catalog MCP client lookups	`GET /api/catalog`; never returns stream URLs.

Server-side jobs only (`scripts/.ts`, GitHub Actions — never `EXPO_PUBLIC_`)

Variable	Used by	Notes
`SUPABASE_URL`	Catalog sync, nightly recommendation jobs	Repo secret in CI; falls back to `supabase projects api-keys` locally when linked.
`SUPABASE_SERVICE_ROLE_KEY`	Catalog sync, nightly recommendation jobs	Never exposed to the client.
`BYTESTREAM_SUPABASE_REF`	Catalog sync, nightly recommendation jobs	The linked Supabase project ref (`fxjsfuuhargxxdjaskbz`).
`TYPESAFE_API_KEY`	Nightly recommendation build (`recs:users`)	Explicitly optional. Without it, the recommendation jobs degrade to vectors-only scoring rather than failing. See Recommendations.

After the Vercel Marketplace provisions Clerk and Supabase, vercel env pull --yes writes the real client values into .env.local for you.

Testing

pnpm test

Runs jest-expo with @testing-library/react-native available for component tests.

Building for web

pnpm run build:web

Exports a static web build to dist/.

End-to-end smoke test

pnpm e2e

Builds the web export, serves dist/ on localhost:4173 via serve, and runs a Playwright test that loads the app, waits for a live channel’s video to actually be playing, and asserts the crimson LIVE pill is visible.

Get started

How it works

Contribute

Environment variables

Client (`EXPO_PUBLIC_*`, safe to ship in the bundle)

Server-side jobs only (`scripts/.ts`, GitHub Actions — never `EXPO_PUBLIC_`)

Testing

Building for web

End-to-end smoke test

​Environment variables

​Client (EXPO_PUBLIC_*, safe to ship in the bundle)

​Server-side jobs only (scripts/*.ts, GitHub Actions — never EXPO_PUBLIC_*)

​Testing

​Building for web

​End-to-end smoke test

Environment variables

Client (`EXPO_PUBLIC_*`, safe to ship in the bundle)

Server-side jobs only (`scripts/.ts`, GitHub Actions — never `EXPO_PUBLIC_`)

Testing

Building for web

End-to-end smoke test