NVIRON

Nviron is a lightweight, type-safe e[nviron]ment variable management library built for modern JavaScript and TypeScript projects. It helps you define, validate, and safely access environment variables using Zod.

Explore the docs »
Report Bug · Request Feature

About The Project

Nviron simplifies how you work with environment variables in modern JavaScript and TypeScript projects. Instead of manually checking process.env or writing repetitive validation logic, nviron provides a declarative, type-safe, and Zod powered approach that ensures your app runs with confidence no missing or invalid envs.

Built With

🚀 Getting Started

To start using nviron, simply install it in your Node.js or TypeScript project. It’s lightweight, type-safe, and works out of the box with Zod

Install nviron and optionally zod (only if you need full Zod functionality outside of nviron):

Using pnpm

pnpm add nviron

or npm

npm install nviron

or yarn

yarn add nviron

nviron re-exports Zod as z, so for defining and validating environment variables you can do:

import { defineEnv, z } from "nviron";

const env = defineEnv({
  PORT: z.coerce.number(),
  DATABASE_URL: z.string().url(),
});

Usage

Here’s a quick example to get started:

import { defineEnv, z } from "nviron";

// Default usage (process.env)
const env = defineEnv({
  PORT: z.coerce.number(),
  DATABASE_URL: z.string().url(),
  NODE_ENV: z.enum(["development", "production"]),
});

console.log(env.PORT); // Safely typed & validated

// Using a custom source and prefix (e.g., Vite)
const envVite = defineEnv(
  {
    PORT: z.coerce.number(),
    DATABASE_URL: z.string().url(),
    NODE_ENV: z.enum(["development", "production"]),
  },
  {
    source: import.meta.env, // or any custom object
    prefix: "VITE_",
  },
);

console.log(envVite.PORT); // Typed & validated

Optional Config

defineEnv(schema, config?) accepts an optional configuration object:

• source?: EnvData — Environment source object (defaults to process.env).
• prefix?: string — Prefix to strip from environment variable names before validation (useful for Vite or custom setups).

⚠️ Prefixed variables (like VITE_PORT) are automatically normalized to match your schema keys (PORT) before validation.

If any variable is missing or invalid, nviron will display a clear, color-coded error message and exit gracefully helping you catch issues early.

Example Output (when validation failure)

❌ Environment Variable Missing or Invalid

1 issue found in your environment configuration.

1. API_KEY → Invalid input: expected string, received undefined

💡 Check your .env file or environment variables before starting the server.

Types & Zod

nviron exports types to improve TypeScript experience:

• EnvConfig - config object shape
• EnvSchema - type for your environment schema
• ValidatedEnv - type of the validated environment object
• z - re-exported Zod for convenience

For more examples, detailed configuration options, please refer to the Documentation

🗺️ Roadmap

• Core nviron package
• Zod validation support
• Better error diagnostics & colored console output
• CLI tool
  • Environment file generation (.env.example creator)
  • Schema auto-generation from .env files

🤝 Contributing

Contributions are always welcome! 🎉 We believe open source grows stronger through collaboration whether it’s bug fixes, documentation improvements, typo or brand-new features.

If you’d like to contribute, please read our detailed CONTRIBUTING.md

Star History

Don’t forget to ⭐ star the repo if you find it helpful, it really means a lot!