tessl/npm-env-cmd

Executes a command using the environment variables in an env file

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

File Format Support

Name: tessl/npm-env-cmd
Author: tessl

Comprehensive support for multiple environment file formats including standard .env files, JSON configuration, JavaScript modules, TypeScript files, and multi-environment RC files. Each format provides specific advantages for different use cases.

Capabilities

Environment File Parsing

Core function for parsing individual environment files with automatic format detection.

/**
 * Gets the environment vars from an env file
 * @param envFilePath - Path to the environment file  
 * @returns Promise resolving to parsed environment variables
 */
function getEnvFileVars(envFilePath: string): Promise<Environment>;

Supported Extensions:

const IMPORT_HOOK_EXTENSIONS = [
  '.json',
  '.js',
  '.cjs', 
  '.mjs',
  '.ts',
  '.mts',
  '.cts',
  '.tsx',
];

RC File Parsing

Function for parsing multi-environment configuration files.

/**
 * Gets the env vars from the rc file and rc environments
 * @param options - RC file configuration with environments
 * @returns Promise resolving to merged environment variables
 */
function getRCFileVars(
  { environments, filePath }: { environments: string[], filePath: string },
): Promise<Environment>;

File Format Details

Standard .env Files

Traditional dotenv format with key=value pairs and comment support.

Format:

# This is a comment
NODE_ENV=development
API_URL=http://localhost:3000
DATABASE_URL=postgresql://user:pass@localhost/db

# Multiline values with quotes
PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIEvgIBADANBgkqhkiG9w0BAQ..."

# Variable references (processed with --recursive)
FULL_URL=$API_URL/api/v1

Features:

Comments with #
Quoted values for spaces and special characters
No export statements needed
Compatible with standard dotenv libraries

JSON Environment Files

JSON format for structured environment configuration.

Format (.env.json):

{
  "NODE_ENV": "development",
  "API_URL": "http://localhost:3000",
  "DATABASE_URL": "postgresql://user:pass@localhost/db",
  "PORT": "3000",
  "FEATURE_FLAGS": "{\"newUI\": true, \"beta\": false}"
}

Features:

Structured JSON format
All values must be strings
Proper JSON validation
No comments allowed

JavaScript Environment Files

JavaScript modules that export environment objects.

Format (.env.js, .env.mjs, .env.cjs):

// .env.js - ES Module
export default {
  NODE_ENV: 'development',
  API_URL: process.env.NODE_ENV === 'production' 
    ? 'https://api.production.com'
    : 'http://localhost:3000',
  BUILD_TIME: new Date().toISOString(),
  VERSION: require('./package.json').version
};

// .env.cjs - CommonJS  
module.exports = {
  NODE_ENV: 'development',
  API_URL: 'http://localhost:3000'
};

Features:

Dynamic value computation
Conditional logic based on environment
Access to Node.js APIs and modules
Can import other files and packages

TypeScript Environment Files

TypeScript modules with type safety for environment configuration.

Format (.env.ts, .env.mts, .env.cts):

interface EnvironmentConfig {
  NODE_ENV: 'development' | 'production' | 'test';
  API_URL: string;
  PORT: string;
  DATABASE_URL: string;
}

const config: EnvironmentConfig = {
  NODE_ENV: 'development',
  API_URL: 'http://localhost:3000',
  PORT: '3000',
  DATABASE_URL: 'postgresql://localhost/myapp_dev'
};

export default config;

Features:

Full TypeScript type checking
Interface definitions for environment structure
Compile-time validation
IDE autocompletion and error checking
Requires tsx loader for execution

RC Configuration Files

Multi-environment configuration files supporting environment-specific settings.

Format (.env-cmdrc, .env-cmdrc.json):

{
  "development": {
    "NODE_ENV": "development",
    "API_URL": "http://localhost:3000",
    "DEBUG": "true"
  },
  "staging": {
    "NODE_ENV": "staging", 
    "API_URL": "https://api-staging.example.com",
    "DEBUG": "false"
  },
  "production": {
    "NODE_ENV": "production",
    "API_URL": "https://api.example.com",
    "DEBUG": "false"
  }
}

JavaScript RC Format (.env-cmdrc.js):

const environments = {
  development: {
    NODE_ENV: 'development',
    API_URL: 'http://localhost:3000'
  },
  production: {
    NODE_ENV: 'production',
    API_URL: 'https://api.example.com'
  }
};

export default environments;

Features:

Multiple environments in single file
Environment inheritance and merging
Shared configuration patterns
Support for JSON and JavaScript formats

File Loading Process

Format Detection

Files are processed based on their extension:

const ext = extname(absolutePath).toLowerCase();

if (IMPORT_HOOK_EXTENSIONS.includes(ext)) {
  // Dynamic import for JS/TS/JSON files
  const res = await import(pathToFileURL(absolutePath).href);
  return res.default || res;
} else {
  // Parse as .env format
  return parseEnvFile(absolutePath);
}

Import Handling

Different import strategies based on file type:

JSON Files:

const attributeTypes = ext === '.json' 
  ? { with: { type: 'json' } } 
  : {};
const res = await import(pathToFileURL(absolutePath).href, attributeTypes);

TypeScript Files:

if (/tsx?$/.test(ext)) {
  checkIfTypescriptSupported(); // Validates tsx loader availability
}

Module Resolution:

// Handle both default and named exports
const env = res.default || res;

// Support for promise-returning modules
if (isPromise(env)) {
  return await env;
}

Error Handling

File-Specific Errors

PathError: File not found or inaccessible

if (!existsSync(absolutePath)) {
  const pathError = new Error(`Invalid env file path (${envFilePath}).`);
  pathError.name = 'PathError';
  throw pathError;
}

ParseError: File parsing failures

try {
  const parsedVars = parseEnvFormat(content);
  return parsedVars;
} catch (e) {
  const parseError = new Error(`Failed to parse env file: ${e.message}`);
  parseError.name = 'ParseError';
  throw parseError;
}

LoaderError: Module loading failures

function isLoaderError(error: unknown): error is Error {
  return (
    error instanceof Error &&
    'code' in error &&
    error.code === 'ERR_UNKNOWN_FILE_EXTENSION'
  );
}

RC File Environment Errors

EnvironmentError: Requested environment not found in RC file

const envError = new Error(`Failed to find environment "${environment}" in RC file`);
envError.name = 'EnvironmentError';
throw envError;

TypeScript Loader Support

For TypeScript file support, env-cmd checks for tsx loader availability:

/**
 * Check if TypeScript is supported in the current environment
 * @throws Error if TypeScript files cannot be loaded
 */
function checkIfTypescriptSupported(): void;

Loader Detection:

Checks for tsx loader in module resolution
Validates TypeScript compilation support
Provides helpful error messages for missing loaders

Low-Level Parsing Functions

Direct parsing functions for working with environment file content at a granular level.

/**
 * Parse out all env vars from a given env file string and return an object
 * @param envFileString - Raw environment file content
 * @returns Parsed environment variables object
 */
function parseEnvString(envFileString: string): Environment;

/**
 * Parse out all env vars from an env file string
 * @param envString - Environment string content  
 * @returns Environment variables object
 */
function parseEnvVars(envString: string): Environment;

/**
 * Strips out comments from env file string
 * @param envString - Environment file content with comments
 * @returns Content with comments removed
 */
function stripComments(envString: string): string;

/**
 * Strips out newlines from env file string  
 * @param envString - Environment file content with empty lines
 * @returns Content with empty lines removed
 */
function stripEmptyLines(envString: string): string;

/**
 * Normalize imported objects to environment variable format
 * @param input - Raw imported object from JS/TS modules
 * @param absolutePath - File path for error reporting
 * @returns Normalized environment variables with string values
 */
function normalizeEnvObject(input: unknown, absolutePath: string): Environment;

Usage Examples:

import { parseEnvString, stripComments } from "env-cmd/dist/parse-env-file.js";

// Parse raw .env content
const envContent = `
# Database configuration
DB_HOST=localhost
DB_PORT=5432
DB_NAME=myapp
`;

const parsed = parseEnvString(envContent);
// Result: { DB_HOST: 'localhost', DB_PORT: '5432', DB_NAME: 'myapp' }

// Remove comments from content
const cleaned = stripComments(envContent);
// Result: Content without comment lines

Parsing Process:

Comment Removal: stripComments() removes lines starting with #
Empty Line Removal: stripEmptyLines() removes blank lines
Variable Parsing: parseEnvVars() extracts key=value pairs
Quote Handling: Supports both single and double quoted values
Inline Comments: Removes comments from unquoted values

TypeScript Support

TypeScript Loader Validation

Function for validating TypeScript file loading support in the current environment.

/**
 * Check if TypeScript is supported in the current environment
 * @throws Error if TypeScript files cannot be loaded
 */
function checkIfTypescriptSupported(): void;

Usage:

import { checkIfTypescriptSupported } from "env-cmd/dist/loaders/typescript.js";

try {
  checkIfTypescriptSupported();
  // TypeScript files can be loaded
} catch (error) {
  console.error("TypeScript support not available:", error.message);
}

Validation Process:

Checks for tsx loader availability
Validates TypeScript compilation support
Throws descriptive errors for missing loaders

Path Resolution

All file paths undergo resolution processing:

/**
 * A simple function for resolving the path the user entered
 * @param userPath - User-provided file path
 * @returns Absolute resolved path
 */
function resolveEnvFilePath(userPath: string): string;

Resolution Features: