Environment variables

This page describes environment and deployment-related configuration for the monorepo.

SolidStart app (site-solidstart) — on hold

The SolidStart package is on hold and is not the official web target. Environment documentation for that package is deferred until the port is revived.

Next.js app (site-nextjs) — official full stack

The production implementation in this monorepo today is primarily the Next.js app under site-nextjs/, with Convex, Better Auth, Square, and Radar. Most variables and file layout below are Next.js–specific (NEXT_*, App Router, Vercel).

Local development

For local development, we use .env and .env.local files.

Variable file overview

  • .env: Contains non-sensitive development defaults. Shared across some tools but overridden by .env.local in Next.js.

  • .env.local: Contains your personal API keys and secrets. This file is ignored by git.

  • .env.example: A template for the .env file.

  • .env.local.example: A template for the .env.local file.

Next.js encourages use of .env.local to store all personal secrets. While .env will work, it is less accurate for local overrides. Variables in .env.local override variables in .env, which is useful if you are testing a function locally and you don’t want to replace shared information in .env.

Because most software developers are unaware of the difference, they might drop sensitive information into .env instead of .env.local. To be safe, both are excluded from git via .gitignore. Other non-local versions (like .env.development) are also typically ignored to prevent hardcoded secrets in project history.

Sources:

CI/CD pipeline

If you are trying to deploy this code via CI/CD pipelines on GitHub, Vercel, or other deployment platforms, do not use .env files to store variables. Environment variables for staging or production environments should be managed by secret managers or injected directly into the deployment pipeline.

Setup

To get started, copy the template files in the site-nextjs directory:

cd site-nextjs
cp .env.example .env
cp .env.local.example .env.local

Variable reference

Variable Description Source

FOOD_TRUCK_API_URL

Base URL for the API (server-side calls)

Internal / Zuplo

NEXT_PUBLIC_API_URL

Base URL for API calls from the frontend

Internal / Vercel Domain

NEXT_PUBLIC_MAP_PROVIDER

The map provider to use for rendering tiles. Options: radar, openfreemap.

Internal (Default: openfreemap)

NEXT_PUBLIC_RADAR_PUBLISHABLE_KEY

Publishable key for Radar SDK (Maps/Location)

Radar Dashboard

CONVEX_DEPLOYMENT

Your Convex deployment ID (e.g., dev:joyful-otter-123)

Convex Dashboard

NEXT_PUBLIC_CONVEX_URL

Your Convex deployment URL

Convex Dashboard

CONVEX_DEPLOY_KEY

Required for Vercel to deploy Convex functions during build

Convex Dashboard

SQUARE_APPLICATION_ID

Square Application ID

Square Developer Portal

SQUARE_ACCESS_TOKEN

Square Access Token (Sandbox/Production)

Square Developer Portal

SQUARE_WEBHOOK_SIGNATURE_KEY

Square Webhook Signature Key

Square Developer Portal

NEXTAUTH_SECRET

Random string for NextAuth.js encryption

Generate with openssl rand -base64 32

ENCRYPTION_KEY

32-character key for data encryption (Local)

Any random 32-character string

TOKEN_ENCRYPTION_KEY

32-character key for sensitive token encryption (Vercel)

Any random 32-character string

BETTER_AUTH_SECRET

Secret for Better Auth session signing (use a long random string in production)

Generate with openssl rand -base64 32

BETTER_AUTH_URL

Public origin of the Next.js app as seen by the auth server (no trailing path)

e.g. http://localhost:3000 or your Vercel URL

NEXT_PUBLIC_APP_URL

Same origin as BETTER_AUTH_URL for the browser auth client; also used as Next.js metadataBase for canonical URLs, sitemap.xml, and Open Graph / Twitter image URLs

Must match deployment URL (include https:// in production)

FTN_DEVELOPER_EMAILS

Comma-separated list of sign-in emails granted the Convex platformRole of developer (FTN developer panel, /dev/* routes). Server-only; not exposed to the browser.

e.g. you@example.com,teammate@example.com

FTN_PR_EMAILS

Comma-separated list of sign-in emails granted platformRole of pr (approve/reject FTN-affiliated meetup host requests). If an email is also in FTN_DEVELOPER_EMAILS, developer wins.

e.g. pr@foodtrucknerdz.com

FTN_PR_NOTIFY_EMAIL

Inbox that receives “new host request” notifications. Defaults to support@foodtrucknerdz.com if unset.

e.g. pr@foodtrucknerdz.com

RESEND_API_KEY / FTN_TRANSACTIONAL_FROM

Optional. When set, host-request and approval emails send via Resend. Without the key, emails are logged server-side only. Transactional / app only — use sending host updates.foodtrucknerdz.com (e.g. support@updates.foodtrucknerdz.com) after domain verification. Marketing / journeys use Customer.io. Human Gmail send-as uses ZeptoMail (ops), not Resend. See Messaging & marketing.

Resend dashboard; DNS in org infra

Customer.io / Twilio (planned)

Not wired in app code yet. Customer.io is the planned marketing + multi-channel orchestration platform (US data center; Email, SMS, Push, In-app). Twilio is the planned SMS transport. Add site/API and Twilio secrets here when provisioned; never ship write keys to browsers. See Messaging & marketing (Customer.io).

Customer.io / Twilio

YOTI_CLIENT_SDK_ID / YOTI_PEM_PRIVATE_KEY

Optional. Yoti Age Verification credentials for affiliated host age + liveness checks. Leave unset in local/dev to use the stub verification path documented in Community events.

Yoti Age Verification docs

ADAPTY_PUBLIC_SDK_KEY

Adapty public SDK key for mobile (ftn-app via --dart-define=ADAPTY_PUBLIC_SDK_KEY=…). Not a substitute for Better Auth. Create the app and access level premium in the Adapty dashboard. See Subscription management (Adapty).

Adapty Dashboard

GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET

Google OAuth credentials for Better Auth social sign-in

Google Cloud Console

FACEBOOK_CLIENT_ID / FACEBOOK_CLIENT_SECRET

Meta (Facebook) OAuth credentials for Better Auth social sign-in. In the Meta app, add a Valid OAuth Redirect URI that matches your deployment: the app origin (same as BETTER_AUTH_URL) plus path /api/auth/callback/facebook.

Meta for Developers

FACEBOOK_CONFIG_ID

Optional. Facebook Login for Business configuration ID (User access token type). Omit for standard Facebook Login.

Meta Developer Portal → Facebook Login for Business → Configurations

Vercel deployment

For production deployments on Vercel, variables are managed in the Vercel Dashboard under Settings > Environment Variables.

Important notes

  1. CONVEX_DEPLOY_KEY is REQUIRED for Vercel deployments. Without it, Convex functions won’t deploy during build.

  2. NEXT_PUBLIC_CONVEX_URL is typically set automatically by Convex when using pnpm convex deploy --cmd in the build command. Only set manually if you need to override the default.

  3. Square variables are only needed if you’re using Square POS integration. Get credentials from the Square Developer Portal.

  4. Radar variables are only needed if you’re using location services or the Radar map provider.

  5. Map providers: We use a hybrid approach. Radar SDK is used for geocoding and search (due to its generous free tier), while OpenFreeMap is the default for map tile visualization to ensure privacy and cost-effectiveness.

  6. TOKEN_ENCRYPTION_KEY should be a strong random string (at least 32 characters). Use it to encrypt sensitive data like Square access tokens.

  7. NEXT_PUBLIC_* variables are exposed to the browser. Never put secrets in these variables.

  8. Do not pull environment variables via Vercel CLI. If prompted by vercel --prod to download variables, select NO. This prevents Vercel from overwriting your local setup or creating redundant .env files.

  9. Social login: Set BETTER_AUTH_URL and NEXT_PUBLIC_APP_URL to the production site origin. For Facebook, register the matching /api/auth/callback/facebook redirect URI in the Meta app.

  10. Square: Use one Square application for both POS linking and seller sign-in. Register two redirect URIs in the Square app: the POS link URL (SQUARE_REDIRECT_URI, path /api/auth/callback/square) and the Better Auth URL with path /api/auth/oauth2/callback/square on the same origin as BETTER_AUTH_URL.

For more details, see the Deployment guide in the Next.js section.