Next.js Environment Variables

What are Environment Variables?
Creating Environment Variables
Types & Priority of .env Files
Accessing Environment Variables
Server vs Client Variables
Security Best Practices
Validation & Defaults
Deployment & Platform Notes
Common Pitfalls

Environments variables are used to store configuration values that can vary between different environments (e.g., development, staging, production).

Instead of hardcoding sensitive data in your code, you store it in environment variables, which improves security and flexibility. Environment variables help you keep secrets out of your codebase and make your app portable across environments.

Use cases

API keys (Stripe, SendGrid, etc.)
Database URLs and credentials
Secret tokens (JWT, OAuth, etc.)
Third-party service credentials
Feature flags and toggles
Analytics and monitoring keys
Environment-specific configuration (domains, ports, etc.)

Next.js provides built-in support for environment variables.

Create Environment Variables

Environment variables in Next.js are used to store configuration values that can vary between different environments (e.g., development, staging, production).

To create environment variables in Next.js, you can use a .env file in the root of your project.

For example, you can create a .env file with the following content:

# .env
            DATABASE_URL=postgres://user:password@localhost:5432/mydb
            API_KEY=your-api-key
            SECRET_TOKEN=your-secret-token

Next.js will automatically load the environment variables from the .env file and make them available in your application.

Type of environment variables

Next.js supports multiple environment files:

File Name	Usage
`.env.local`	Used for local development and is ignored by git
`.env.development`	Used for development environment
`.env.production`	Used for production environment
`.env.test`	Used for testing environment
`.env`	Default environment variables that are loaded in all environments

Accessing Environment Variables

You can access environment variables in your Next.js application using the process.env object.

For example, you can access the DATABASE_URL environment variable like this:


  const databaseUrl = process.env.DATABASE_URL;
  const apiKey = process.env.API_KEY;
  const secretToken = process.env.SECRET_TOKEN;

You can also use environment variables in your Next.js API routes and server components.

Server vs Client Environment Variables

By default, all environment variables are only available on the server side. If you want to expose certain environment variables to the client side, you need to prefix them with NEXT_PUBLIC_.

Server Environment variables

These are available only on the server side and are not exposed to the client.

For Example:


  const databaseUrl = process.env.DATABASE_URL;

Client Environment variables

These are prefixed with NEXT_PUBLIC_ and are available on both the server and client sides.

For Example:

 // NEXT_PUBLIC_API_URL
  const apiUrl = process.env.NEXT_PUBLIC_API_URL;

Restart app after changing environment variables

After changing environment variables, you need to restart your Next.js application for the changes to take effect.

npm run dev

Security Best Practices

Never commit secrets or .env files to version control. Add .env* to your .gitignore.
Only expose variables to the client by prefixing with NEXT_PUBLIC_.
Use strong, unique values for secrets and tokens.
Rotate secrets regularly and after leaks.
Never log secrets or sensitive values.
Use environment-specific files for different deployments.

Deployment & Platform Notes

Set environment variables in your deployment platform's dashboard (Vercel, Netlify, Railway, etc.).
For Docker, use --env-file or -e flags.
On Vercel, .env files are not deployed—set variables in the dashboard.
On Netlify, use the site settings for environment variables.
Restart your app after changing environment variables.

Common Pitfalls

❌ Committing secrets to Git: Always use .gitignore for .env* files.
❌ Exposing secrets to client: Only use NEXT_PUBLIC_ for safe values.
❌ Forgetting to restart: Changes to .env require a restart.
❌ Typos in variable names: Misspelled names won't be loaded.
❌ Using process.env in the browser for server-only vars: Only NEXT_PUBLIC_ vars are available client-side.
❌ Missing validation: Always check required variables at startup.