SaaS Box

Environment Variables

SaaS Box enforces strict, type-safe environment variable validation using Zod. If you attempt to start the server or build the application without a required variable, the process will immediately fail and explicitly tell you which key is missing.

Core Application

Fundamental variables required for basic routing, absolute URLs, and application state.

VariableConfiguration & Retrieval
NEXT_PUBLIC_APP_URL

The public-facing URL used by client components to construct absolute paths, canonical SEO tags, and email links.

Development: http://localhost:3000
Production: https://yourdomain.com
NEXT_PUBLIC_DEMO_MODE

A boolean flag used within the admin dashboard to populate mock data for demonstration purposes. If you are building a real production application, you can safely delete this variable and entirely remove its associated mock logic from the codebase.

Value: true | false

Database Configuration

Internal Guide →Neon Docs ↗

Connection strings required by Drizzle ORM to interface with your Neon Tech serverless PostgreSQL instance.

VariableConfiguration & Retrieval
DATABASE_URL

The secure connection string used by both the Next.js runtime and the Drizzle CLI.

  1. Log in to your Neon Tech dashboard.
  2. Select your project and navigate to the Dashboard .
  3. Under the Connection Details section, ensure the role is set correctly.
  4. Copy the pooled connection string provided.

Authentication Engine

Internal Guide →Better Auth Docs ↗

Cryptographic secrets and OAuth credentials utilized by Better-Auth to issue secure, signed session tokens.

VariableConfiguration & Retrieval
BETTER_AUTH_SECRET

A high-entropy cryptographic secret. Do not expose this to the client. You can generate this securely using the official Better-Auth CLI tool.

npx @better-auth/cli secret
BETTER_AUTH_URL

The root URL of your application where the authentication API routes reside.

Usually identical to NEXT_PUBLIC_APP_URL, but strictly enforced on the server to prevent callback hijacking.

GITHUB_CLIENT_ID
GITHUB_CLIENT_SECRET

Required to enable GitHub OAuth login.

  1. Go to GitHub Developer Settings > OAuth Apps.
  2. Click New OAuth App .
  3. Set Homepage URL to your BETTER_AUTH_URL.
  4. Set Authorization callback URL to /api/auth/callback/github.
GOOGLE_CLIENT_ID
GOOGLE_CLIENT_SECRET

Required to enable Google OAuth login.

  1. Go to Google Cloud Console and select your project.
  2. Navigate to APIs & Services > Credentials.
  3. Create an OAuth client ID (Web application).
  4. Add Authorized redirect URI: /api/auth/callback/google.

Billing & Subscriptions

Internal Guide →Polar Docs ↗

Keys required to interact with the Polar.sh API for managing user subscriptions, processing payments, and verifying secure webhooks.

VariableConfiguration & Retrieval
POLAR_ACCESS_TOKEN

The primary access token utilized by the backend to fetch subscription tiers and modify customer states.

  1. Log in to your Polar.sh dashboard.
  2. Navigate to Settings > Developers .
  3. Generate a new Personal Access Token with the required scopes.
POLAR_WEBHOOK_SECRET

A cryptographic signature used to verify that incoming webhook payloads genuinely originate from Polar.sh.

  1. In Polar.sh, go to Settings > Webhooks .
  2. Create an endpoint pointing to /api/webhook/polar.
  3. Reveal and copy the generated Webhook Secret.
NEXT_PUBLIC_POLAR_PRO_PRODUCT_ID

The unique identifier for your primary paid subscription tier. Exposed to the client to dynamically generate checkout links.

  1. In Polar.sh, navigate to the Products tab.
  2. Select your configured Pro tier.
  3. Copy the Product ID from the URL or the product settings page.

Cloudflare R2 Storage

Internal Guide →Cloudflare Docs ↗

S3-compatible API credentials for securely uploading user avatars and storing general application assets without massive egress fees.

VariableConfiguration & Retrieval
R2_ACCOUNT_ID

Your root Cloudflare Account ID.

  1. Log in to the Cloudflare Dashboard.
  2. Select your active domain or account.
  3. Scroll down to the bottom right of the overview page to find your Account ID .
R2_ACCESS_KEY_ID
R2_SECRET_ACCESS_KEY

S3 API credentials generated specifically for your storage bucket.

  1. Navigate to R2 in the Cloudflare sidebar.
  2. Click Manage R2 API Tokens .
  3. Create a new token with Object Read & Write permissions.
  4. Copy both keys immediately as the secret will not be shown again.
R2_BUCKET_NAME

The literal string name of the bucket you created (e.g., saas-box-production).

NEXT_PUBLIC_R2_DEV_URL

The public URL where your assets are served. Cloudflare provides a default .r2.dev URL, or you can map a custom domain.

https://pub-xxxxxxxxxxxxx.r2.dev

Email Delivery

Internal Guide →Resend Docs ↗

Configuration for dispatching transactional emails such as password resets via Resend.

VariableConfiguration & Retrieval
RESEND_API_KEY

The master key used to authenticate requests to the Resend API.

  1. Log in to Resend.com.
  2. Navigate to the API Keys section.
  3. Generate a new key with full permissions for sending.
EMAIL_FROM

The exact email address that will act as the sender for your transactional emails.

If you have not verified a custom domain yet, you must use Resend's default testing email. Once verified, replace it with your production email address.

Testing: onboarding@resend.dev
Production: support@yourdomain.com
← Previous StepQuick StartNext Section →Authentication