vite-plugin-dotenvx

A Vite plugin to seamlessly integrate with dotenvx.

Features

• 🔐 Decryption Automatically decrypts encrypted .env files using dotenvx
• 🌍 Multi Env Supports multiple .env files & environment-specific configurations
• 🔄 Variables Supports variable expansion & command substitution in your .env files
• 🏗️ Build-Ready Works in both development & build modes with configurable options
• 📝 Dev Tools Auto-generates .env.example files & updates .gitignore automatically
• 🔌 Client Access Selectively expose environment variables to client-side code
• 🛡️ Security Configurable error handling with strict mode & flexible configuration

Install

npm install -D vite-plugin-dotenvx
# or
yarn add -D vite-plugin-dotenvx
# or
pnpm add -D vite-plugin-dotenvx
# or
bun add -D vite-plugin-dotenvx

Get Started

// vite.config.ts
import { defineConfig } from 'vite'
import Dotenvx from 'vite-plugin-dotenvx'

export default defineConfig({
  plugins: [
    Dotenvx({
      enabled: true, // default: true
      verbose: true, // default: false, enables detailed logging
      path: ['.env', '.env.local'], // default: ['.env']
      envKeysFile: '.env.keys', // default: '.env.keys'
      overload: false, // default: false
      convention: 'nextjs', // optional, load envs using a convention like Next.js
    })
  ]
})

Advanced Configuration

Here's an example with all available options:

// vite.config.ts
import { defineConfig } from 'vite'
import Dotenvx from 'vite-plugin-dotenvx'

export default defineConfig({
  plugins: [
    Dotenvx({
      // Basic options
      enabled: true,
      verbose: true,
      path: ['.env.local', '.env'],
      envKeysFile: '.env.keys',
      overload: false,
      convention: 'nextjs',

      // Advanced options
      applyInBuild: true, // Apply in build mode as well
      strict: true, // Exit with code 1 if any errors are encountered
      ignore: ['MISSING_ENV_FILE'], // Ignore specific errors
      generateExample: true, // Auto-generate .env.example file
      updateGitignore: true, // Auto-add .env.keys to .gitignore
      exposeToClient: ['VITE_.*', 'PUBLIC_.*'], // Expose specific variables to client
    })
  ]
})

Usage with dotenvx

This plugin integrates with dotenvx, a better dotenv from the creator of dotenv. It automatically decrypts encrypted .env files during development.

Encrypting your .env files

Given you installed vite-plugin-dotenvx, you may run the following command to encrypt your .env files:

bunx dotenvx encrypt

This will encrypt your .env file and create a .env.keys file with the encryption keys.

Using encrypted .env files

The plugin will automatically decrypt your encrypted .env files during development. No additional configuration is needed.

VS Code Extension

For the best development experience, we recommend installing the dotenvx VS Code extension. This extension provides syntax highlighting, encryption/decryption features, and other helpful tools directly in your editor.

# Install from VS Code marketplace
code --install-extension dotenv.dotenvx-vscode

Or search for "dotenvx" in the VS Code extensions marketplace.

For more information on dotenvx, visit dotenvx.com.

Options

Option	Type	Default	Description
enabled	boolean	true	Enable or disable the plugin
verbose	boolean	false	Enable verbose logging
path	string | string[]	['.env']	Path to .env file(s)
envKeysFile	string	'.env.keys'	Path to .env.keys file
overload	boolean	false	Override existing env variables
convention	string	undefined	Load a .env convention (e.g., 'nextjs')
applyInBuild	boolean	false	Apply the plugin in build mode as well
strict	boolean	false	Exit with code 1 if any errors are encountered
ignore	string[]	undefined	Ignore specific errors
generateExample	boolean	false	Auto-generate .env.example file
updateGitignore	boolean	false	Auto-add .env.keys to .gitignore
exposeToClient	string[]	[]	Expose specific environment variables to the client

Testing

bun test

Changelog

Please see our releases page for more information on what has changed recently.

Contributing

Please review the Contributing Guide for details.

Community

For help, discussion about best practices, or any other conversation that would benefit from being searchable:

Discussions on GitHub

For casual chit-chat with others using this package:

Join the Stacks Discord Server

Postcardware

“Software that is free, but hopes for a postcard.” We love receiving postcards from around the world showing where vite-plugin-dotenvx is being used! We showcase them on our website too.

Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, United States 🌎

Sponsors

We would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.

• JetBrains
• The Solana Foundation

Credits

• Mot for creating dotenv & dotenvx
• Chris Breuer
• All Contributors

License

The MIT License (MIT). Please see LICENSE for more information.

Made with 💙