Operations
Root env files, Vercel env management, Supabase values, Stripe values, and Turbo task env forwarding.
Apps load environment variables from the repository root. Deployed services share one Vercel
project environment. Next.js apps call loadMonorepoEnv (via @workspace/next-config) so they read
the root files even though each app lives under apps/<name>.
| File | Purpose |
|---|---|
.env.example | Tracked template (no secrets) |
.env.local | From pnpm env:pull:development (gitignored) |
.env.development.local | Local overrides that survive pulls (Portless URLs, local Supabase, DEV_LOGIN_*) |
.env.production.local | From pnpm env:pull:production for local production builds |
supabase/.env.example → supabase/.env.local | Supabase CLI Google OAuth and CLI-only settings |
Copy .env.example to .env.local when you are not linked to Vercel yet, then fill required values.
Prefer pnpm env:pull (development + production) when the root project is linked.
For local Supabase, common values (in .env.development.local) are:
NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=<local-publishable-key>
# Optional; unset falls back to https://localhost → app.localhost / api.localhost
# NEXT_PUBLIC_SITE_URL=https://localhostLink the repository root to the CentraKit Vercel project and manage deployed values there (including marketplace integrations for Sentry, Supabase, Stripe, and Resend).
pnpm env:pull # development → .env.local + production → .env.production.local
pnpm env:pull:development
pnpm env:pull:production
pnpm env:pull:preview # → .env.preview.local (optional; Next does not auto-load it)Prefer shared integration names (NEXT_PUBLIC_SENTRY_DSN / SENTRY_*, Supabase, Stripe, Resend).
AI Gateway and Vercel Connect use VERCEL_OIDC_TOKEN from pnpm env:pull. Sentry SDK initialization
is disabled in local development.
Keep local-only overrides in .env.development.local so development pulls into .env.local do not
wipe Portless or local Supabase settings.
Turborepo only forwards variables listed in a task's env array or global env configuration. If a build needs a secret or public value, add it to that app's turbo.json task configuration, root globalEnv, or globalPassThroughEnv.
NEXT_PUBLIC_SITE_URL is in root globalEnv so CI and local next build hash it. Off Vercel, unset values fall back to https://localhost (SaaS https://app.localhost, API https://api.localhost). SENTRY_AUTH_TOKEN is in build passThroughEnv so the Sentry plugin can see it without affecting the cache hash.
Do not commit .env.local files or credentials. Document variable names and ownership, not real secret values.