Vercel: Environment Variables Without .env in Git

This guide is for a project already hosted on Vercel. You need access to its settings and an understanding of which variables the application reads. The example below applies to Next.js; variable names from another framework cannot be carried over automatically. The guide is based on official documentation; it has not been tested on a real account.

Practical information about using Ailoot is available in the documentation.

Why you do not need to add .env to Git#

An environment variable is a setting with a name and a value that an application receives separately from its source code. For example, the name SERVICE_API_KEY lets the program access the value of an external service's key. Do not put the key itself in the guide, your conversation with an agent or the repository.

Next.js can load variables from local .env* files. However, a local file and a project's settings in Vercel are two separate locations. If the file is not pushed to the repository, set the values on the hosting platform separately. The standard create-next-app template adds .env files to .gitignore; the Next.js documentation warns that you should almost never push them to the repository.

If you are still unsure what can be stored in source files, start with the security check for a project built with AI. Here, we are addressing a narrower question: where to set the configuration for a specific Vercel deployment.

First, determine where the application reads the variable#

Before entering any values, make a list of names, without the secrets themselves. For each name, you need to establish three things: which environment uses it, where the code that reads the variable runs, and when the value is needed.

The Development environment is intended for local development. Preview is for preview deployments, and Production is for the main published version. Preview can have settings for a specific Git branch: these override the general Preview settings with the same names.

In a Next.js project, variables without NEXT_PUBLIC_ are available on the server by default. The NEXT_PUBLIC_ prefix allows the value to be embedded in the JavaScript delivered to the browser. This is suitable for a setting that is explicitly public, such as a non-secret version label, but not for a private API key. Even without this prefix, application code must not manually return a secret to the client.

If you have not yet identified the framework, ask the agent to identify it from the project files. The comparison of Astro and Next.js can help you understand the differences; you cannot apply the NEXT_PUBLIC_ rule to every React application.

Hosting configuration is one of the tasks involved in working on an application with an AI agent.

How to add a variable to a Vercel project#

Carry out the steps in the official dashboard yourself. Do not give the agent a real key to fill in the form, and do not attach a screenshot containing its value.

1. Open the Vercel dashboard and select the correct project. Do not rely solely on a matching repository name: check that you are configuring the application you intend to open.
2. Go to Environment Variables in the project settings sidebar.
3. In Name, enter the name the application reads, such as SERVICE_API_KEY. This is an example name; if the code expects another one, use its exact spelling.
4. In Value, enter the value from your credential store. Do not put it in the source code, a chat or a verification log.
5. Select the environment that needs this setting. Use Preview to check a preview version and Production for the main version. Do not automatically assign one secret to all environments.
6. If the Preview setting applies to a specific branch, check the selected branch and any override with the same name.
7. Click Save.

Vercel makes project variables available both during the build and when server-side Vercel Functions run. However, a value being available within Vercel does not mean it can be sent to the browser: that depends on the application code and the framework's rules.

Why you need a new deployment after Save#

Saving a variable does not change existing deployments. The Vercel documentation requires you to redeploy the project for the new setting to reach the version you use.

When working through Git, you can create a new Production deployment by pushing a commit to the branch specified in Production Branch, and a Preview deployment by pushing to another branch. Do not assume the main branch is always main: check your project's setting. This should be a normal, agreed project release, without adding a secret file to the commit.

After starting the deployment, wait for the build to finish and open the URL of the new deployment. Keep a record of its URL, environment and branch. If you check the old URL of an individual deployment, the new settings will not appear there.

Next.js has another condition: references such as process.env.NEXT_PUBLIC_RELEASE_LABEL are replaced with their values during next build. The value is fixed after the build. Changing the setting without a new build will not rewrite client-side JavaScript that has already been delivered.

How to check the result without exposing the key#

Start with a safe example: an explicitly non-secret label named NEXT_PUBLIC_RELEASE_LABEL with the value preview-check. These are an example name and text, not a key or a test performed here. If a Next.js application reads this variable directly through process.env.NEXT_PUBLIC_RELEASE_LABEL, it can display the label in the intended place in the interface after a new build. This check only confirms that the public setting was passed through.

A private key is checked differently. Do not output its value, a portion of it, its length or the entire process.env. Do not create a public URL that returns the variable's contents. First, check only whether the setting is “present / absent” on the server, then separately check the application function that uses the service. The presence of a setting does not prove the key is valid or has the required permissions.

You can record the results without secrets:

• the project, environment and branch match those selected during configuration;
• you are checking the URL of a new deployment created after saving the variable;
• the build has finished, and the required application function has run on safe test data;
• the secret is not exposed in the browser, API responses, logs or conversations.

If the function makes a payment, sends a message or performs another action with consequences, use the service's designated test mode. Checking the configuration does not, by itself, authorize a real operation.

What to check if the value is still undefined#

undefined means no value was obtained at that point of access. Work through the name, environment and version in order, without changing all the settings at once.

Once you have checked the name, environment and new version, an error in the function still does not prove the variable caused it. Investigate the specific server-side code error without publishing diagnostic data containing secrets. This guide does not promise to resolve every HTTP 500 response.

Moving to your own server requires a different procedure: see the guide to deploying a project with Coolify. Vercel's button names and configuration steps do not apply to it.

Go to Ailoot.