unplugin-environment

A powerful plugin for safely loading environment variables with schema validation. Simple to use with virtual modules, type-safe with TypeScript support, and designed for a better developer experience. 🔥 🚀 👷

Supports:

Table of Contents

• 📚 Table of Contents
• 🔥 Features
• 📦 Installation
• 🚀 Basic Usage
  • 1. Configuration
    • 1.a Schema Validation 👍 Recommended
    • 1.b Intellisense with TypeScript 👍 Recommended
    • 1.c Client/Server Environment 👍 Recommended for SSR, SSG, and other client/server environment.
  • 2. Accessing Environment Variables
  • 3. Done
• 💡 Acknowledgements

Features

• 🔐 Secure: Load environment variables safely with schema validation to avoid errors and prevent exposing sensitive information.
• ✍️ Type-Safe: Automatically inferred types based on your schema configuration.
• ⚡ Developer-Friendly: Lightweight and simple API for managing environment variables with seamless TypeScript integration.

Installation

Install via your preferred package manager:

npm install unplugin-environment       # npm

yarn add unplugin-environment          # yarn

bun add unplugin-environment           # bun

pnpm add unplugin-environment          # pnpm

⇡ Back to top

Basic Usage

Configuration

Next.js

// next.config.mjs
import Environment from 'unplugin-environment/webpack'

const nextConfig = {
    webpack(config){
        config.plugins.push(Environment('PREFIX_APP'))
        return config
    },
}

export default nextConfig

⇡ Back to top

Vite

// vite.config.ts
import Environment from 'unplugin-environment/vite'

export default defineConfig({
  plugins: [
    Environment('PREFIX_APP'),
  ],
})

⇡ Back to top

Farm

// farm.config.ts
import Environment from 'unplugin-environment/farm'

export default defineconfig({
  plugins: [
    Environment('PREFIX_APP'),
  ],
})

⇡ Back to top

Rspack

// rspack.config.js
module.exports = {
  /* ... */
  plugins: [
    require('unplugin-environment/rspack')('PREFIX_APP')
  ]
}

⇡ Back to top

Rollup

// rollup.config.js
import Environment from 'unplugin-environment/rollup'

export default {
  plugins: [
    Environment('PREFIX_APP'),
  ],
}

⇡ Back to top

Rolldown

// rolldown.config.js
import Environment from 'unplugin-environment/rolldown'

export default {
  plugins: [
    Environment('PREFIX_APP'),
  ],
}

⇡ Back to top

Webpack

// webpack.config.js
module.exports = {
  /* ... */
  plugins: [
    require('unplugin-environment/webpack')("PREFIX_APP")
  ]
}

⇡ Back to top

Esbuild

// esbuild.config.js
import { build } from 'esbuild'
import Environment from 'unplugin-environment/esbuild'

build({
  plugins: [Environment('PREFIX_APP')],
})

⇡ Back to top

Astro

// astro.config.mjs
import { defineConfig } from 'astro/config'
import Environment from 'unplugin-environment/astro'

build({
  plugins: [Environment('PREFIX_APP')],
})

⇡ Back to top

Schema Validation

Use the schema option with zod for validating environment variables. This automatically creates a virtual module with types.

Environment({
    match: 'PREFIX_', // or ['PREFIX_', 'PREFIX2_']
    schema: {
        PREFIX_APP_NAME: z.string().min(1).default('My App'),
        PREFIX_APP_PORT: z.coerce.number().min(1).default(3000),
    },
})

⇡ Back to top

Intellisense with TypeScript

To enable Intellisense for environment variables, add the following to your tsconfig.json:

{
    "compilerOptions": {
        "types": ["unplugin-environment/client"]
    }
}

⇡ Back to top

Accessing Environment Variables

You can access environment variables from the virtual module @env:

import { env } from '@env'

console.log(env.PREFIX_APP_NAME)

If you want to customize the module name, use the moduleEnvName option:

// in plugin configuration
Environment({
    match: 'PREFIX_', // or ['PREFIX_', 'PREFIX2_']
    schema: ...,
    moduleEnvName: 'MYENV',
})


// you can access it from `MYENV` module
import { env } from 'MYENV'

console.log(env.PREFIX_APP_NAME)

⇡ Back to top

Client/Server Environment

To handle environment variables separately for client and server, use the client and server options. This allows for precise control over which variables are accessible in different environments.

Note

When using the client and server options, you cannot access environment variables through the @env module. Instead, use @env/client for client-side variables and @env/server for server-side variables by default.

Example configuration:

Environment({
    client: {
        match: 'CLIENT_',
        schema: {
            CLIENT_APP_NAME: z.string().min(1).default('My App'),
        },
    },
    server: {
        match: 'SERVER_',
        schema: {
            SERVER_APP_DB_URL: z.string().min(1).default('postgres://localhost:5432/mydb'),
        }
    },
})

If you'd like to change the default module names @env/client and @env/server, you can use the optional moduleEnvName key to define a custom module name for accessing the environment variables.

Caution

When customizing moduleEnvName for client and server, ensure the module names are different. Using the same name for both client and server can cause conflicts and unpredictable behavior.

Environment({
    client: {
        match: 'CLIENT_',
        schema: {
            CLIENT_APP_NAME: z.string().min(1).default('My App'),
        },
        moduleEnvName: '@myenv/client', // Optional: Customize the client module name
    },
    server: {
        match: 'SERVER_',
        schema: {
            SERVER_APP_DB_URL: z.string().min(1).default('postgres://localhost:5432/mydb'),
        },
        moduleEnvName: '@myenv/server', // Optional: Customize the server module name
    },
})

Accessing Client/Server Environment

// client environment
import { env } from '@env/client'

env.CLIENT_APP_NAME // typed with string

// server environment
import { env } from '@env/server'

env.SERVER_APP_DB_URL // typed with string

⇡ Back to top

Acknowledgements

• dotenv
• t3-env
• vite-plugin-environment

---

⇡ Back to top