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. 🔥 🚀 👷

npm package npm package downloads

Supports:

Next.js Vite Esbuild Webpack Astro Rollup Rolldown Rspack Farm

## Table of Contents * [📚 Table of Contents](#-table-of-contents) * [🔥 Features](#features) * [📦 Installation](installation) * [🚀 Basic Usage](#basic-usage) * [1. Configuration](#configuration) * [1.a Schema Validation](#schema-validation) `👍 Recommended` * [1.b Intellisense with TypeScript](#intellisense-with-typescript) `👍 Recommended` * [1.c Client/Server Environment](#clientserver-environment) `👍 Recommended` for SSR, SSG, and other client/server environment. * [2. Accessing Environment Variables](#accessing-environment-variables) * [3. Done](#) * [💡 Acknowledgements](#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: ```bash 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
```ts // 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
```ts // vite.config.ts import Environment from 'unplugin-flag/vite' export default defineConfig({ plugins: [ Environment('PREFIX_APP'), ], }) ```
⇡ Back to top

Farm
```ts // farm.config.ts import Environment from 'unplugin-flag/farm' export default defineconfig({ plugins: [ Environment('PREFIX_APP'), ], }) ```
⇡ Back to top

Rspack
```ts // rspack.config.js module.exports = { /* ... */ plugins: [ require('unplugin-flag/rspack')('PREFIX_APP') ] } ```
⇡ Back to top

Rollup
```ts // rollup.config.js import Environment from 'unplugin-flag/rollup' export default { plugins: [ Environment('PREFIX_APP'), ], } ```
⇡ Back to top

Rolldown
```ts // rolldown.config.js import Environment from 'unplugin-flag/rolldown' export default { plugins: [ Environment('PREFIX_APP'), ], } ```
⇡ Back to top

Webpack
```ts // webpack.config.js module.exports = { /* ... */ plugins: [ require('unplugin-flag/webpack')("PREFIX_APP") ] } ```
⇡ Back to top

Esbuild
```ts // esbuild.config.js import { build } from 'esbuild' import Environment from 'unplugin-flag/esbuild' build({ plugins: [Environment('PREFIX_APP')], }) ```
⇡ Back to top

Astro
```ts // 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](https://github.com/colinhacks/zod_) for validating environment variables. This automatically creates a virtual module with types. ```ts 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`: ```json { "compilerOptions": { "types": ["unplugin-flag/client"] } } ```
⇡ Back to top
### Accessing Environment Variables You can access environment variables from the virtual module `@env`: ```typescript import { env } from '@env' console.log(env.PREFIX_APP_NAME) ``` If you want to customize the module name, use the `moduleEnvName` option: ```typescript // 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: ```ts 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. ```ts 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 ```ts // 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](https://github.com/motdotla/dotenv) * [t3-env](https://github.com/t3-oss/t3-env) * [vite-plugin-environment](https://github.com/ElMassimo/vite-plugin-environment)
⇡ Back to top