Builder Toolkit · 07 / 11

Environment Variables

Understand local versus hosted settings, public versus server-only values, and why new variables need a rebuild.

Environment Variables

What this is

An environment variable is a setting stored outside your code, so the same project can behave differently in different places.

Your project reads a name such as SUPABASE_URL. The value lives on your machine and in your hosting settings, never in the code you commit.

The one idea

Code goes in Git. Values go in the environment. That separation is what lets you share your code without sharing your keys.

Why it matters

This is the number one cause of "it works on my laptop but the live site is broken".

Your local .env.local file is deliberately ignored by Git. It never reaches GitHub, so it never reaches your host. If you do not set the values again in your hosting dashboard, the live build has nothing to read.

What to do

Understand the two places

Place	File or screen	Used by
Local	`.env.local` in your project root	`npm run dev` on your machine
Hosted	Your host's environment variables settings	The live build and the live site

Same names in both places. Different place to put them. Setting one does not set the other.

Write a local file

Copy

NEXT_PUBLIC_SUPABASE_URL=https://yourproject.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

No quotes, no spaces around the equals sign, one per line. Confirm .env.local is listed in your .gitignore before you commit anything.

Know which values are public

This distinction protects you, and beginners get it wrong constantly.

Kind	Naming	Where it ends up	Safe to expose
Public	Prefixed, for example `NEXT_PUBLIC_`	Bundled into the browser code	Yes, by design
Server-only	No prefix	Stays on the server	No, never

A NEXT_PUBLIC_ value is visible to anyone who opens developer tools on your site. That is intended for things like a public project URL. Never give that prefix to a service role key, a database password, or a private token.

The prefix is a decision, not a formality

Adding NEXT_PUBLIC_ to a secret to silence an error publishes that secret to every visitor. If a value is failing because it is not reaching the browser, the fix is usually to move the work to the server, not to expose the key.

Add them to your host

Open your project settings on the host and find environment variables.
Add each name and value exactly as in your local file.
Save.
Redeploy. Existing deployments do not pick up new values.

Do this now

Open your hosting environment variables screen and compare it line by line with your local .env.local. Any name in one and not the other is a live bug waiting to happen.

Check yourself

.env.local exists locally and is ignored by Git.
Every variable my project needs is also set on my host.
I can explain which of my variables are public and which are server-only.
I know a new variable requires a redeploy.

If the live site errors but local works

Nine times out of ten it is a missing or misspelled variable on the host, or a variable added without redeploying. Check those two before touching any code.

Common mistakes

Assuming .env.local was uploaded with the project. It never is.
Adding variables on the host and not redeploying.
Typos in names. SUPBASE_URL fails silently and looks like a code bug.
Marking a secret as public to make an error disappear.
Keeping different values locally and on the host, then debugging phantom differences.
Pasting a full .env file into a chat or screenshot while asking for help.

Next step

Your settings are right in both places. Now give the project a real address: Domains and DNS.