Comprehensive Guide to Environment Variables in Vue.js: From Vue CLI to Vite

The Importance of Environment Variables in Vue.js Development

In modern frontend development, environment variables have become essential tools for managing application configuration. They not only help developers distinguish between different environments (such as development, testing, and production) but also effectively protect sensitive information by preventing hardcoded API keys, database connection strings, and other critical configurations in source code. The Vue.js ecosystem provides native support, making environment variable usage straightforward and efficient.

Vue CLI Environment Variable Configuration

For projects created with Vue CLI, environment variable configuration follows a clear set of rules. First, create a .env file in the project root directory, which serves as the primary storage location for environment variables. It's important to note that in Vue CLI 3 and later versions, only variables prefixed with VUE_APP_ are automatically loaded into the application.

Environment file loading follows specific priority rules:

.env                # loaded in all cases
.env.local          # loaded in all cases, ignored by git
.env.[mode]         # only loaded in specified mode
.env.[mode].local   # only loaded in specified mode, ignored by git

This layered loading mechanism allows developers to configure different environment variables for various development stages. For example, the development environment can use local API endpoints, while the production environment points to actual server addresses.

Practical Applications of Environment Variables

Accessing environment variables in Vue components is straightforward. Taking API endpoint configuration as an example, suppose we define in the .env file:

VUE_APP_API_BASE_URL=https://api.example.com
VUE_APP_API_VERSION=v1

In Vue components, these variables can be accessed through the process.env object:

export default {
  mounted() {
    const apiUrl = process.env.VUE_APP_API_BASE_URL
    const apiVersion = process.env.VUE_APP_API_VERSION
    console.log(`API endpoint: ${apiUrl}/${apiVersion}`)
    
    // Actual API call example
    fetch(`${apiUrl}/${apiVersion}/users`)
      .then(response => response.json())
      .then(data => {
        this.users = data
      })
  },
  data() {
    return {
      users: []
    }
  }
}

Vite Environment Variable Configuration

For Vue projects built with Vite, environment variable configuration differs slightly. Vite requires environment variables to be prefixed with VITE_ and accessed through the import.meta.env object. This design integrates environment variables more naturally within the module system.

Vite environment file example:

VITE_API_ENDPOINT=https://api.example.com
VITE_APP_TITLE=My Vue App

Usage in components:

const apiEndpoint = import.meta.env.VITE_API_ENDPOINT
const appTitle = import.meta.env.VITE_APP_TITLE

// Usage in Composition API
import { ref, onMounted } from 'vue'

export default {
  setup() {
    const data = ref(null)
    
    onMounted(async () => {
      const response = await fetch(`${import.meta.env.VITE_API_ENDPOINT}/data`)
      data.value = await response.json()
    })
    
    return { data }
  }
}

Environment Modes and Variable Management

Both Vue CLI and Vite support mode-based environment variable management. Common modes include:

• development - development mode, using .env.development or .env.development.local
• production - production mode, using .env.production or .env.production.local
• test - test mode, using .env.test or .env.test.local

This mode-based management makes it simple to use different configurations across various environments. For instance, the development environment can point to a local mock server, while the production environment points to actual cloud services.

Security Best Practices

While environment variables provide convenience in frontend development, developers must understand their security limitations. Frontend environment variables are directly embedded into the final JavaScript bundle during the build process, meaning they are visible to clients. Therefore, truly sensitive information such as database passwords or private API keys should never be stored in frontend environment variables.

Correct approach:

// Secure usage - only store non-sensitive configurations
VUE_APP_API_BASE_URL=https://api.example.com
VUE_APP_APP_NAME=My Application

// Insecure usage - avoid storing sensitive information in frontend
# VUE_APP_DATABASE_PASSWORD=secret123  // Don't do this!
# VUE_APP_STRIPE_SECRET_KEY=sk_test_...  // Don't do this!

Development Workflow Optimization

To ensure proper loading of environment variables, developers should follow these best practices:

1. Always restart the development server after modifying .env files
2. Ensure .env files are located in the project root directory, not within the src directory
3. Add .env files to .gitignore to prevent sensitive information from being committed to version control
4. Create .env.example files for team collaboration, documenting required environment variables

Team collaboration example:

# .env.example - shared configuration template for teams
VUE_APP_API_BASE_URL=your_api_base_url_here
VUE_APP_APP_NAME=your_app_name_here
VUE_APP_DEBUG_MODE=false

# Team members copy to .env and fill in actual values

Troubleshooting and Debugging

When environment variables aren't working properly, follow these troubleshooting steps:

// Simple method for debugging environment variables
export default {
  created() {
    // Check all available environment variables
    console.log('All environment variables:', process.env)
    
    // Check specific variables
    console.log('API base URL:', process.env.VUE_APP_API_BASE_URL)
    
    // Verify variable existence
    if (!process.env.VUE_APP_API_BASE_URL) {
      console.error('VUE_APP_API_BASE_URL environment variable not set')
    }
  }
}

Common issue solutions:

• Variables not loading: Check if variable prefixes are correct (Vue CLI uses VUE_APP_, Vite uses VITE_)
• Variable values undefined: Confirm the development server has been restarted
• Variables not effective after build: Check if build commands correctly specify environment modes

Advanced Configuration Techniques

For complex application scenarios, combine with TypeScript for better development experience:

// env.d.ts - environment variable type definitions
interface ImportMetaEnv {
  readonly VITE_API_BASE_URL: string
  readonly VITE_APP_TITLE: string
  readonly VITE_DEBUG_MODE: string
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

// Type-safe usage in components
const apiUrl: string = import.meta.env.VITE_API_BASE_URL

By properly configuring and using environment variables, Vue.js developers can build more robust, maintainable applications while ensuring efficient and secure development workflows.