Understanding Environment Variables in Vite: Why VITE_ Prefix is Important

Introduction

When developing a web application with Vite, I encountered an issue where the environment variables I had set up were showing as undefined in the client-side source code.
The following is a summary of the causes and solutions to this problem.

.env.local:

API_KEY=your_api_key

example.tsx:

const API_KEY = import.meta.env.API_KEY;
console.log('API KEY: ', API_KEY);

▽Console

Cause and Solution

The issue was that the environment variables in Vite project required a VITE_ prefix.

▽Before Fix (.env.local:)

API_KEY=your_api_key

↓
▽After Fix (.env.local file:)　←It works😃

VITE_API_KEY=your_api_key

Why is the VITE_ Prefix Necessary?

So why does Vite require environment variables to have the VITE_ prefix? There are two main reasons:

1. Security

The official documentation explains it as follows:

To prevent environment variables from being accidentally exposed to the client, only variables that start with VITE_ are exposed in the processed code by Vite. For example, in the following environment variables:
.env file:

VITE_SOME_KEY=123
DB_PASSWORD=foobar

Only VITE_SOME_KEY will be exposed to the client source code as import.meta.env.VITE_SOME_KEY, while DB_PASSWORD will not be exposed.

console.log(import.meta.env.VITE_SOME_KEY); // "123"
console.log(import.meta.env.DB_PASSWORD); // undefined

Official documentation link: Environment Variables

Vite strictly manages the environment variables that can be accessed on the client side by default. If all environment variables were exposed to the client side, it could pose a significant security risk. In particular, it’s crucial to prevent sensitive server-side variables, such as API keys or database credentials, from leaking to the client.

Therefore, Vite ensures that only variables with the VITE_ prefix are accessible on the client side, preventing the unintended exposure of sensitive information.

2. Clarity

The VITE_ prefix indicates which environment variables are intended for client-side use. This improves code readability and helps prevent the accidental use of variables that should remain private, particularly in team development environments.

Supplement

1. What Are Environment Variables?

Let's briefly review what environment variables are. Environment variables are variables used to provide configuration values that an application needs to function. By using environment variables, you can easily switch between different environments (e.g., development, testing, production) without modifying your application’s code.

2. Setting Up Environment Variables in Vite

To use environment variables in Vite, you need to create a .env file in the root directory of your project and define your variables there. As mentioned earlier, it’s crucial to prefix your variable names with VITE_.

For example, to set an API key for an external service, your .env file should look like this:

Example:
(.env file)

VITE_API_KEY=your_api_key

(example.tsx)

const apiKey = import.meta.env.VITE_API_KEY;

3. TypeScript Auto-Completion

If you tend to forget details as I do, there’s a way to improve your code's accuracy by using type definitions for import.meta.env. This provides auto-completion in TypeScript.

To set this up, simply create a vite-env.d.ts file in the src directory and define your environment variables within ImportMetaEnv.

Official Documentation: TypeScript Auto-Completion

Conclusion

When setting environment variables in Vite, it’s essential to prefix the variable names with VITE_. This practice not only enhances security but also optimizes your application's performance.