unplugin-flag

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-flag       # npm

yarn add unplugin-flag          # yarn

bun add unplugin-flag           # bun

pnpm add unplugin-flag          # pnpm

⇡ Back to top

Basic Usage

Configuration

Next.js

// next.config.mjs
import Environment from 'unplugin-flag/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-flag/vite'

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

⇡ Back to top

Farm

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

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

⇡ Back to top

Rspack

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

⇡ Back to top

Rollup

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

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

⇡ Back to top

Rolldown

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

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

⇡ Back to top

Webpack

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

⇡ Back to top

Esbuild

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

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

⇡ Back to top

Astro

// astro.config.mjs
import { defineConfig } from 'astro/config'
import Environment from 'unplugin-flag/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-flag/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