KrakenJS environment configuration for repeatable development setups

Recommended Pattern: Mapping File + Dotenv

Use config/custom-environment-variables.json to declaratively map configuration keys to environment variable names, then load per-machine values from a gitignored .env file via dotenv before the config package initializes. This keeps the mapping version-controlled while secrets and machine-specific paths stay out of git.

Why This Prevents Drift

The config package (used by KrakenJS) reads custom-environment-variables.json at require time and overlays any matching process.env values on top of default.json, development.json, and production.json. Because the mapping itself is committed, every developer and CI environment applies the same override structure — only the actual values differ per machine.

Implementation Steps

1. Create the mapping file at config/custom-environment-variables.json:

   {
     "database": {
       "host": "DB_HOST",
       "password": "DB_PASSWORD"
     },
     "service": {
       "apiKey": "SERVICE_API_KEY"
     }
   }

2. Add a gitignored .env in the project root with local values:

   DB_HOST=localhost
   DB_PASSWORD=dev-only-secret
   SERVICE_API_KEY=local-dev-key

3. Load dotenv before any config require in your entry point (e.g., server.js):

   require('dotenv').config();
   const config = require('config');
   // config.get('database.host') now returns 'localhost'

4. Commit default.json and development.json with safe, non-secret defaults. Commit custom-environment-variables.json. Never commit .env.

Verification Checklist

• Run npm ls config to confirm the config package version (mapping file support exists since v1.x).
• Add a test key to default.json ("testKey": "default"), map it in custom-environment-variables.json ({"testKey": "TEST_VAR"}), set TEST_VAR=override in .env, start the app, and log config.get('testKey') to confirm the override works.
• Temporarily log process.env.TEST_VAR right after dotenv.config() and before require('config') to verify load order.
• Repeat on a second machine or CI container to confirm repeatability.

Assumptions & Uncertainties

• Dot notation vs nested objects: Some older config versions expect flat keys with dot notation (e.g., "database.host": "DB_HOST") instead of nested objects. Verify your version's syntax if overrides don't apply.
• Type conversion: Mapped environment variables are always strings; the package does not auto-parse JSON, numbers, or booleans. Handle conversion in application code if needed.
• KrakenJS version: Both 1.x (Express 3) and 2.x (Express 4) use the same config package behavior; no framework-specific differences exist for this pattern.

Missing diagnostic detail: What config package version does your project currently resolve to? Run npm ls config and share the version if override behavior differs from the steps above.