.env.local › «Recommended»

Since Vite bundles for both dev and build, remember that .env.local is loaded during vite build as well. Don't assume it's only for vite dev . 3. Node.js (Manual loading with dotenv) Pure Node.js doesn't have a native file loader. You use the dotenv package. In this case, you control the logic .

In the modern landscape of web development—whether you’re working with Next.js, React (Vite/CRA), Nuxt, or Node.js—environment variables are the bedrock of security and configuration management. You’ve likely encountered the standard .env file. But as your application grows in complexity, a new player enters the arena: .env.local .

Is it just another dotfile? Absolutely not. Misunderstanding .env.local can lead to production secrets leaking into your Git history, or worse, hours of debugging "why does my app work locally but not on staging?" .env.local

| File Name | Git Status | Environment | Use Case | | :--- | :--- | :--- | :--- | | | Committed (usually) | All (Default) | Baseline defaults. Non-sensitive config (e.g., DEFAULT_PORT=3000 , APP_NAME=MyApp ). | | .env.local | Ignored | Local Only | Personal overrides, secrets, machine-specific paths. | | .env.development | Committed | Development | Shared dev settings (e.g., API_URL=http://localhost:3001 ). | | .env.production | Committed | Production | Shared prod settings (e.g., API_URL=https://api.myapp.com ). | | .env.production.local | Ignored | Prod override | Emergency machine-specific production overrides (rare). | The Critical Rule of Overrides In almost every framework (especially Next.js), .env.local takes precedence over all other non-specific files. If API_KEY=abc123 is in .env and API_KEY=xyz789 is in .env.local , the application will use xyz789 locally.

This article dives deep into the .env.local file: what it is, how it differs from other env files, its security implications, and the exact patterns you need to use it effectively in 2025. At its core, .env.local is a plain text file used to store environment variables specifically for local development . It follows the same KEY=VALUE syntax as standard .env files, but its purpose and behavior are distinct. Since Vite bundles for both dev and build, remember that

# Only accessible on the server (Node.js) DATABASE_URL="postgresql://user:pass@localhost:5432/mydb" STRIPE_SECRET_KEY="sk_test_..." NEXT_PUBLIC_GA_ID="G-XXXXXXXXXX" 2. Vite (and Create React App) Vite uses .env.local similarly, with one crucial difference: variable prefix.

You are on a plane without internet. Your app usually calls a live API via API_URL=https://api.example.com . You drop API_URL=http://localhost:4000 into .env.local to point at a local mock server. Your teammates' configs remain unchanged. but always commit an .env.example file.

require('dotenv').config( path: '.env' ); require('dotenv').config( path: '.env.local', override: true ); Because you explicitly load .env.local second (with override: true ), it overwrites the default .env values. Using .env.local is easy. Using it well requires discipline. 1. The .env.example Contract Never commit .env.local , but always commit an .env.example file. This acts as documentation for your team.