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

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.