Environment Variables

next-forge uses environment variables for configuration. This guide will help you set up the required variables to get started quickly, and optionally configure additional features.

Quick Start (Minimum Setup)

To get next-forge running locally with basic functionality, you only need to configure these required variables:

1. Database (Required)

Add to packages/database/.env:

DATABASE_URL="postgresql://user:password@localhost:5432/mydb"

2. Authentication (Required)

Add to apps/app/.env.local and apps/web/.env.local:

# Server
CLERK_SECRET_KEY="sk_test_..."

# Client
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_test_..."
NEXT_PUBLIC_CLERK_SIGN_IN_URL="/sign-in"
NEXT_PUBLIC_CLERK_SIGN_UP_URL="/sign-up"
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL="/"
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL="/"

3. Local URLs (Pre-configured)

These are already set to sensible defaults for local development:

NEXT_PUBLIC_APP_URL="http://localhost:3000"
NEXT_PUBLIC_WEB_URL="http://localhost:3001"
NEXT_PUBLIC_API_URL="http://localhost:3002"
NEXT_PUBLIC_DOCS_URL="http://localhost:3004"
VERCEL_PROJECT_PRODUCTION_URL="http://localhost:3000"

That's it! You can now run npm run dev and the app will work with basic authentication and database functionality.

Optional Features

The following environment variables enable additional features. You can add them as needed:

Content Management (BaseHub)

Required for the CMS functionality in packages/cms.

BASEHUB_TOKEN="bshb_..."

Email (Resend)

Required for sending transactional emails.

RESEND_TOKEN="re_..."
RESEND_FROM="noreply@yourdomain.com"

Get your API key from Resend

Payments (Stripe)

Required for subscription and payment functionality.

STRIPE_SECRET_KEY="sk_test_..."
STRIPE_WEBHOOK_SECRET="whsec_..."

stripe listen --forward-to localhost:3000/api/webhooks/stripe

Analytics

Google Analytics

NEXT_PUBLIC_GA_MEASUREMENT_ID="G-..."

Create a GA4 property

PostHog

NEXT_PUBLIC_POSTHOG_KEY="phc_..."
NEXT_PUBLIC_POSTHOG_HOST="https://app.posthog.com"

Get your keys from PostHog

Observability

Better Stack (Uptime monitoring)

BETTERSTACK_API_KEY="..."
BETTERSTACK_URL="..."

Get your API key from Better Stack

Security

Arcjet (Rate limiting & security)

ARCJET_KEY="ajkey_..."

Get your key from Arcjet

Real-time Features

Liveblocks (Collaboration)

LIVEBLOCKS_SECRET="sk_..."

Get your secret from Liveblocks

Notifications (Knock)

KNOCK_API_KEY="..."
KNOCK_SECRET_API_KEY="..."
KNOCK_FEED_CHANNEL_ID="..."
NEXT_PUBLIC_KNOCK_API_KEY="..."
NEXT_PUBLIC_KNOCK_FEED_CHANNEL_ID="..."

Get your keys from Knock

Feature Flags

FLAGS_SECRET="..."

Generate a random secret string for encrypting feature flag data.

Webhooks (Svix)

SVIX_TOKEN="..."

Get your token from Svix

Clerk Webhooks

CLERK_WEBHOOK_SECRET="whsec_..."

Environment Variable Files

next-forge uses environment variables across multiple locations:

Type Safety

Type safety is provided by @t3-oss/env-nextjs, which provides runtime validation and autocompletion for all environment variables. Each package defines its own environment variables in a keys.ts file with Zod validation schemas.

Validation Rules

Adding a New Environment Variable

To add a new environment variable:

1. Add the variable to the relevant .env.local files
2. Add validation to the server or client object in the package's keys.ts file

Example in packages/my-package/keys.ts:

import { createEnv } from "@t3-oss/env-nextjs";
import { z } from "zod";

export const keys = createEnv({
  server: {
    MY_NEW_SECRET: z.string().min(1),
  },
  client: {
    NEXT_PUBLIC_MY_VALUE: z.string().optional(),
  },
  runtimeEnv: {
    MY_NEW_SECRET: process.env.MY_NEW_SECRET,
    NEXT_PUBLIC_MY_VALUE: process.env.NEXT_PUBLIC_MY_VALUE,
  },
});

Deployment

When deploying to Vercel or other platforms:

1. Add all required environment variables to your deployment platform
2. Update URL variables (NEXT_PUBLIC_APP_URL, etc.) to production values
3. Some integrations (like Sentry) automatically inject their variables via marketplace integrations