unplugin-environment
v1.3.0
Published
A plugin for loading enviroment variables safely with schema validation, simple with virtual module, type-safe with intellisense, and better DX π₯ π π·. Support with Next.js, Vite, Webpack, Rollup, Rspack, Farm, and more.
Downloads
68
Maintainers
Readme
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.
- 1.a Schema Validation
- 2. Accessing Environment Variables
- 3. Done
- 1. Configuration
- π‘ 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
Basic Usage
Configuration
// next.config.mjs
import Environment from 'unplugin-environment/webpack'
const nextConfig = {
webpack(config){
config.plugins.push(Environment('PREFIX_APP'))
return config
},
}
export default nextConfig
// vite.config.ts
import Environment from 'unplugin-environment/vite'
export default defineConfig({
plugins: [
Environment('PREFIX_APP'),
],
})
// farm.config.ts
import Environment from 'unplugin-environment/farm'
export default defineconfig({
plugins: [
Environment('PREFIX_APP'),
],
})
// rspack.config.js
module.exports = {
/* ... */
plugins: [
require('unplugin-environment/rspack')('PREFIX_APP')
]
}
// rollup.config.js
import Environment from 'unplugin-environment/rollup'
export default {
plugins: [
Environment('PREFIX_APP'),
],
}
// rolldown.config.js
import Environment from 'unplugin-environment/rolldown'
export default {
plugins: [
Environment('PREFIX_APP'),
],
}
// webpack.config.js
module.exports = {
/* ... */
plugins: [
require('unplugin-environment/webpack')("PREFIX_APP")
]
}
// esbuild.config.js
import { build } from 'esbuild'
import Environment from 'unplugin-environment/esbuild'
build({
plugins: [Environment('PREFIX_APP')],
})
// astro.config.mjs
import { defineConfig } from 'astro/config'
import Environment from 'unplugin-environment/astro'
build({
plugins: [Environment('PREFIX_APP')],
})
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),
},
})
Intellisense with TypeScript
To enable Intellisense for environment variables, add the following to your tsconfig.json
:
{
"compilerOptions": {
"types": ["unplugin-environment/client"]
}
}
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)
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