Environment Configuration
Centralized Configuration Management
The Next.js Boilerplate is engineered to provide a seamless transition from local development to production-scale deployment. By centralizing all configuration settings, the system ensures that your application remains consistent, secure, and easy to maintain as your project grows.
This boilerplate utilizes a robust environment variable strategy that eliminates the "it works on my machine" problem, allowing you to focus on building features rather than debugging deployment scripts.
Type-Safe Environment Variables
To prevent runtime errors and ensure developer confidence, the boilerplate integrates type-safe environment configuration. Using T3 Env, every environment variable is validated against a defined schema at startup.
Key Benefits:
- Early Error Detection: If a required variable (like an API key) is missing or incorrectly formatted, the application will fail to start and provide a clear error message, preventing broken deployments.
- Auto-Completion: Developers benefit from full TypeScript IDE support when accessing environment variables.
- Secure Exposure: It enforces a strict separation between server-side secrets and client-side public variables, preventing accidental data leaks.
Core Integration Settings
The boilerplate comes pre-configured for the industry’s leading services. To activate these features, you simply need to provide the corresponding keys in your .env files.
🔐 Authentication (Clerk)
Manage user identity effortlessly. The boilerplate is pre-wired for passwordless login, social auth, and multi-factor authentication.
- Benefit: Zero-boilerplate auth setup that scales from 1 to 1,000,000 users.
💽 Database (DrizzleORM)
The system supports multiple database engines (PostgreSQL, SQLite, and MySQL) through DrizzleORM.
- Local Development: Uses PGlite, a WASM-based Postgres that runs locally without needing a Docker container or external server.
- Production: Optimized for Prisma Postgres or any compatible PostgreSQL provider.
🛡️ Security & Protection (Arcjet)
Configuration includes built-in bot detection, rate limiting, and attack protection.
- Benefit: Protect your application from malicious actors and API abuse with minimal configuration.
🚨 Error Monitoring & Analytics (Sentry & PostHog)
Turn on professional-grade monitoring by simply adding your DSN and API keys.
- Sentry: Provides real-time crash reporting and performance monitoring.
- PostHog: Delivers deep insights into user behavior and feature adoption.
Local vs. Production Environments
The boilerplate simplifies the management of different deployment stages through standard environment files:
| File | Intended Use |
| :--- | :--- |
| .env.local | Local development overrides (git-ignored to keep secrets safe). |
| .env.production | Settings specific to your live production environment. |
| .env.test | Isolated configuration for running Vitest and Playwright suites. |
Localization and App Config
Beyond environment variables, high-level application behavior is managed through the src/utils/AppConfig.ts file. This is the "control center" for your product's identity, including:
- Multilingual Support: Define supported locales (e.g., English, French) and the default language.
- Metadata: Set your product name and SEO defaults.
- Clerk Localizations: Easily map authentication UI languages to your app's supported locales.
export const AppConfig = {
name: 'Your Product Name',
locales: ['en', 'fr'],
defaultLocale: 'en',
localePrefix: 'as-needed',
};
By leveraging this structured configuration approach, the Next.js Boilerplate ensures your application is not just a collection of files, but a production-ready system capable of scaling with your business needs.