KrakenJS Configuration Layering: Designing Environment‑Specific Settings

Requirements

When building a Node.js service with KrakenJS, the same source code must run unchanged across development, testing, and production. Sensitive values such as database URLs, feature flags, and server ports must be externalised so they can be adjusted without rebuilding the artifact. The solution must be deterministic, easy to audit, and compatible with the twelve‑factor app principle of storing config in the environment.

Smallest Suitable Design

KrakenJS provides a built‑in config module that merges a base config.json with an optional file named config.<NODE_ENV>.json. The merge is a shallow‑object overlay: properties in the environment file replace or add to those in the base file. No additional libraries or custom middleware are required.

File layout example

project/
├─ config.json
├─ config.development.json
├─ config.production.json
└─ server.js

config.json contains defaults that are safe for all environments (e.g., logging level). Environment‑specific files override only the values that differ.

Trust/Data Boundaries

The configuration files are read at process start‑up and treated as trusted input because they reside in the repository or are injected via secure deployment mechanisms (e.g., secrets manager). The merged config object is frozen for the lifetime of the process; KrakenJS does not expose a runtime API to mutate it, preventing accidental changes that could bypass security reviews.

Operational Checks

To verify that the correct layering occurred, start the application with an explicit NODE_ENV and inspect the resolved config:

1. Set the environment variable (requires permission to execute the Node process):

   NODE_ENV=development node server.js

2. Add a temporary debug line in server.js after KrakenJS initialization to dump the config:

   const app = require('kraken-js');
   app.create().then((instance) => {
     console.log('Resolved config:', instance.config);
     // start listening...
   });

3. Check the console output: values from config.development.json should appear where they differ from config.json. Repeat with NODE_ENV=production to confirm the production overrides.

Risk: If NODE_ENV is unset or misspelled, KrakenJS falls back to an empty environment name, effectively loading only config.json. This can cause production‑like behavior in a developer machine or expose development secrets in staging. Always set the variable explicitly in launch scripts or container definitions.

Failure Modes

• Incorrect merge order – Should never happen because the algorithm is fixed: base first, then environment file. If a custom config loader is introduced, verify that it respects this order.

• File missing or malformed JSON – KrakenJS will throw an error during start‑up, preventing the service from launching with an incomplete configuration. Ensure CI pipelines validate JSON syntax.

• Unintended property overwrite – Because the merge is shallow, nested objects are replaced entirely. If a nested object needs partial updates, restructure the config to keep the nested level flat or use a custom deep‑merge strategy outside KrakenJS.

Conditions That Would Change the Design

The current layering approach remains appropriate as long as:

• The number of distinct environments stays low (typically dev, test, prod).
• Configuration values are primarily scalar or flat objects; deep hierarchical overrides are rare.
• The application does not require runtime re‑loading of config without a restart. If hot‑reload becomes a requirement, an external config service (e.g., Consul, Vault) would replace the file‑based merge.

Practical Verification Checklist

1. Confirm NODE_ENV is set in the launch command or container env.
2. Start the app and capture the logged config object.
3. Compare each key against the base and environment files to ensure the expected override.
4. Run the same check for each target environment to guarantee consistency.
5. In CI, add a step that lints JSON files and fails on parse errors.