Improve environment variable setup

[empz]

Is your feature request related to a problem? Please describe.
The whole environment variable setup is kind of complex. I've been hunting down multiple instances of environment variables across the apps and packages, running the dev command after I set a new one and there's always a missing required one.

Describe the solution you'd like
I haven't looked at the monorepo deeply but maybe we could set the required variables for things like database, auth just to run the web app which is what we want to start with. We don't need to set up things like PostHog from the beginning.

Describe alternatives you've considered
If an optional environment variable is not, maybe the associated package could just return a no-op implementation that just logs function calls.

[liljamesjohn]

There is a specific documentation page for environment variables explaining how they are implemented.

It also explains that improvements/ recommendations for how to implement them better are wanted.

https://www.next-forge.com/docs/setup/env

[Zenahr]

@iamjamesjohn I think what @empz is asking for is a clarified "Quick Start" guide just to get the project compiled successfully locally.

Reading the "Installation" guide and trying to follow the steps as they are documented lead to errors. Nowhere does it say "You need to set up a postgress server manually", you'd assume a modern codebase manages these type of things on its own unless explicitly said otherwise.

[AndrewVoirol]

This will be my third time attempting to get a clean start at this, and the .env are my biggest itch to date. From the best glance there are at least 3-4 places env need to be setup (locally) api/app/web/root and perhaps more if I dove deeper. Not to mention then when deploying (to Vercel) I'm getting conflicting information as to if I should setup a shared set of env across deployments (app/api/web) or if I should setup the env on Vercel separately for each deployment.

I do see the call out for requests on ways this can be done better. I have my thoughts on that, but first I'd like to see this running, and running locally, and deployed successfully, and not have copy and past fatigue already just from .env variables.

Do I make one big env.example or env.local , etc, and just use that for all of them, and then also use that to import into Verce, is that the way?

Just feedback, and echo'ing the challenges of getting it setup and reducing local friction do get a quick set of wins as The Forge starts forging. Which (for now I accomplished by making fake keys for the things I don't need right now), not the best but ... it gets me by.

This is (WIP) cheat sheet I'm using with my Cursor/Cline agent assistant, just sharing in case it is of use to anyone:

---

Environment Variables Setup Checklist

Overview

This checklist covers all required environment variables for the Next.js Forge monorepo. Each app (app, web, api) needs its own .env.local file with the appropriate variables.

🚨 CRITICAL: Vercel Deployment Issues

Current Problem

The apps/app deployment is failing on Vercel due to missing Clerk environment variables. The build error shows:

❌ Invalid environment variables: [
  {
    code: 'invalid_type',
    expected: 'string',
    received: 'undefined',
    path: [ 'NEXT_PUBLIC_CLERK_SIGN_UP_URL' ],
    message: 'Required'
  },
  {
    code: 'invalid_type',
    expected: 'string',
    received: 'undefined',
    path: [ 'NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL' ],
    message: 'Required'
  },
  {
    code: 'invalid_type',
    expected: 'string',
    received: 'undefined',
    path: [ 'NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL' ],
    message: 'Required'
  }
]

Required Fix

Add these environment variables to your Vercel project settings:

1. Go to Vercel Dashboard → Your Project → Settings → Environment Variables
2. Add the missing variables:
   • NEXT_PUBLIC_CLERK_SIGN_UP_URL = /sign-up
   • NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL = /
   • NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL = /

Required Environment Variables

🔐 Authentication (Clerk)

Required for all apps

# Server-side (required)
CLERK_SECRET_KEY="sk_test_..."                    # Required - Get from Clerk Dashboard
CLERK_WEBHOOK_SECRET="whsec_..."                  # Optional - For webhooks

# Client-side (required)
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_test_..."   # Required - Get from Clerk Dashboard
NEXT_PUBLIC_CLERK_SIGN_IN_URL="/sign-in"          # Required - URL path
NEXT_PUBLIC_CLERK_SIGN_UP_URL="/sign-up"          # Required - URL path
NEXT_PUBLIC_CLERK_FALLBACK_REDIRECT_URL="/"       # Required - Redirect after sign-in/sign-up
NEXT_PUBLIC_CLERK_FORCE_REDIRECT_URL="/"          # Optional - Force redirect URL
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL="/"           # Required - Redirect after sign-in
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL="/"           # Required - Redirect after sign-up

🗄️ Database (Drizzle + Neon)

Required for all apps

DATABASE_URL="postgresql://..."                    # Required - Neon database connection string

📊 Analytics (PostHog)

Required for all apps

# Client-side (required)
NEXT_PUBLIC_POSTHOG_KEY="phc_..."                 # Required - Get from PostHog Dashboard
NEXT_PUBLIC_POSTHOG_HOST="https://app.posthog.dev" # Required - PostHog instance URL
NEXT_PUBLIC_GA_MEASUREMENT_ID="G-XXXXXXX"         # Optional - Google Analytics ID

📝 CMS (Basehub)

Required for web app

BASEHUB_TOKEN="bshb_pk_..."                       # Required - Get from Basehub Dashboard

📧 Email (Resend)

Required for all apps

RESEND_FROM="your-email@domain.com"               # Required - Sender email address
RESEND_TOKEN="re_..."                             # Required - Get from Resend Dashboard

💳 Payments (Stripe)

Required for all apps

STRIPE_SECRET_KEY="sk_test_..."                   # Required - Get from Stripe Dashboard
STRIPE_WEBHOOK_SECRET="whsec_..."                 # Required - Get from Stripe Dashboard

🔒 Security (Arcjet)

Optional - Only in production

ARCJET_KEY="ajkey_..."                           # Optional - Get from Arcjet Dashboard

📱 Notifications (Knock)

Optional

KNOCK_API_KEY=""                                  # Optional - Get from Knock Dashboard
KNOCK_FEED_CHANNEL_ID=""                          # Optional - Get from Knock Dashboard
KNOCK_SECRET_API_KEY=""                           # Optional - Get from Knock Dashboard
NEXT_PUBLIC_KNOCK_API_KEY=""                      # Optional - Client-side Knock key
NEXT_PUBLIC_KNOCK_FEED_CHANNEL_ID=""              # Optional - Client-side channel ID

🔄 Webhooks (Svix)

Required for all apps

SVIX_TOKEN="sk_test_..."                         # Required - Get from Svix Dashboard

🎨 Collaboration (Liveblocks)

Required for app

LIVEBLOCKS_SECRET="sk_test_..."                  # Required - Get from Liveblocks Dashboard

📈 Logging (Betterstack)

Required for all apps

# Server-side
BETTERSTACK_API_KEY="..."                        # Required - Get from Betterstack Dashboard
BETTERSTACK_URL="https://in.logs.betterstack.com" # Required - Betterstack ingestion URL

# Client-side (required)
NEXT_PUBLIC_BETTER_STACK_SOURCE_TOKEN="..."       # Required - Same as API key
NEXT_PUBLIC_BETTER_STACK_INGESTING_URL="..."      # Required - Same as URL

🚩 Feature Flags

Optional

FLAGS_SECRET=""                                   # Optional - Feature flags secret

🌐 App URLs

Required for all apps

# App-specific URLs (adjust ports as needed)
VERCEL_PROJECT_PRODUCTION_URL="http://localhost:3000"  # App port
NEXT_PUBLIC_APP_URL="http://localhost:3000"            # App URL
NEXT_PUBLIC_WEB_URL="http://localhost:3001"            # Web URL
NEXT_PUBLIC_API_URL="http://localhost:3002"            # API URL (web app only)
NEXT_PUBLIC_DOCS_URL="http://localhost:3004"           # Docs URL

Setup Instructions

1. Create Environment Files

Create .env.local files in each app directory:

• apps/app/.env.local
• apps/web/.env.local
• apps/api/.env.local

2. Get API Keys

Visit the following dashboards to get your API keys:

• Clerk: https://dashboard.clerk.com/
• Neon Database: https://console.neon.tech/
• PostHog: https://app.posthog.com/
• Basehub: https://basehub.com/
• Resend: https://resend.com/
• Stripe: https://dashboard.stripe.com/
• Arcjet: https://app.arcjet.com/
• Knock: https://knock.app/
• Svix: https://dashboard.svix.com/
• Liveblocks: https://liveblocks.io/
• Betterstack: https://betterstack.com/

3. Replace Placeholders

Replace all placeholder values (like sk_test_placeholder) with your actual API keys.

4. Validate Setup

Run the development server to check for validation errors:

cd apps/app && pnpm dev

Current Status ✅

Working Features:

• ✅ Turbopack compilation
• ✅ Betterstack logging integration
• ✅ Drizzle database setup
• ✅ Authentication flow
• ✅ Environment variable validation
• ✅ All apps responding correctly

Environment Files Status:

• ✅ apps/app/.env.local - Configured
• ✅ apps/web/.env.local - Configured
• ✅ apps/api/.env.local - Configured

Validation Status:

• ✅ All required environment variables present
• ✅ Format validation passing
• ✅ No missing dependencies
• ✅ No Prisma conflicts (migrated to Drizzle)

Next Steps

1. Replace placeholder values with real API keys for production
2. Test each integration individually
3. Set up production environment variables on your deployment platform
4. Configure webhooks for production use

Troubleshooting

Common Issues:

• Validation errors: Check that API keys match the expected format (e.g., sk_ prefix for Stripe)
• Missing variables: Ensure all required variables are present in each app's .env.local
• Port conflicts: Verify that each app uses the correct port (3000, 3001, 3002)

Validation Rules:

• Clerk keys must start with sk_ (server) or pk_ (client)
• Stripe keys must start with sk_ (server) or pk_ (client)
• PostHog key must start with phc_
• Basehub token must start with bshb_pk_
• Arcjet key must start with ajkey_
• URLs must be valid URLs
• Database URL must be a valid PostgreSQL connection string