Skip to main content
The Next.js SaaS Starter requires several environment variables to be configured for proper operation. These variables control database connectivity, payment processing, authentication, and application URLs.

​
Setup Methods

You can configure environment variables in two ways:
  1. Automated Setup (Recommended): Run the interactive setup script
  2. Manual Setup: Create and configure the .env file yourself

​
Automated Setup

The easiest way to configure your environment is to use the automated setup script: 
pnpm db:setup
This interactive script will:
  • Check for Stripe CLI installation and authentication
  • Set up your PostgreSQL database (local or remote)
  • Retrieve your Stripe API keys
  • Create a webhook secret automatically
  • Generate a secure AUTH_SECRET
  • Write all variables to .env
The setup script requires the Stripe CLI to be installed. If not found, it will provide installation instructions.

​
Manual Setup

If you prefer to configure environment variables manually, create a .env file in the root of your project with the following variables:

​
Required Environment Variables

​
POSTGRES_URL
string
required
PostgreSQL database connection stringFormat: postgresql://[user]:[password]@[host]:[port]/[database]Example: postgresql://postgres:postgres@localhost:54322/postgresWhere to get it:
Keep your database credentials secure. Never commit .env files to version control.
​
STRIPE_SECRET_KEY
string
required
Your Stripe secret API key for processing paymentsFormat: sk_test_... (test mode) or sk_live_... (production)Where to get it:
  1. Go to Stripe Dashboard > API Keys
  2. Copy the “Secret key” (starts with sk_test_ for test mode)
  3. For production, switch to live mode and use your live secret key
Never expose your secret key in client-side code or commit it to version control.
​
STRIPE_WEBHOOK_SECRET
string
required
Stripe webhook signing secret for verifying webhook eventsFormat: whsec_...Where to get it:Development:
stripe listen --print-secret
This command will output your webhook secret. Copy the value that starts with whsec_.Production:
  1. Go to Stripe Dashboard > Webhooks
  2. Click “Add endpoint”
  3. Enter your webhook URL: https://yourdomain.com/api/stripe/webhook
  4. Select events to listen to (at minimum: customer.subscription.updated, customer.subscription.deleted)
  5. Copy the “Signing secret” from the webhook details page
The webhook secret ensures that webhook events are actually coming from Stripe and haven’t been tampered with.
​
BASE_URL
string
required
The base URL of your applicationDevelopment: http://localhost:3000Production: https://yourdomain.comThis is used for:
  • Stripe checkout success/cancel redirects
  • Billing portal return URLs
  • Email links and callbacks
​
AUTH_SECRET
string
required
Secret key for signing and encrypting authentication tokensHow to generate:
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
Or use OpenSSL:
openssl rand -hex 32
Use a cryptographically secure random value. Never reuse secrets across environments.

​
Example Configuration

Your .env file should look like this:
.env
POSTGRES_URL=postgresql://postgres:postgres@localhost:54322/postgres
STRIPE_SECRET_KEY=sk_test_51Abc123...
STRIPE_WEBHOOK_SECRET=whsec_abc123...
BASE_URL=http://localhost:3000
AUTH_SECRET=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6

​
File Location

The environment variables must be stored in .env (not .env.local) unless you modify the configuration.
From the source code comments in .env.example: 
# Note: this must be .env, not .env.local, without further configuration changes.
This is because Drizzle ORM and other server-side scripts need to access these variables outside of the Next.js runtime.

​
Security Best Practices

Never commit your .env file to version control. The .gitignore file should include .env to prevent accidental commits.
Use different values for development, staging, and production environments. Never share production credentials.

​
Additional Security Tips

  1. Rotate secrets regularly: Change AUTH_SECRET and regenerate API keys periodically
  2. Use test mode in development: Always use Stripe test keys (sk_test_) during development
  3. Limit API key permissions: Use restricted API keys in production when possible
  4. Monitor access: Review Stripe API logs and database access logs regularly
  5. Environment-specific values: Never use production database URLs or API keys in development

​
Troubleshooting

​
”POSTGRES_URL environment variable is not set”

This error occurs when the database client tries to connect without finding the POSTGRES_URL variable. Make sure:
  • Your .env file exists in the project root
  • The variable name is spelled correctly (case-sensitive)
  • There are no extra spaces around the = sign

​
Stripe webhook signature verification failed

This usually means:
  • STRIPE_WEBHOOK_SECRET is incorrect or missing
  • The webhook secret doesn’t match the endpoint configuration
  • In development, the stripe listen command isn’t running
See the Stripe Configuration page for detailed webhook setup instructions.

​
Next Steps

Database Setup

Configure PostgreSQL and run migrations

Stripe Setup

Set up payment processing and webhooks

Build docs developers (and LLMs) love

Get started for freeTalk to us