Environment (.env) files and .gitignore

[dennisvang]

Nearly every source on the web advises against committing any .env files into git (or other version control system).

For example, here's from the dotenv FAQ:

FAQ
Should I commit my .env file?

No.

This makes perfect sense to me.

I assumed that ignoring .env files was a general "best practice," and, knowing that vite uses dotenv, I expected this to apply to vite as well.

However, -- please correct me if I'm wrong -- contrary to the above, the vite docs appear to suggest that .env files should be committed, except for .env*.local files:

.env                # loaded in all cases
.env.local          # loaded in all cases, ignored by git

and

Ignoring local .env files

.env.*.local files are local-only and can contain sensitive variables. You should add *.local to your .gitignore to avoid them being checked into git.

This comes as a surprise, and it sounds rather risky to me.

For example, what happens if a new dev, like me, assumes all .env files are ignored, and is unaware of the distinction between .env and .env.local?

Could someone shed some light on this?

[dennisvang]

#19471 is related but does not provide a clear answer.

[dennisvang]

Another example from the twelve factor app:

The twelve-factor app stores config in environment variables [...] unlike config files, there is little chance of them being checked into the code repo accidentally; [...]

[MukundaKatta]

Your instinct is right and the Vite docs aren't really contradicting the "don't commit .env" advice — they're describing a split that the generic dotenv FAQ doesn't talk about. The key idea:

Vite treats .env as a shared-default file, not a secrets file. Only variables prefixed with VITE_ end up in client code at all, and those are by definition public (they're embedded in the JS bundle your users download). So the committed .env / .env.production / .env.development files are for non-secret, shared defaults. Per-developer values and secrets go in .env*.local, which is git-ignored.

To make this concrete:

.env                    # shared across everyone, committed
.env.development        # shared dev defaults, committed
.env.production         # shared prod defaults, committed
.env.local              # YOUR machine, NOT committed
.env.development.local  # YOUR dev overrides, NOT committed
.env.production.local   # YOUR prod overrides, NOT committed

Concretely:

# .env  (committed)
VITE_API_URL=https://api.example.com
VITE_FEATURE_FLAGS=chat,search

# .env.local  (git-ignored)
VITE_API_URL=http://localhost:3000
API_SECRET=dev-only-key-never-shipped

Two rules that keep this safe:

1. Nothing you'd be unhappy to see in the bundled JS belongs in a committed file, ever. The VITE_ prefix is a hard rule — Vite refuses to expose non-prefixed vars to client code precisely so you can keep DATABASE_URL, API_SECRET, etc. in the same .env ecosystem without leaking them. But if you commit a .env with a VITE_STRIPE_SECRET_KEY in it, that absolutely ships to the browser — the prefix is a gate for exposure, not a marker of safety.

2. Your new-dev failure mode is real — solve it with a checklist, not a convention. Add .env*.local to .gitignore (Vite does this in the scaffolded templates) and put an .env.example in the repo:

   # .env.example — committed; copy to .env.local and fill in
   VITE_API_URL=http://localhost:3000
   API_SECRET=
   STRIPE_SECRET_KEY=
   

   This is the twelve-factor story you linked, just adapted to the Vite loader — your secrets still live in env vars at runtime, and the .env*.local files are just a dev-ergonomics shim so you don't have to export everything by hand.

How this compares to the dotenv FAQ

The generic dotenv advice ("don't commit .env") was written in a world where .env was the secrets file. Vite and Next.js and Nuxt all split the file into tiers precisely because frontend frameworks have legitimate use for committed, non-secret config (API base URL, public analytics keys, feature flags). The naming convention is the mechanism — .local is the tier you never commit. So both docs can be correct simultaneously:

• dotenv's .env ≈ Vite's .env.local
• Vite's .env has no equivalent in plain dotenv; it's a per-mode shared defaults file.

If your team comes from a plain-dotenv background, a one-line README note ("Vite-style: commit .env, put secrets in .env.local") saves a lot of onboarding pain.

[lonvarscsak]

Thank you for this, I was pulling my hair out figuring how to store base configs in the repo (without secrets) and all the "dont commit .env stuff" had me perplexed. :P

[dennisvang]

Thanksi @MukundaKatta, I appreciate the quick response and detailed answer. 🙂

Just out of curiosity: Why not use a dedicated file type (without .env in the filename) for default config, to make the difference explicit? Many backend frameworks use this approach. For example in Spring default config can be placed in a yaml file, which is under version control, and environment variables can be used to override that default config.

[codeXsidd]

To safely handle your environment variables in a Vite project without leaking secrets to
GitHub

, follow this standard setup:

1. Update your .gitignore

Make sure you are only pushing your base environment templates to GitHub, while keeping secret keys completely local. Add these lines to your .gitignore file:

# Local environment variables (Secret keys)
.env.local
.env.*.local

# Ignore actual production/development environments if they contain sensitive data
.env.development.local
.env.production.local

2. Name your variables correctly in Vite

Vite protects you from accidentally leaking secrets to your client-side bundle. By default, it will only load environment variables that are prefixed with VITE_.

• In your .env.local file:

  VITE_API_URL=https://example.com
  SECRET_BACKEND_KEY=12345  # This will NOT be exposed to the client
  

3. Accessing them in your code

In Vite, you do not use process.env. Instead, access them via import.meta.env:

const apiUrl = import.meta.env.VITE_API_URL;
console.log(apiUrl); // Outputs: https://example.com

[DaCameraGirl]

You're reading the Vite docs correctly — and the apparent contradiction with general dotenv advice is intentional. Vite makes a deliberate design choice here that's worth understanding.

The Vite Model: Split By Purpose, Not By Name

Vite distinguishes between shared defaults (committed) and local overrides/secrets (ignored):

File	Committed?	Purpose
.env	Yes	Shared defaults for all environments
.env.development	Yes	Shared dev defaults
.env.production	Yes	Shared prod defaults
.env.local	No (git-ignored)	Local overrides — your personal dev values
.env.development.local	No	Local dev overrides
.env.production.local	No	Local production overrides (rare)

Vite's .gitignore template already ignores *.local files out of the box.

Why This Is Different From dotenv's "Never Commit"

The dotenv FAQ is really saying: don't commit secrets. The method it suggests (ignore everything) is conservative. Vite's approach is more precise: the .env file should only contain non-secret, safe-to-share values.

The key distinction:

# .env — SAFE TO COMMIT (no secrets)
VITE_API_URL=https://api.example.com
VITE_APP_NAME=My App
VITE_FEATURE_FLAGS_ENABLED=true

# .env.local — NOT committed (personal/secret values)
VITE_API_KEY=sk-my-real-key   # ❌ don't put this in .env!
DATABASE_URL=postgres://...

The VITE_ Prefix Rule is Critical

Only variables prefixed with VITE_ are injected into your client bundle via import.meta.env. Never put actual secrets in a VITE_ variable — they will appear in plain text in your JavaScript bundle that anyone can inspect.

// In your component — this gets embedded in the public JS bundle!
console.log(import.meta.env.VITE_API_URL) // OK — a public URL
console.log(import.meta.env.VITE_SECRET_KEY) // ❌ NEVER DO THIS

Variables without the VITE_ prefix (e.g., DATABASE_URL) are available in vite.config.ts server-side code only, never in client code.

Recommended .gitignore Setup

# .gitignore
.env.local
.env.*.local

# Optional: keep .env itself but document it's safe-to-share
# .env   <-- do NOT ignore this

Best Practice: Add a .env.example

Commit a .env.example with all required variable names but empty/placeholder values. This documents what every developer needs to set up without leaking real values:

# .env.example — always committed
VITE_API_URL=
VITE_APP_NAME=
ANY_SECRET_VAR=  # this goes in .env.local only

New developers clone the repo and copy it: cp .env.example .env.local then fill in real values.

TL;DR

Vite's convention is correct and not contradictory to security advice. Commit .env with only non-sensitive shared config. Put any secret or personal value in .env.local (which is git-ignored by default). The VITE_ prefix intentionally limits what lands in the client bundle.

[ltianyi992]

You are not wrong to feel confused — this is a genuine distinction that Vite makes intentionally, and it differs from the pure dotenv convention.

Vite's mental model:

File	Committed?	Contains
.env	✅ Yes	Non-secret defaults, safe for all environments
.env.development	✅ Yes	Dev-specific non-secret values
.env.production	✅ Yes	Prod-specific non-secret values
.env.local	❌ No	Local overrides (any environment)
.env.*.local	❌ No	Environment-specific local overrides

The key insight is: only VITE_* prefixed variables are exposed to the browser bundle. Vite intentionally requires the VITE_ prefix to prevent accidentally leaking server-side secrets into the frontend JS.

So the convention is:

• .env stores public, non-sensitive values that are safe to commit — things like VITE_API_BASE_URL=https://api.example.com or feature flag defaults
• Sensitive values should never have the VITE_ prefix — they stay in .env.local or in your CI/CD secrets manager, and are never exposed to the bundle

Best practice for teams:

1. Commit .env and .env.production with non-secret VITE_* values
2. Add .env*.local to .gitignore (Vite does this by default)
3. For secrets that a build needs (API keys, tokens), use CI secrets / Cloud Build substitutions — never store them in any committed .env
4. Provide a .env.example file with all variable names but no real values, so new devs know what to create in their .env.local

This is different from the dotenv-for-Node.js convention because in a Node app, .env contains secrets that never leave the server. In a Vite app, everything with VITE_ prefix is public by design — so committing those defaults is generally safe.

[Nithwin]

The confusion here is real — I hit the same wall when I first started with Vite. The short version: Vite's .env convention is intentionally different from generic dotenv advice, and once you understand why, the mental model clicks.

Why Vite commits .env files (and it's not a mistake)

Generic dotenv advice ("never commit .env") exists because in a traditional server-side app, your .env holds secrets — DB passwords, API keys, tokens. You never want those in git.

Vite's situation is fundamentally different: it's a frontend build tool. Anything that ends up in import.meta.env gets baked into your JavaScript bundle and shipped to users' browsers. So there are no secrets in Vite's env system to begin with — if you put a secret key in VITE_STRIPE_SECRET, it becomes a public string visible to anyone who opens DevTools.

Given that, Vite splits env files by audience, not by sensitivity:

File	Committed?	Purpose
.env	✅ Yes	Shared defaults for everyone
.env.development	✅ Yes	Shared dev defaults
.env.production	✅ Yes	Shared prod defaults
.env.local	❌ No	Your local machine overrides
.env.*.local	❌ No	Per-mode local overrides

The .local suffix = "this is mine, not the team's."

Your practical setup

# .env (committed — public defaults only, never secrets)
VITE_API_URL=https://api.example.com
VITE_APP_NAME=MyApp

# .env.local (git-ignored — your personal overrides)
VITE_API_URL=http://localhost:3000

For actual secrets that your backend needs? Don't put them in Vite env files at all — they belong in server environment variables (CI/CD secrets, platform config), not in anything with a VITE_ prefix.

The .env.example pattern (solves your new-dev concern)

Commit an .env.example to the repo:

# .env.example — copy this to .env.local and fill in your values
VITE_API_URL=http://localhost:3000
# INTERNAL_API_SECRET=   <-- server only, never VITE_-prefixed

Add one line to your README: "copy .env.example to .env.local". New devs follow one step, nothing sensitive leaks.

To answer your Spring comparison — the reason Vite doesn't use a separate file type is it leverages the existing OS/shell ENV=value convention that every CI system, Docker, and platform-as-a-service understands natively. The .local suffix is Vite's way of carving out a git-ignored tier within that convention.

Both docs are correct simultaneously:

• dotenv's .env ≈ Vite's .env.local (the secrets file, never committed)
• Vite's .env has no plain-dotenv equivalent — it's a shared defaults file for non-secret public config

If your team comes from a plain-dotenv background, a one-liner in the README ("Vite-style: commit .env for shared defaults, put secrets in .env.local") saves a lot of onboarding confusion.