Skip to main content

Environment Variables

Environment variables are a key part of modern web development. They allow you to store sensitive or configuration-specific information outside your codebase, keeping it secure and adaptable to different environments. In Vite, managing environment variables is simple and efficient, enabling you to customize your project based on the environment (development, production, etc.).

In this guide, we’ll explain how to define and use environment variables in .env files, with practical examples, such as using API URLs in your project.

1. Defining Environment Variables in .env Files​

Vite supports environment variables defined in .env files, which can be loaded automatically based on the environment (e.g., development, production). These variables can be accessed within your project and used to customize the build or runtime behavior.

How to Create .env Files​

To start using environment variables in Vite, you need to create one or more .env files in the root of your project. You can create:

  • .env – Default file for all environments.
  • .env.local – Overrides .env values, ignored by version control.
  • .env.development, .env.production – Environment-specific files.

Example File Structure​

project/
├── .env
├── .env.local
├── .env.development
├── .env.production
├── src/
├── index.html
├── vite.config.js
└── package.json

2. Defining Variables in .env Files​

In the .env files, environment variables are defined using the format VITE_ followed by the variable name. Vite automatically exposes all variables starting with VITE_ to your application.

Example .env File​

# .env file
VITE_API_URL=https://api.example.com
VITE_APP_NAME=My Vite App
VITE_APP_VERSION=1.0.0
  • VITE_API_URL: The URL for your API server.
  • VITE_APP_NAME: The name of your application.
  • VITE_APP_VERSION: The version of your app.

In the case of environment-specific files (e.g., .env.development or .env.production), you can override or add specific variables for that environment.

# .env.production file
VITE_API_URL=https://api.production.com
VITE_APP_NAME=My Vite App (Production)

3. Accessing Environment Variables in Your Code​

Once the variables are defined, you can access them in your application by using import.meta.env. This object contains all the variables you defined with the VITE_ prefix.

Example of Using Environment Variables in Your Code​

// src/main.js
console.log('App Name:', import.meta.env.VITE_APP_NAME);
console.log('API URL:', import.meta.env.VITE_API_URL);
console.log('App Version:', import.meta.env.VITE_APP_VERSION);

This will output:

App Name: My Vite App
API URL: https://api.example.com
App Version: 1.0.0

Example: Using API URLs​

You might need to set a different API URL depending on the environment (development, production, etc.). Here’s how to handle it:

In your .env file:​

# .env
VITE_API_URL=https://api.example.com

In .env.production (for production-specific settings):​

# .env.production
VITE_API_URL=https://api.production.com

In your code, you can use the appropriate API URL:​

// src/api.js
const apiUrl = import.meta.env.VITE_API_URL;

async function fetchData() {
  const response = await fetch(`${apiUrl}/data`);
  const data = await response.json();
  return data;
}

fetchData().then(data => console.log(data));

In development, https://api.example.com will be used, and in production, https://api.production.com will be used, based on the environment file.

4. Using .env.local for Sensitive Information​

If you need to store sensitive information such as API keys or authentication tokens, you should use .env.local to keep them out of version control (i.e., Git). The .env.local file will never be committed to the repository if you have it listed in your .gitignore file.

Example .env.local File​

# .env.local
VITE_API_KEY=your-api-key-here

This file can store secret credentials or keys for third-party services, and will only be available locally for development.

5. Environment-Specific Variables​

Vite allows you to define different variables for different environments by creating environment-specific files like .env.development or .env.production.

Example: .env.development​

# .env.development
VITE_API_URL=https://dev.api.example.com

Example: .env.production​

# .env.production
VITE_API_URL=https://api.example.com

When you run Vite in a specific environment (e.g., using npm run build for production), Vite will automatically load the correct .env file based on the environment.

6. Using Environment Variables for Configuration​

In larger projects, you may want to use environment variables for specific configurations, such as enabling/disabling features or setting different endpoints for API requests. Here are some common examples:

Example: Enabling Debug Mode​

You can enable or disable debug mode in your app using environment variables.

# .env
VITE_DEBUG=true

Then, in your code:

if (import.meta.env.VITE_DEBUG === 'true') {
  console.log('Debug mode is enabled');
}

Example: Changing the App’s Theme​

You can also use environment variables to toggle different themes or UI modes.

# .env.production
VITE_THEME=dark

In your code:

const theme = import.meta.env.VITE_THEME;
if (theme === 'dark') {
  document.body.classList.add('dark-theme');
}

7. Conclusion​

Environment variables are a powerful way to configure your Vite project in different environments and manage sensitive information securely. By defining variables in .env files and using the import.meta.env object, you can keep your code flexible, clean, and environment-specific.

  • Use .env for general settings.
  • Store sensitive data in .env.local (and ensure it's ignored in version control).
  • Create environment-specific .env.development, .env.production files to override settings.

By properly managing environment variables, you can ensure that your project remains adaptable, secure, and easy to configure across different stages of development.