Lesson 3 of 6 · about 20 minutes

How environment variables work

The win One variable, three values: your app shows a different name in Production, in Preview and on your laptop, and you can say why a changed value did not show up until you redeployed.

This lesson uses a harmless value on purpose. Get the mechanics right with something that cannot hurt you, and the real keys in Lessons 4 and 5 become routine.

First, recall

Three facts carry the whole topic

1. A variable is a name, a value, and a list of environments. The same name can hold a different value in Production, in Preview and in Development. That is how one codebase talks to a live database in one place and a scratch database in another.

2. A deployment keeps the values it was created with. Changing a value in the dashboard changes nothing that is already running. The new value arrives with the next deployment, so after a change you redeploy.

3. In Next.js, the name decides who can see the value. A name beginning NEXT_PUBLIC_ is copied into the JavaScript sent to every visitor, at build time. Every other name stays on the server.

Where the values live on your laptop

Next.js reads a file called .env.local when you run npm run dev. You do not write that file by hand. vercel env pull downloads the project's Development values into it. create-next-app already ignores .env* in Git, so the file stays off GitHub.

Do it

Run these from the beachhead folder, on main.

1. Add one name with three values. The value is public by design, so passing it on the command line is fine here. --no-sensitive keeps it readable later.

   vercel env add NEXT_PUBLIC_APP_NAME production --value "Beachhead" --no-sensitive --yes
   vercel env add NEXT_PUBLIC_APP_NAME preview --value "Beachhead (preview)" --no-sensitive --yes
   vercel env add NEXT_PUBLIC_APP_NAME development --value "Beachhead (dev)" --yes

2. Look at what you made.

   vercel env ls

   Three rows, one per environment. The same list is in the dashboard under the project's Environment Variables page.

3. Pull the Development value down.

   vercel env pull

   Open .env.local and find NEXT_PUBLIC_APP_NAME. Then run git status: the file is not listed, because it is ignored.

4. Use it. Replace the home page with one line that shows the name.

   app/page.tsx

   export default function Home() {
     return <h1>{process.env.NEXT_PUBLIC_APP_NAME ?? "unnamed"}</h1>;
   }

   Run npm run dev and open localhost:3000. It says Beachhead (dev).

5. Ship it.

   git add -A
   git commit -m "Show app name from environment"
   git push

   When the deployment is ready, your production domain says Beachhead. Same code, different value.

6. Predict, then observe. Change the Production value:

   vercel env update NEXT_PUBLIC_APP_NAME production --value "Beachhead v2" --yes

   Before you reload the production page, say out loud what it will show.

   Reload it. What happened, and why?

   It still says Beachhead. The running deployment was built with the old value, and a NEXT_PUBLIC_ value is baked into the JavaScript at build time.

7. Redeploy. In the dashboard open Deployments, find the latest production deployment, open its ⋯ menu and choose Redeploy. When it finishes, reload: Beachhead v2.

That last pair of steps is the most common Vercel confusion there is. You have now seen it happen under controlled conditions.