Environment Variables

This guide provides a detailed overview of the environment variables required to run the SaaS Boilerplate. Properly configuring these variables is essential for features like authentication, database connections, payment processing, and more.

Setting Up Environment Variables

The SaaS Boilerplate uses a .env file for local development. To get started:

1. Copy the example environment file:

cp .env.sample .env

2. Edit the .env file with your specific configuration values

Core Environment Variables

Database Connection

# PostgreSQL connection URL
DATABASE_URL="postgresql://docker:docker@localhost:5432/docker?schema=public"
NEXT_RUNTIME="nodejs"

Replace the username (docker), password (docker), host (localhost), port (5432), and database name (docker) with your specific configuration.

Application Setup

# Name of your application
IGNITER_APP_NAME="SaaS Boilerplate"

# URL where your app will be running
IGNITER_APP_URL=https://localhost:3000/

# Path where your API will be running
IGNITER_APP_BASE_PATH=/api/v1

# Secret key for JWT (Replace this with a random string)
IGNITER_APP_SECRET=your_random_secret_key

# Application environment (development, production, test)
NODE_ENV="development"

Security Note: In production, always use a strong, unique IGNITER_APP_SECRET value. This key is used for signing JWTs and other security-related features.

Authentication Providers

The SaaS Boilerplate supports various OAuth providers for authentication:

# GitHub OAuth credentials
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret

# Google OAuth credentials
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret

Setting Up OAuth Providers

Google OAuth Setup:

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Navigate to API & Services > Credentials
4. Create an OAuth 2.0 Client ID
5. Add your application URL and callback URL (http://localhost:3000/api/auth/callback/google for local development)
6. Copy the Client ID and Client Secret to your .env file

GitHub OAuth Setup:

1. Go to GitHub Developer Settings
2. Click on "New OAuth App"
3. Fill in the application details
4. Set the callback URL to http://localhost:3000/api/auth/callback/github for local development
5. Copy the Client ID and Client Secret to your .env file

Storage Providers

For file storage capabilities, you need to configure your storage provider:

STORAGE_ENDPOINT=http://localhost:9000
STORAGE_ACCESS_KEY_ID=your_access_key_id
STORAGE_SECRET_ACCESS_KEY=your_secret_access_key
STORAGE_REGION=your_region
STORAGE_BUCKET=your_bucket_name

This configuration works with MinIO for local development, or with cloud providers like AWS S3, Google Cloud Storage, or similar services in production.

Billing Providers

For payment processing and subscription management, the SaaS Boilerplate uses Stripe:

# Stripe private key
STRIPE_SECRET_KEY=

# Webhook secret for verifying webhook events
STRIPE_WEBHOOK_SECRET=

# Public key for client-side Stripe integration
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=

Setting Up Stripe

1. Create a Stripe account
2. Get your API keys from the Stripe Dashboard
3. Set up your products and prices in the Stripe Dashboard
4. Create a webhook endpoint and get the webhook secret
5. For local testing, use the Stripe CLI to forward webhooks:

bun stripe:webhook

Using Environment Variables in Your Code

The SaaS Boilerplate works with Igniter.js, which provides a type-safe way to access environment variables:

// Example usage in your code
import { env } from "@/igniter";

// Access environment variables with type safety
const appUrl = env.IGNITER_APP_URL;
const isDevelopment = env.NODE_ENV === "development";

Environment-Specific Variables

You might want different configurations for development, testing, and production environments. The SaaS Boilerplate supports multiple environment files:

• .env.development - Used in development mode
• .env.test - Used when running tests
• .env.production - Used in production

Managing Environment Variables in Production

For production deployments, set your environment variables through your hosting provider's dashboard:

• Vercel

  Set environment variables in your project settings
• Netlify

  Configure environment variables in the Netlify dashboard
• AWS/GCP/Azure

  Use their respective secrets management services

Troubleshooting

Environment Variables Not Loading

If your environment variables are not being loaded correctly:

1. Make sure your .env file is in the root directory
2. Check for syntax errors in your .env file
3. Restart your development server after making changes
4. Verify that there are no spaces around the = sign in your variable definitions

Sensitive Information

Never commit your .env file to version control. Ensure it's included in your .gitignore file to prevent accidental exposure of sensitive information.

What's Next?

Now that you have configured your environment variables, you can proceed with:

• Local Development - Set up your local development environment
• First Steps - Start building your first feature