ng-compare-env 🔍

Zero-dependency Angular environment comparator for preprod and prod configurations across regions, brands, and sub-environments.

💡 The Problem

In enterprise and multi-regional Angular applications, environment configurations are often split across regions (such as EMEA, ANZ, ASIA, UK, EU, CHINA, etc.). Each region maintains paired folders like preprod and prod.

When developers add new features or environment variables into preprod, it is easy to forget to add them to prod. This causes catastrophic runtime crashes in production.

ng-compare-env automates this comparison in seconds:

1. Detects files missing in prod that exist in preprod.
2. Inspects configuration files (e.g., *Config.ts, environment*.ts) and detects missing keys in prod.
3. Prompts interactively for the target region/folder without requiring any code edits.
4. Returns an exit code 1 on failure, making it ideal for CI/CD gates and git pre-commit hooks.

🚀 Quick Start (Zero Install)

Run directly in any Angular workspace with npx:

npx ng-compare-env

(or using alias)

npx compare-env

📦 Installation

Add it to your Angular project as a development dependency:

npm install --save-dev ng-compare-env

Or with Yarn / pnpm:

yarn add -D ng-compare-env
# or
pnpm add -D ng-compare-env

Add a convenience script to your package.json:

{
  "scripts": {
    "compare-env": "compare-env"
  }
}

Now any developer can run:

npm run compare-env

🎯 How It Works

1. Interactive Mode (Default)

When you run npm run compare-env or npx ng-compare-env, the CLI interactively prompts you:

==================================================
              Angular Env Comparator              
==================================================

Enter root environment folder (e.g. EMEA, ANZ, ASIA, or "all"): EMEA

🔍 Searching for pairs under root environment folder: "EMEA"

Found 1 environment pair(s):
 • src/environments/EMEA

==================================================
Environment: src/environments/EMEA
==================================================

❌ Files Missing In Prod
   secretConfig.ts

❌ Missing Keys In Prod : appConfig.ts
   featureNewDashboard

==================================================
SUMMARY
==================================================
Environment Pairs Checked : 1
With Issues               : 1
Passed                    : 0

2. Dynamic Ignore Resolution (No Code Changes Needed!)

By default, standard build folders and other regions are kept in IGNORE_DIRS:

node_modules, .git, .angular, dist, coverage, .idea, .vscode,
ANZ, ASIA, UK, Root, CHINA, EU, EMEA

Old Approach: Developers had to manually edit the script to exclude EMEA from IGNORE_DIRS.

New Approach in ng-compare-env:

• When you input EMEA, the tool automatically exempts EMEA from the ignore list while keeping all other regions ignored.
• When you input ANZ, it automatically scans ANZ and ignores EMEA.
• You never need to touch the code or edit configuration files.

3. Non-Interactive / CI/CD Mode

You can provide the target environment folder directly via CLI argument or flag:

# By folder name
npx ng-compare-env EMEA

# Using flag
npx ng-compare-env --root EMEA
npx ng-compare-env -r ANZ

# Scan all environment folders in the workspace
npx ng-compare-env --all

In automated CI/CD pipelines (GitHub Actions, GitLab CI, Azure DevOps, Jenkins):

npx ng-compare-env EMEA
# Returns exit code 1 if issues found, 0 if all clean!

📂 Example Folder Structure

my-angular-app/
├── src/
│   └── environments/
│       ├── ANZ/
│       │   ├── preprod/
│       │   │   └── appConfig.ts
│       │   └── prod/
│       │       └── appConfig.ts
│       ├── EMEA/
│       │   ├── preprod/
│       │   │   ├── appConfig.ts
│       │   │   └── paymentConfig.ts
│       │   └── prod/
│       │       ├── appConfig.ts
│       │       └── paymentConfig.ts
│       └── ASIA/
│           ├── preprod/
│           └── prod/

🛠️ Programmatic Usage

You can also import and use ng-compare-env directly in custom Node.js / TypeScript build scripts:

const { findEnvironmentPairs, compareEnvironment, run } = require('ng-compare-env');

// Run full check programmatically
run({ targetFolder: 'EMEA' }).then(summary => {
  console.log(`Passed: ${summary.passed}, Issues: ${summary.failed}`);
});

Full TypeScript declarations (index.d.ts) are included out of the box.

🔄 Angular Version Compatibility

| Angular Version | Supported | Notes | | :--- | :---: | :--- | | Angular 19+ | ✅ | Fully tested with standalone components & esbuild/Vite | | Angular 17 - 18 | ✅ | Seamless integration with modern Angular CLI | | Angular 13 - 16 | ✅ | Works with Ivy builds | | Angular 8 - 12 | ✅ | Works with classic View Engine and Node 10+ |

Why is it 100% compatible across all Angular versions?

1. Developer Tooling (Build-time): It operates on the project structure and does not bundle into frontend client code.
2. Optional Peer Dependency: @angular/core: ">=8.0.0" is defined as optional, so it will never trigger ERESOLVE unable to resolve dependency tree errors.
3. Zero External Runtime Dependencies: Built entirely using Node.js standard library APIs (fs, path, readline). Fast, secure, and immune to version conflicts.

📄 License

MIT © Kuldeep Kaushik