Installation

This guide will walk you through the process of installing env-mage in your Node.js project.

Requirements

Before installing env-mage, make sure you have:

• Node.js (version 14.x or later)
• npm (version 6.x or later), yarn, or pnpm

Installation Options

You can install env-mage either globally or as a project dependency, depending on your needs.

Global Installation

Global installation allows you to use env-mage commands from any directory on your machine. This is useful if you work with multiple projects and want to have env-mage available system-wide.

# Using npm
npm install -g env-mage

# Using yarn
yarn global add env-mage

# Using pnpm
pnpm add -g env-mage

Example output:

added 37 packages in 4.2s

Local Project Installation

If you want to include env-mage as part of your project dependencies, you can install it locally:

# Using npm
npm install --save-dev env-mage

# Using yarn
yarn add --dev env-mage

# Using pnpm
pnpm add -D env-mage

Example output:

added 37 packages, removed 0 packages, changed 0 packages in 2.8s

Verifying Installation

After installation, you can verify that env-mage was installed correctly:

env-mage --version

Example output:

env-mage v1.2.0

Configuration

env-mage works out of the box with no configuration, but you can customize its behavior:

Project Configuration

Create an env-mage.config.js file in your project root:

module.exports = {
  // Default paths
  envPath: '.env',
  examplePath: '.env.example',
  
  // Validation options
  required: ['API_KEY', 'DATABASE_URL'],
  
  // TypeScript options
  typesOutput: 'src/env.d.ts',
  
  // Scanning options
  scanDirs: ['src'],
  scanIgnore: ['node_modules', 'dist']
};

CLI Configuration

You can also set configuration options using CLI flags, which override the config file:

env-mage validate --env-path=.env.production --required=API_KEY,DATABASE_URL

Things to Know

• Global installation (-g) requires appropriate permissions
• Local installation requires using npx env-mage to run commands
• Config file takes precedence over default values but not over CLI arguments
• env-mage respects .gitignore patterns when scanning files