Your App Works on Your Laptop. Why Does It Break When You Deploy?

Your AI-built app runs perfectly in the editor. You deploy it. The login page loads, then nothing works. Or worse, everything works, and a secret key is sitting in the JavaScript any visitor can download.

Both problems usually come from the same place: environment variables. These are the settings your app reads when it builds or runs, such as database URLs, API keys and payment keys. They live outside your code on purpose. That also makes them easy to forget.

This piece uses Vercel and Next.js as the example, because it is a common pairing and both sets of docs are clear. The questions apply to any host.

What an environment variable is, in one paragraph

Vercel's environment variables docs describe them as key-value pairs configured outside your source code, so each value can change depending on the environment. Vercel says these values are encrypted at rest. Your code reads them during the build or while a function runs.

On your laptop, they usually sit in a file like .env.local. On the host, you add them in the project settings. If you only did the first part, your deployed app is missing its settings.

One app, three environments

Vercel lets you apply each variable to one or more environments:

• Production: used by your next production deployment, usually created by pushing to the main branch.
• Preview: used by deployments from any other branch.
• Development: used when you run the project locally. The vercel env pull command downloads these into a .env file.

This is useful. Your preview builds can talk to a test database and a test payment account, while production uses the real ones. It is also where mistakes happen. A key added only to Preview will be missing in Production. A live key added to every environment means test branches can touch real data.

Changing a value does not change the live app

This one surprises people. The Vercel docs say changes to environment variables are not applied to previous deployments. They only apply to new deployments.

So if you fix a wrong key in the dashboard and refresh your site, nothing changes. You need to redeploy.

The prefix that makes a value public

In Next.js, variables are only available on the server by default. The Next.js environment variables guide explains that adding the NEXT_PUBLIC_ prefix tells Next.js to inline the value into the JavaScript sent to the browser.

That is fine for a public analytics ID. It is not fine for a secret. Anything with that prefix should be treated as published. If an AI tool added NEXT_PUBLIC_ to a key so an error would go away, the error went away because the key is now public.

The guide also notes that these public values are frozen at build time. Changing them later means building again.

Keep .env files out of Git

The Next.js guide warns that you almost never want to commit .env files to your repository, and says the default create-next-app template adds them to .gitignore. If your app was generated by a different tool, check. It takes one search.

The Deploy Settings Check

Here is a short check I'd run on any AI-built app before calling it shippable.

1. List every variable the app reads. Search the code for process.env. Write the names down.
2. Is each one set on the host? Compare your list with the host's settings page, one name at a time.
3. Is each one in the right environment? Live payment and database keys in Production only. Test keys in Preview and Development.
4. Does any secret start with NEXT_PUBLIC_? If yes, assume it has been exposed and replace it.
5. Are .env files ignored by Git? Open .gitignore and check. Then check the repository itself.
6. Did you redeploy after the last change? If not, the live app is still using the old values.

If you can answer all six, most "works locally, broken in production" bugs have nowhere to hide.

Why this belongs in "shippable"

A prototype runs on one machine with one set of settings. A product runs in several places, with different settings in each, and some of those settings are secrets. Getting them right is boring work. It is also the difference between an app that deploys cleanly and one that leaks.

If you only do one thing after reading this: search your code for NEXT_PUBLIC_ today and read every name it finds.

Shaheer Malik is a design engineer for founders, taking products from AI prototype to shippable product. If your prototype needs to become something real users can rely on, Ship It Live is how he does it. See how Ship It Live works.

Researched and drafted with AI assistance; facts checked against the linked sources.