Web and mobile environment variables

Web app (`frontend`)

The web app has no validated env schema. Variables are read where they are used. The scripts in the root package.json wrap Turborepo with dotenv -c, which loads .env and then .env.local from the repository root. There is no .env.example in the repository at the time of writing.

Required

Variable	Read in	Purpose
`CORE_API_URL`	`apps/saas/modules/shared/lib/core-api.ts`, `bff-proxy.ts`	Base URL of the core API, with no path. The `/api` proxy throws `CORE_API_URL is not configured` without it.
`SERVICE_AUTH_SECRET`	`core-api.ts`	HMAC secret that signs `/v1/web` requests. Must equal the backend value.
`NEXT_PUBLIC_SAAS_URL`	`@repo/utils`, auth client	Public URL of the web app. Baked into the client bundle at build time.

Optional

Variable	Default	Purpose
`CORE_API_SERVICE_ID`	`web`	Service id sent as `x-service-id`. The backend only registers `web`.
`NEXT_PUBLIC_SITE_URL`	none	Public site URL. Declared in `turbo.json` `globalEnv` and passed at build time.
`NEXT_PUBLIC_MEDIA_CDN_URL`	a CDN host set in code	Base URL for media links built by `modules/shared/lib/media-url.ts`.
`NEXT_PUBLIC_TRAINEE_PREVIEW_URL`	`/trainee-preview`	Where the embedded trainee app preview is loaded from.
`NEXT_PUBLIC_DOCS_URL`	none	Link target for documentation, read in `apps/saas/config.ts`.
`NEXT_PUBLIC_MARKETING_URL`	none	Link target for the marketing site, read in `apps/saas/config.ts`.
`NEXT_PUBLIC_LANGUAGE_SWITCH_EMAILS`	a placeholder address	Accounts allowed to see the language switch, read in `apps/saas/config.ts`.
`MARKETING_URL`	`http://localhost:3001`	Origin of the marketing dev server. Used only in development by `proxy.ts` and the rewrites in `next.config.ts`.
`AUTH_TRUSTED_ORIGINS`	empty	Comma-separated extra origins. `next.config.ts` turns them into `allowedDevOrigins` so you can open the dev server from a LAN address.
`DEPLOYMENT_VERSION`	none	Passed to `deploymentId` in `next.config.ts`. The manual deploy workflow sets it to the commit SHA so stale clients are detected after a release.
`NEXT_SERVER_ACTIONS_ENCRYPTION_KEY`	none	Set by the manual deploy workflow, derived from the auth secret, so Server Action ids stay stable across builds.
`NEXT_TELEMETRY_DISABLED`	none	Set to `1` to turn off Next.js telemetry.
`PORT`	`3000` in dev, `3043` in production	Port the Next.js server listens on.
`PRICE_ID_*`	none	The same plan ids the backend uses. `@repo/payments` reads them to map a purchase to a plan in the UI.
`NEXT_PUBLIC_VERCEL_URL`, `VERCEL`	none	Read by `@repo/utils` base URL helpers. Leftover from the starter kit. The app is not deployed on Vercel.

Build-time only

The Dockerfile and the CI workflows also set DATABASE_URL and BETTER_AUTH_SECRET to placeholder values during the build. The web app no longer opens a database connection or runs better-auth in process, so these are not needed at runtime. A local .env may still contain a DATABASE_URL from before the consolidation. It can be removed.

The boundary check

pnpm check:core-api runs tools/check-no-direct-core-api.sh. It fails when:

any file other than apps/saas/modules/shared/lib/core-api.ts mentions CORE_API_URL or SERVICE_AUTH_SECRET,
a variable named NEXT_PUBLIC_CORE_API... exists,
a "use client" file imports core-api or calls coreApiFetch,
core-api.ts is missing or does not import server-only.

At the time of writing, several other files also read CORE_API_URL: bff-proxy.ts, bff-server-fetch.ts, modules/admin/lib/admin-api.ts, and the route handlers under app/api/onboarding and app/api/waitlist. The script allows only core-api.ts, so it reports these files. CI runs the script as its first step. Either the allow list or those files need to change before the check passes.

Mobile app (`mobile`)

The mobile app reads only EXPO_PUBLIC_* variables at runtime. Expo inlines them into the JavaScript bundle at build time, so they are public. Never put a secret in one. mobile/.env.example is in the repository. .env and .env.production are ignored by Git.

Variable	Required	Purpose
`EXPO_PUBLIC_API_URL`	no	Base URL of the core API, with no `/api` or `/v1` suffix. When unset in development, the app derives `http://HOST:3031` from the Metro host. When unset in a release build, it uses the production API URL hardcoded in `src/lib/api/config.ts`.
`EXPO_PUBLIC_FB_APP_ID`	no	Facebook app id used to attribute workout shares to Instagram Stories. Without it the share still works but is not attributed.
`APP_ENV`	no	`preview` or `production`. Set by the EAS build profiles.

Where the values come from in each context

Context	Source
`pnpm start` on a simulator or device	`mobile/.env`, or automatic host detection
EAS build with the `preview` or `production` profile	`build.<profile>.env` in `eas.json`
Local production build	`mobile/.env.production`. Keep it in sync with `eas.json`.
OTA update	EAS environment variables. `scripts/sync-eas-ota-env.js` copies `APP_ENV` and every `EXPO_PUBLIC_*` key from `eas.json` into the matching EAS environment before each publish.

Variables used only by scripts

Variable	Used by	Purpose
`PREVIEW_BASE_PATH`	`app.config.js`, `scripts/export-preview.sh`	Base path of the web export. Defaults to `/trainee-preview`.
`PREVIEW_API_URL`	`app.config.js`, `scripts/export-preview.sh`	API URL baked into the web export through `extra.apiUrl`.
`PREVIEW_TARGET_DIR`	`scripts/export-preview.sh`	Output folder. Defaults to `../frontend/apps/saas/public/trainee-preview`.
`API_PORT`, `IFACE`	`scripts/use-lan-ip.sh`	Port and network interface used to write a LAN URL into `.env`.

Values that must match across repositories

Value	Backend	Web app	Mobile app
HMAC secret	`SERVICE_AUTH_SECRET`	`SERVICE_AUTH_SECRET`	not used
Service id	key `web` in `serviceSecrets`	`CORE_API_SERVICE_ID`	not used
API URL	`PUBLIC_API_URL`	`CORE_API_URL`	`EXPO_PUBLIC_API_URL`
Web URL	`NEXT_PUBLIC_SAAS_URL`, `APP_WEB_URL`, `CORS_ORIGIN`	`NEXT_PUBLIC_SAAS_URL`	not used
Plan ids	`PRICE_ID_*`	`PRICE_ID_*`	not used

Overview

Getting set up

Conventions

Backend architecture

Building backend modules

Backend security and access

Background work and delivery

Backend platform features

Backend operations

Backend packages

Data model

JSON shapes

Web app: basics

Web app: data and API

Web app: auth, organizations and billing

Web app: UI foundations

Web app: feature areas

Web app: quality and delivery

Trainee app: foundations

Trainee app: UI

Trainee app: workouts

Trainee app: nutrition

Trainee app: forms, content and tracking

Trainee app: device features

Trainee app: native, build and release

Messaging integrations

Platform integrations

External API and automation

Operations

Web and mobile environment variables

Web app (`frontend`)

Required

Optional

Build-time only

The boundary check

Mobile app (`mobile`)

Where the values come from in each context

Variables used only by scripts

Values that must match across repositories

​Web app (frontend)

​Required

​Optional

​Build-time only

​The boundary check

​Mobile app (mobile)

​Where the values come from in each context

​Variables used only by scripts

​Values that must match across repositories

Web app (`frontend`)

Required

Optional

Build-time only

The boundary check

Mobile app (`mobile`)

Where the values come from in each context

Variables used only by scripts

Values that must match across repositories