# pixl-config

> A simple JSON configuration loader.

Latest version **1.0.16** (published 2026-09-15) · MIT license · 0 weekly downloads

## Install

```sh
npm install pixl-config
pnpm add pixl-config
yarn add pixl-config
bun add pixl-config
```

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 1.0.16 |
| Published | 2026-09-15 |
| First published | 2015-02-08 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 13.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | Joseph Huckaby |
| Maintainers | jhuckaby |
| Keywords | json, config |

## Links

- npm: https://www.npmjs.com/package/pixl-config
- Repository: https://github.com/jhuckaby/pixl-config
- Issues: https://github.com/jhuckaby/pixl-config/issues
- npm.io page: https://npm.io/package/pixl-config

## Dependencies (3)

- [pixl-args](https://npm.io/package/pixl-args.md) ^1.0.0
- [pixl-class](https://npm.io/package/pixl-class.md) ^1.0.3
- [pixl-tools](https://npm.io/package/pixl-tools.md) ^2.0.2

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 1.0.16 (latest) — 2026-09-15
- 1.0.15 — 2026-04-25
- 1.0.14 — 2026-03-27
- 1.0.13 — 2022-03-27
- 1.0.12 — 2020-06-19
- 1.0.11 — 2020-04-10
- 1.0.10 — 2020-04-09
- 1.0.9 — 2019-04-09
- 1.0.8 — 2019-02-10
- 1.0.7 — 2018-11-29
- 1.0.6 — 2018-11-08
- 1.0.5 — 2018-08-15
- 1.0.4 — 2018-07-04
- 1.0.3 — 2018-02-06
- 1.0.2 — 2017-04-25
- … 2 more at https://npm.io/package/pixl-config/versions

## README

# Overview

This module provides a simple interface to your application's JSON configuration file on disk.  It will load and parse the file, and can automatically reload it when it changes (and emit an event when this happens).  Command-line arguments are automatically merged in with your config (uses [pixl-args](https://www.npmjs.com/package/pixl-args)), and treated as overrides.

# Usage

Use [npm](https://www.npmjs.com/) to install the module:

```sh
npm install pixl-config
```

Then use `require()` to load it in your code:

```js
const Config = require('pixl-config');
```

To use the module, instantiate an object:

```js
let config = new Config('conf/config.json');
```

If there is an error loading or parsing the file, an exception will be thrown, so you might want to wrap it in a try/catch.

Upon success, you can access your configuration keys/values using the `get()` method:

```js
let verbose = config.get('verbose');
let debug = config.get('debug');
```

If you just want a hash of the entire config file, call `get()` without passing a key:

```js
let opts = config.get();
if (opts.verbose) console.log("Verbose option is set.");
if (opts.debug) console.log("Debug option is set.");
```

You can also set values by calling `set()` and passing both a key and a value.  Example:

```js
config.set('verbose', true);
```

Values you set manually are persisted as long as the Node process is alive, even if the configuration file is reloaded on disk.

## Command-line Arguments

Command-line arguments (from [process.argv](http://nodejs.org/docs/latest/api/process.html#process_process_argv)) are automatically parsed and merged in with your configuration, and treated as overrides.  Only `--key value --key value` style arguments are processed.

Please see the [pixl-args](https://www.npmjs.com/package/pixl-args) module for more details.

## Live File Reloading

If you want the library to monitor your configuration file for live changes and automatically reload it, pass `true` as a second argument to the constructor:

```js
let config = new Config('conf/config.json', true);
```

This uses polling, and by default it checks the file for changes every 10 seconds.  The library then reloads the configuration and fires off an event you can listen for:

```js
let config = new Config('conf/config.json', true);

config.on('reload', function() {
	console.log("My app's config was reloaded!");
	console.log("Verbose = " + config.get('verbose'));
} );
```

If there is an error reloading the configuration, an `error` event is emitted (no exception is thrown).

To set the polling frequency, pass in the desired number of milliseconds instead of `true` as the second argument.  For example, to check every five seconds pass in `5000`:

```js
let config = new Config('conf/config.json', 5000);
```

To stop monitoring (for example during your app's shutdown sequence) call the `stop()` method.

If you would prefer to control exactly when to check for changes, do not enable live monitoring, and instead simply call the `check()` method at any frequency you want.

# License

**The MIT License**

*Copyright (c) 2014 - 2019 by Joseph Huckaby*

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

---
_Source: https://npm.io/package/pixl-config · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._