Environment Setup
Configure .env for auth, billing, storage, email, and API. Includes examples and verification steps.
Welcome to the environment setup guide for the SaaS Boilerplate! If you're new to configuring applications, don't worry—this guide will walk you through every step in a clear, step-by-step manner. Environment variables are like secret settings that tell your application how to connect to databases, handle authentication, and integrate with external services. We'll explain what each one does, why it's important, and how to get the right values. By the end, your .env file will be ready, and you'll understand how everything fits together.
Why Environment Variables Matter
In web development, especially with frameworks like Next.js, environment variables keep sensitive information—like passwords, API keys, and database connections—separate from your code. This is crucial for security: you never want to hardcode secrets in your source files, as they could be exposed if your code is shared or deployed publicly. Instead, you store them in a .env file, which is ignored by version control (like Git) and loaded only when the app runs locally or in production.
The SaaS Boilerplate uses several environment variables to power features like user authentication (via Better Auth), payment processing (via Stripe), file storage, email sending, and more. If these aren't set correctly, your app might fail to start or behave unexpectedly. Let's dive into setting them up.
Before You Begin
Before configuring your environment variables, make sure you have the prerequisites in place. This ensures a smooth setup process.
- Node.js 22+: This is the runtime for your application. You can download it from the official Node.js website. If you're new to Node.js, it's a JavaScript runtime that lets you run code outside a browser.
- Docker Desktop: We'll use Docker to run a local PostgreSQL database. Download it from Docker's website. Docker packages software into containers, making it easy to run databases locally without installing them directly on your machine.
- A Text Editor: Something like VS Code, which you can get from code.visualstudio.com, to edit your
.envfile. - Optional: Accounts for Integrations: If you plan to use social logins (GitHub/Google), payments (Stripe), storage, or email, sign up for those services. We'll cover them in their respective sections.
Once you have these, you're ready to proceed. If you haven't already, clone the repository and install dependencies as described in the Quickstart guide.
Creating Your .env File
The first step is to create a copy of the sample environment file provided with the boilerplate. This gives you a template with all the variables you need.
Copy the Sample File
In your terminal, navigate to the root of your project (where you cloned the repository) and run:
cp .env.sample .envThis command creates a new file called .env by copying .env.sample. The .env file is where you'll add your actual values. Never commit .env to Git—it's listed in .gitignore to keep your secrets safe.
Open and Edit .env
Open .env in your text editor. You'll see a list of variables with placeholder values or comments. We'll fill them in one by one in the sections below. Save the file after each change.
Core Variables
These are the essential variables needed to get your app running. We'll explain each one, why it's needed, and how to set it.
Igniter Framework
These variables configure the core framework settings.
Prop
Type
For production databases, use a managed service like Prisma Cloud or Neon. They'll give you a connection string. Always use secure credentials and enable SSL.
Application Setup
These variables define your app's basic configuration.
Prop
Type
For IGNITER_APP_SECRET, generate a secure random string with openssl rand -base64 32.
Auth Providers (Optional)
These enable social logins via GitHub and Google, powered by Better Auth. Learn more in the Better Auth documentation.
Prop
Type
To get GitHub credentials: Go to GitHub Settings > Developer settings > OAuth Apps. Create a new app, set the callback URL to http://localhost:3000/api/auth/callback/github (adjust for production). Copy the Client ID and Client Secret.
For Google: Visit the Google Cloud Console. Create a project, enable the Google+ API, and set up OAuth 2.0 credentials. Set the redirect URI to http://localhost:3000/api/auth/callback/google.
Better Auth supports email/password login, OTP, and these social providers. If you skip these, users can still sign up with email.
Storage Providers (Optional)
For file uploads, the app can use cloud storage like AWS S3 or local alternatives like MinIO.
Prop
Type
For AWS S3, create an IAM user with S3 permissions and generate access keys. For MinIO, use the defaults. See the AWS S3 docs for more.
Billing Providers (Optional)
If your SaaS app charges users, Stripe handles payments seamlessly.
Prop
Type
Sign up at stripe.com, go to your dashboard, and find the "API keys" section. Use test keys for development. For webhooks, create an endpoint in Stripe and use the CLI for local testing: stripe listen --forward-to localhost:3000/api/webhooks/stripe.
For more on Stripe integration, see the Stripe API docs. The boilerplate includes pre-built endpoints for subscriptions and portals.
Email Providers (Optional)
To send emails (e.g., for password resets or notifications), configure an email service. We recommend SMTP for development (with MailHog for testing) and Resend for production.
Prop
Type
For development, leave as SMTP to use simulate send e-mails with MailHog(https://localhost:8025). For production, switch to Resend and get your API key from resend.com. For more on email setup and adding custom providers, see the Email guide.
Setting Up and Verifying
Now that you've configured the variables, let's apply them and test.
Run Database Migrations
With your DATABASE_URL set, run:
npm run db:migrate:devThis uses Prisma to create tables in your database. If it fails, double-check your URL and ensure Docker/PostgreSQL is running.
Start the Development Server
Launch your app:
npm run devVisit http://localhost:3000 in your browser. You should see the homepage. Check http://localhost:3000/docs for the documentation.
Verify Everything Works
- Database: Run
npm run db:studioto open Prisma Studio (a web interface for your database). You should see tables likeuserandsession. - Auth: Try signing up a user. If Better Auth is configured, it should work.
- API: Test an endpoint, like fetching users, to ensure Igniter is responding.
- Optional Features: If you set up Stripe, try a test payment. For storage, upload a file.
Troubleshooting
Even with careful setup, issues can arise. Here's how to fix common problems:
If you're stuck, check the console logs in your terminal or browser dev tools. The Next.js debugging guide can help.
Best Practices
See Also
- Quickstart - Get the basics running.
- Running Locally - Start your dev server.
- Authentication Guide - Deep dive into Better Auth.
- Billing Guide - Integrate Stripe fully.
- Environment Variables Reference - Full list with defaults.