@nendlabs/nenv

A flexible library for loading and parsing environment variables in Node.js applications. It uses the dotenv package to load environment variables from a .env file and provides various parsers to handle different data types. Additionally, it includes utilities to get common environment descriptors like the operating system, Node.js version, and deployment environments (e.g., Vercel, Cloudflare).

Installation

Install the package via npm:

npm install @nendlabs/nenv

Usage

Loading Environment Variables

First, load the environment variables from your .env file:

import { nenv } from '@nendlabs/nenv';

nenv.load();

Parsing Environment Variables

String

Parse an environment variable as a string:

const apiUrl = nenv.str`API_URL`;
console.log(apiUrl); // Outputs the value of API_URL

Number

Parse an environment variable as a number:

const port = nenv.num`PORT`;
console.log(port); // Outputs the value of PORT as a number

Boolean

Parse an environment variable as a boolean:

const isFeatureEnabled = nenv.bool`FEATURE_ENABLED`;
console.log(isFeatureEnabled); // Outputs the value of FEATURE_ENABLED as a boolean

Array

Parse an environment variable as an array (comma-separated values):

const supportedLocales = nenv.array`SUPPORTED_LOCALES`;
console.log(supportedLocales); // Outputs the value of SUPPORTED_LOCALES as an array

With custom delimiter

const supportedLocales = nenv.array('SUPPORTED_LOCALES', '.');
console.log(supportedLocales); // Outputs the value of SUPPORTED_LOCALES as an array

JSON

Parse an environment variable as a JSON object:

const config = nenv.json`CONFIG`;
console.log(config); // Outputs the value of CONFIG as a JSON object

With zod Schema

import { nenv } from '@nendlabs/nenv';
import { z } from 'zod';

nenv.load();

const configSchema = z.object({
  key: z.string(),
  value: z.number(),
});

const config = nenv.json('CONFIG', configSchema);
console.log(config); // Outputs the validated JSON object

Date

Parse an environment variable as a date:

const launchDate = nenv.date`LAUNCH_DATE`;
console.log(launchDate); // Outputs the value of LAUNCH_DATE as a Date object

Getting Environment Descriptors

You can get common environment descriptors such as the operating system, Node.js version, and deployment environments:

const env = nenv.environment;

console.log('Node version:', env.node.version);
console.log('Running in Docker:', env.is.docker);
console.log('OS type:', env.os.type);
console.log('OS platform:', env.os.platform);
console.log('OS architecture:', env.os.arch);
console.log('CPUs:', env.os.cpus);
console.log('Total memory:', env.os.totalMemory);
console.log('IP address:', env.ip);

Examples

Example 1: Basic Usage

import { nenv } from '@nendlabs/nenv';

nenv.load();

const apiUrl = nenv.str`API_URL`;
const port = nenv.num`PORT`;
const isFeatureEnabled = nenv.bool`FEATURE_ENABLED`;

console.log(`API URL: ${apiUrl}`);
console.log(`Port: ${port}`);
console.log(`Feature Enabled: ${isFeatureEnabled}`);

Example 2: Handling Different Environments

import { nenv } from '@nendlabs/nenv';

nenv.load();

const env = nenv.environment;

if (env.is.production) {
  console.log('Running in production mode');
} else if (env.is.vercel) {
  console.log('Running on Vercel');
} else if (env.is.cloudflare) {
  console.log('Running on Cloudflare');
}

console.log('Node version:', env.node.version);
console.log('OS type:', env.os.type);
console.log('OS platform:', env.os.platform);
console.log('OS architecture:', env.os.arch);

Example 3: Advanced Parsing

import { nenv } from '@nendlabs/nenv';

nenv.load();

const supportedLocales = nenv.array`SUPPORTED_LOCALES`;
const config = nenv.json`CONFIG`;
const launchDate = nenv.date`LAUNCH_DATE`;

console.log('Supported Locales:', supportedLocales);
console.log('Config:', config);
console.log('Launch Date:', launchDate);

Use Cases

• Loading Environment Variables: Easily load and manage environment variables from a .env file.
• Type-Safe Parsing: Parse environment variables as different types (string, number, boolean, array, JSON, date) with type safety.
• Environment Descriptors: Get useful information about the runtime environment, such as OS details, Node.js version, and deployment environment.
• Configuration Management: Manage complex configurations using JSON environment variables.