Simple Config Utility for Node.js

1.8.2 · abandoned · verified Sun Apr 19

Cz is a minimalistic configuration utility designed for Node.js applications, enabling developers to load, manage, and access configuration settings from files or programmatically. It provides methods for loading configuration files (e.g., JSON), setting default values, and getting/setting specific configuration properties using dot-notation paths. The package's current stable version is 1.8.2, released in early 2017. Due to a lack of updates since then, it is considered abandoned. Key differentiators include its extreme simplicity and reliance on CommonJS patterns, making it suitable for older Node.js projects but not for modern ESM-first environments. It provides basic configuration merging capabilities by applying changes on top of defined defaults, with options to reset the configuration or just its defaults.

Common errors

```
ReferenceError: Cz is not defined
```
cause Attempting to use `Cz` as a global variable without explicit import or definition.

fix Ensure `const Cz = require('cz');` is at the top of your file to import the class.
```
TypeError: config.defaults is not a function
```
cause Calling a method like `defaults()` directly on the `require('cz')` result, instead of on an instantiated `Cz` object.

fix Correct the import and instantiation: `const Cz = require('cz'); const config = new Cz(); config.defaults({});`
```
Error: ENOENT: no such file or directory, open './config.json'
```
cause The file path provided to `config.load()` does not exist or is inaccessible from the current working directory.

fix Verify the `config.json` file path is correct and the file exists. Use an absolute path or ensure the relative path is correct based on where your script is run.

Warnings

gotcha The `cz` package is effectively abandoned, with its last release (v1.8.2) in January 2017. It has not received updates for over seven years, which means it may not be compatible with newer Node.js versions or security best practices.
Fix: Consider migrating to a actively maintained configuration library like `dotenv`, `config`, or `nconf` for ongoing support and compatibility.
gotcha Cz is a CommonJS-only module. It does not provide ESM (ECMAScript Module) exports, making it incompatible with `import` statements in modern Node.js or browser environments where ESM is preferred or required.
Fix: Use `require('cz')` for module imports. If you need ESM compatibility, you will need to use a different library or a CJS-to-ESM wrapper/bundler.
gotcha The README documentation includes an example `const config = require('cz'); config.defaults({});` which incorrectly implies the `cz` module exports a direct instance or a function. The module actually exports the `Cz` class, requiring instantiation with `new Cz()` before methods can be called.
Fix: Always instantiate `Cz` using `const config = new Cz();` before attempting to use its methods like `config.defaults()` or `config.set()`.

Install

npm install cz npm
yarn add cz yarn
pnpm add cz pnpm

Imports

Cz
wrong:
```
import Cz from 'cz';
```
correct:
```
const Cz = require('cz');
const config = new Cz();
```
The `cz` package exports the `Cz` class directly. It is a CommonJS module, primarily intended for use with `require()` and instantiation with `new`.
config.load()
wrong:
```
const config = require('cz').load('./config.json');
```
correct:
```
const config = new Cz();
config.load('./config.json');
```
Configuration methods like `load` are available on an instantiated `Cz` object, not directly on the module export.
config.get()
wrong:
```
require('cz').get('db:host');
```
correct:
```
const config = new Cz();
config.get('db:host');
```
Accessing configuration values requires an initialized `Cz` instance.

Quickstart

This quickstart demonstrates how to instantiate `Cz`, set initial configuration, define default values, retrieve specific configuration properties using dot notation, and construct a practical connection string using both manual concatenation and `cz`'s `joinGets` helper.

const Cz = require('cz');
const config = new Cz();

// Imagine 'config.json' exists with some data, e.g., { "db": { "host": "localhost" } }
// For demonstration, we'll simulate the load with `set`
config.set('db', {
    host: 'localhost',
    port: 27017,
    username: 'user',
    password: 'password',
    collection: 'my-app'
});

// Sets Cz's default value for "port" to 4000
config.defaults({
    port: 4000
});

// Sets Cz to { random: 'random value' }
config.set('random', 'random value');

// This will return the whole config object currently loaded
console.log('Current config:', config.get());

// This will get { host: 'localhost', port: 27017, username: 'user', password: 'password', collection: 'my-app' } from the config object
console.log('db config:', config.get('db'));
console.log('db host:', config.get('db:host'));

// Example of how to construct a connection string
const mongoUri = 'mongodb://' + config.get('db:username') + ':' + config.get('db:password') + '@' + config.get('db:host') + ':' + config.get('db:port') + '/' + config.get('db:collection');
console.log('MongoDB URI (manual):', mongoUri);

// Cz provides a helper to join gets for you
const mongoUriJoined = 'mongodb://' + config.joinGets(['db:username', 'db:password', 'db:host', 'db:port', 'db:collection'], [':', '@', ':', '/']);
console.log('MongoDB URI (joined):', mongoUriJoined);

view raw JSON →