vite-plugin-meta-env

1.0.2 verified Mon Apr 27 auth: no javascript

Vite plugin to expose dynamic or non-prefixed environment variables via import.meta.env. Current stable version 1.0.2 (Aug 2023). Allows defining variables not starting with VITE_ (the default envPrefix) or process.env. Configurable to attach variables to import.meta.env or process.env. Different from standard Vite env handling by enabling arbitrary variable names without prefix restrictions. Active maintenance with TypeScript types included. Minimal API with one function call.

Common errors

error TypeError: VitePluginMetaEnv is not a function ↓

cause Named import instead of default import (e.g., import { VitePluginMetaEnv } from 'vite-plugin-meta-env').

fix

Change to default import: import VitePluginMetaEnv from 'vite-plugin-meta-env'

error Cannot read properties of undefined (reading 'APP_VERSION') ↓

cause Variable not exposed because plugin not configured, or second argument misconfigured, or accessing before build.

fix

Ensure plugin is added to Vite plugins array with correct arguments. Access via import.meta.env only after build.

error Module '"vite-plugin-meta-env"' has no exported member 'VitePluginMetaEnv'. Did you mean to use 'import VitePluginMetaEnv from "vite-plugin-meta-env"' instead? ↓

cause Using named import when the package exports a default.

fix

Use default import syntax as shown in the docs.

Warnings

gotcha Variables defined with this plugin are statically embedded at build time. Changes to .env files or runtime environment after build will NOT be reflected. ↓

fix Rebuild the project after changing environment variable values. For dynamic runtime variables, use process.env with appropriate server-side handling.

gotcha If using TypeScript, you must manually extend ImportMetaEnv interface to get type safety and IntelliSense for custom variables. ↓

fix Add declarations in a .d.ts file per Vite docs: https://vitejs.dev/guide/env-and-mode.html#intellisense

gotcha The second parameter (defineOn) is not validated; passing an invalid value will silently fail (variables not exposed). ↓

fix Only use 'import.meta.env' or 'process.env' as the second argument. Check that variable is accessible after configuration.

gotcha This plugin only works during the Vite build process. It does not handle SSR or server-side runtime variables. ↓

fix For SSR, use Vite's define option or platform-specific runtime config. The plugin is intended for client-side builds only.

Install

npm install vite-plugin-meta-env

yarn add vite-plugin-meta-env

pnpm add vite-plugin-meta-env

Imports

VitePluginMetaEnv

wrong

const { VitePluginMetaEnv } = require('vite-plugin-meta-env')

correct

import VitePluginMetaEnv from 'vite-plugin-meta-env'

Plugin uses ESM default export; named import and CommonJS require will fail

Quickstart

Shows how to define custom env variables without VITE_ prefix and access them via import.meta.env.

// vite.config.ts
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import VitePluginMetaEnv from 'vite-plugin-meta-env';

export default defineConfig({
  plugins: [
    vue(),
    VitePluginMetaEnv({
      APP_VERSION: '1.0.0',
      APP_BUILD_TIME: new Date().toISOString()
    }, 'import.meta.env')
  ]
});

// In your code:
console.log(import.meta.env.APP_VERSION); // '1.0.0'