# superconf

> Smart configuration loader

Latest version **1.5.2** (published 2026-06-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install superconf
pnpm add superconf
yarn add superconf
bun add superconf
```

## Health

**Score 45/100 (D)** — status: active.

Positive: no vulnerabilities.

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

## Facts

| | |
|---|---|
| Version | 1.5.2 |
| Published | 2026-06-01 |
| First published | 2016-05-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 4 |
| Unpacked size | 30.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Andi Heinkelein |
| Maintainers | andifeind, kippis, firetux |
| Keywords | conf, config, configuration |

## Links

- npm: https://www.npmjs.com/package/superconf
- Repository: https://github.com/Andifeind/superconf
- Homepage: https://github.com/Andifeind/superconf#readme
- Issues: https://github.com/Andifeind/superconf/issues
- npm.io page: https://npm.io/package/superconf

## Dependencies (4)

- [js-yaml](https://npm.io/package/js-yaml.md) ^4.1.0
- [coffeescript](https://npm.io/package/coffeescript.md) ^2.7.0
- [firescript-firefs](https://npm.io/package/firescript-firefs.md) ^0.3.3
- [firescript-runtime](https://npm.io/package/firescript-runtime.md) ^0.3.13

## Alternatives

- [jsforce](https://npm.io/package/jsforce.md) — 851.2K weekly downloads
- [react-native-qrcode-svg](https://npm.io/package/react-native-qrcode-svg.md) — 693.5K weekly downloads
- [@salesforce/plugin-data](https://npm.io/package/@salesforce/plugin-data.md) — 394.9K weekly downloads
- [@backstage/plugin-search-common](https://npm.io/package/@backstage/plugin-search-common.md) — 308.5K weekly downloads
- [@chain-registry/types](https://npm.io/package/@chain-registry/types.md) — 38.4K weekly downloads

## Recent versions

- 1.5.2 (latest) — 2026-06-01
- 1.5.1 — 2026-06-01
- 1.5.0 — 2025-09-26
- 1.4.0 — 2025-09-25
- 1.3.1 — 2023-11-20
- 1.3.0 — 2023-10-06
- 1.2.4 — 2021-06-05
- 1.2.3 — 2019-07-30
- 1.2.2 — 2019-01-19
- 1.2.1 — 2019-01-02
- 1.2.0 — 2018-07-29
- 1.1.0 — 2018-04-30
- 1.0.1 — 2017-09-09
- 1.0.0 — 2017-09-03
- 0.2.2 — 2017-09-03
- … 4 more at https://npm.io/package/superconf/versions

## README

Superconf
=========

[![Build Status](https://travis-ci.org/Andifeind/superconf.svg?branch=master)](https://travis-ci.org/Andifeind/superconf)

Superconf is a smart configuration loader for Node.js.
It supports `json`, `cson`, `yaml`, `.rc` or `package.json` config formats.

## Usage

```js
const superconf = require('superconf');
const conf = superconf('myconf');
```

This command loads a configuration from current working dir.
Superconf tries to load configurations in this order:

* ${name}.json
* ${name}.cson
* ${name}.yaml
* ${name}.yml
* .${name}rc
* package.json (returns ${name} property)

## Options

### `files` overwrites the files array

```js
const opts = {
  files: ['config/development.json', 'config/development.yml']
}

const conf = superconf('myconf', opts)
```

### `cwd` set the current working dir

```js
const opts = {
  cwd: `${process.cwd()}/config`
}

const conf = superconf('myconf', opts)
```


## Merge configs

Superconf comes with a merge method. Morge is similar to Object.assign() or lodash.extend().
Its a configurable merge method which merges multiple configurations together.

This method was implemented because Object.assign or lodash.extend handle `undefined` or `null` properties differently.

### *static* merge(left, right[, ...args])

```js
const left = {
  fruit: 'Apple',
  vegetable: 'Carrot'
};

const right = {
  fruit: 'Banana',
  vegetable: undefined
};

const assgned = Object.assign({}, left, right);
// assgned === {
//   fruit: 'Banana'.
//   vegetable: undefined
// }

const conf = superconf.merge(left, right);
// conf === {
//   fruit: 'Banana',
//   vegetable: 'Carrot'
// }

```

#### Configure merge

Merge behavior can be changed.

A static `config()` method can be used to change merge begavior.

```js
const left = {
  fruits: {
    red: 'Apple'
  },
  vegetable: 'Carrot'
};

const right = {
  fruits: {
    yellow: 'Banana'
  },
  vegetable: undefined
};

const conf = superconf.merge(left, right);
// conf === {
//   fruits: {
//     yellow: 'Banana'
//   },
//   vegetable: 'Carrot'
// }

const conf = superconf.config({
  dept: 1
}).merge(left, right);
// conf === {
//   fruits: {
//     red: 'Apple',
//     yellow: 'Banana'
//   },
//   vegetable: 'Carrot'
// }
```
This will merge objects together, but only on the first level.

## Copy configs

The `.copy()` method returns a deep copy of the input object. It traverse through all objects and arrays and creates new copies of all objects and arrays.

### *static* copy(*any* obj)

```js
const obj = {
  foo: 'foo',
  bar: {
    bla: 'bla'
  }
}

const copy = superconf.copy(obj)

obj !== copy // true
obj.bar !== copy.bar // true
```

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