In this tutorial, you will learn where to create environment variables, how to use them, and how to avoid common beginner mistakes.

This guide assumes you are new and want practical, safe rules you can follow every time.

What We Will Learn

• What environment variables are
• Where to create them in a React project
• The difference between server and client variables
• How to use them step by step
• Common mistakes beginners make
• A simple mental model you can remember

Step 1: What Environment Variables Are

An environment variable is just a value stored outside your code.

Think of it like a settings file:

• API URLs
• Keys
• Feature switches
• Environment specific values

Example:

API_URL=https://api.example.com

Your code reads this value instead of hard coding it.

Step 2: Where Environment Variables Live

In modern React (App Router), environment variables live in .env files at the root of your project.

Project Structure

my-app/
├── app/
├── components/
├── lib/
├── .env.local
├── package.json

The important file is:

.env.local

This file is not committed to Git and is safe for local development.

Step 3: Create the .env.local File

At the root of your project (same level as package.json):

1. Create a new file
2. Name it exactly:

.env.local

Now add your variables.

Step 4: Add Your First Environment Variables

Open .env.local and add:

DATABASE_URL=postgres://localhost:5432/mydb
NEXT_PUBLIC_API_URL=https://api.example.com

Important Rule (Very Important)

• Variables WITHOUT NEXT_PUBLIC_ → Server only (safe for secrets)

• Variables WITH NEXT_PUBLIC_ → Sent to the browser (NOT secrets)

Step 5: Understanding Server vs Client (Critical)

Server Environment Variables

These are safe.

DATABASE_URL=postgres://...
SECRET_KEY=abc123

Used for:

• Databases
• Private APIs
• Auth secrets

They must never be used in client components.

Client Environment Variables

These are public.

NEXT_PUBLIC_API_URL=https://api.example.com

Used for:

• Public API URLs
• Analytics IDs
• Feature flags

Anyone can see these in the browser.

Step 6: Using Environment Variables on the Server

Server files include:

• Server components
• Files in lib/
• API routes
• Server actions

Example: Server Config File

// lib/config.ts
export const databaseUrl = process.env.DATABASE_URL
export const apiUrl = process.env.NEXT_PUBLIC_API_URL

This file runs on the server.

Secrets are safe here.

Step 7: Using Environment Variables in Client Components

Client components must use only public variables.

Example Client Component

// components/api-info.tsx
"use client"
 
export function ApiInfo() {
  return (
    <p>
      API URL: {process.env.NEXT_PUBLIC_API_URL}
    </p>
  )
}

This value is baked into the browser bundle at build time.

Step 8: Very Common Beginner Mistake (Avoid This)

Never do this in a client component

process.env.DATABASE_URL

If you do this:

• The secret leaks
• Anyone can see it
• It is a security bug

Always remember:

If it reaches the browser, it is public forever

Step 9: Safe Pattern (Server Reads, Client Receives Data)

If the client needs something derived from secrets, do this:

Server Utility

// lib/get-public-config.ts
export function getPublicConfig() {
  return {
    apiUrl: process.env.NEXT_PUBLIC_API_URL
  }
}

Component

// components/config-view.tsx
import { getPublicConfig } from "../lib/get-public-config"
 
export function ConfigView() {
  const config = getPublicConfig()
  return <p>{config.apiUrl}</p>
}

Secrets never cross the boundary.

Step 10: Environment Variables Are Build Time

This is very important.

process.env.NEXT_PUBLIC_API_URL

• Is replaced during build
• Cannot change while the app is running
• Requires a rebuild to update

If you change .env.local, you must:

npm run dev

Restart the dev server.

Step 11: Feature Flags (Beginner Friendly Use Case)

.env.local

NEXT_PUBLIC_NEW_UI=true

Component

if (process.env.NEXT_PUBLIC_NEW_UI === "true") {
  return <NewUI />
}
 
return <OldUI />

Simple, safe, and common.

Step 12: What You Should NOT Use Environment Variables For

Do not use them for:

• User state
• UI state
• Dynamic values
• Things that change often

Environment variables are configuration, not state.

Simple Mental Model (Remember This)

• Server reads everything
• Client reads only NEXT_PUBLIC_
• Secrets never go to the client
• Variables are set before the app runs
• Restart after changing .env

If you remember this, you will avoid 90 percent of mistakes.

Beginner Checklist

Before using an environment variable, ask:

1. Is this a secret?
2. Does the browser need it?
3. Did I prefix it correctly?
4. Did I restart the dev server?

Conclusion

Environment variables in React are simple once you follow the rules:

• Create .env.local at the project root
• Keep secrets server only
• Use NEXT_PUBLIC_ intentionally
• Treat variables as build time constants

If you follow this step by step approach, you will use environment variables safely and confidently in any React app.