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, AbacatePay, or InfinitePay), 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, AbacatePay, or InfinitePay), 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, configure the gateway for credits and the gateway for subscriptions independently.
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.
Use PAYMENT_GATEWAY for credits, recharges, and one-time payments. Prices marked with metadata.type = "annual_pay" use this same gateway as a one-time checkout with the complete annual value; changing it to stripe, abacatepay, infinitepay, or appmax does not require code changes. Keep NEXT_PUBLIC_PAYMENT_GATEWAY synchronized for the client UI. Keep PAYMENT_SIGNATURE_GATEWAY and NEXT_PUBLIC_PAYMENT_SIGNATURE_GATEWAY synchronized. Use PAYMENT_SIGNATURE_BILLING_MODE=native for the existing gateway-managed subscription flow, or internal_charge for new monthly subscriptions whose recurring control stays in the application and creates one checkout per period. Existing subscriptions are not migrated when the mode changes. Internal charges accept the methods declared by the selected gateway; InfinitePay exposes Pix + card and never creates a recurring gateway subscription. Also synchronize NEXT_PUBLIC_PAYMENT_SIGNATURE_BILLING_MODE for the monthly checkout UI.
When PAYMENT_GATEWAY=infinitepay or an internal subscription uses PAYMENT_SIGNATURE_GATEWAY=infinitepay, provide INFINITEPAY_HANDLE. The checkout uses the public endpoint /api/infinitepay/webhook; configure INFINITEPAY_WEBHOOK_URL when the derived application URL is not publicly reachable. InfinitePay confirms each webhook through payment_check before credits, annual access, or an internal subscription charge is released. Internal subscription checkouts use Pix + card as a single payment; they do not create a recurring gateway subscription. See the InfinitePay Checkout documentation and the InfinitePay Help Center.
With InfinitePay, the annual checkout remains a single annual charge for the system, while Pix/card installment options (up to 12x when available for the account) are presented by InfinitePay itself.
When using Appmax, credits and annual plans use a hosted payment link with values in cents, Pix/card/boleto options, and up to 12 installments. Monthly subscriptions use the internal Appmax checkout: the browser tokenizes the card with Appmax JS, and the server sends only the resulting token to Appmax. Configure the application credentials in APPMAX_CLIENT_ID and APPMAX_CLIENT_SECRET, the application UUID in APPMAX_APP_UUID, and the numerical application ID in APPMAX_APP_ID. In the billing screen, open Configurar under Conexão Appmax to authorize the merchant. The app then calls /app/client/generate after the redirect, stores the merchant credentials encrypted in the database, and uses those credentials for /v1/*; do not use the application credentials directly for transactions. During Appmax installation, use the public POST https://your-domain.com/api/appmax/health-check as the validation URL. It accepts only the required numeric app_id, returns a new UUID in external_id, and persists the latest UUID for Appmax JS tokenization. Appmax webhooks are received at /api/appmax/webhook and can optionally be protected with APPMAX_WEBHOOK_TOKEN. The Appmax customer portal is not available in this integration.
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.