# confignition

> A modern TypeScript library to parse, watch, and write configuration files (JSON, YAML, TOML, INI, .env) with optional AWS S3 / Azure Blob cloud support, hot reload, field-level encryption, and an Express middleware.

Latest version **1.0.0** (published 2026-08-02) · MIT license · 0 weekly downloads

## Install

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

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2026-08-02 |
| First published | 2023-04-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18.0.0 |
| Dependencies | 4 |
| Unpacked size | 59.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 2 |
| Author | Andrea Pallotta |
| Maintainers | andrea-pallotta |
| Keywords | config, configuration, node, yml, yaml, json, toml, env, dotenv, ini, hot-reload, encryption, aws, azure, s3 |

## Links

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

## Dependencies (4)

- [yaml](https://npm.io/package/yaml.md) ^2.2.2
- [smol-toml](https://npm.io/package/smol-toml.md) ^1.0.0
- [@aws-sdk/client-s3](https://npm.io/package/@aws-sdk/client-s3.md) ^3.321.1
- [@azure/storage-blob](https://npm.io/package/@azure/storage-blob.md) ^12.14.0

## 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.0 (latest) — 2026-08-02
- 0.7.0 — 2023-05-02
- 0.6.0 — 2023-05-02
- 0.5.0 — 2023-04-30
- 0.0.4 — 2023-04-29
- 0.0.3 — 2023-04-28
- 0.0.1 — 2023-04-28

## README

<p>
  <a href="https://www.npmjs.com/package/confignition" target="_blank">
    <img alt="Version" src="https://img.shields.io/npm/v/confignition.svg">
  </a>
  <a href="https://github.com/AndreaPallotta/confignition#readme" target="_blank">
    <img alt="Documentation" src="https://img.shields.io/badge/documentation-yes-brightgreen.svg" />
  </a>
  <a href="https://github.com/AndreaPallotta/confignition/graphs/commit-activity" target="_blank">
    <img alt="Maintenance" src="https://img.shields.io/badge/Maintained%3F-yes-green.svg" />
  </a>
  <a href="https://github.com/AndreaPallotta/confignition/blob/master/LICENSE.md" target="_blank">
    <img alt="License: MIT" src="https://img.shields.io/github/license/AndreaPallotta/confignition" />
  </a>
  <a href="https://github.com/AndreaPallotta/confignition/issues" target="_blank">
    <img alt="Issues" src="https://img.shields.io/github/issues/AndreaPallotta/confignition" />
  </a>
  <img alt="downloads" src="https://img.shields.io/npm/dt/confignition" />
  <img alt="stars" src="https://img.shields.io/github/stars/AndreaPallotta/confignition" />
</p>

<div style="display: flex; justify-content: center;">
  <h1>Confignition</h1>
  <img alt="Logo" src="logo.svg" style="width: 75px; height: auto; margin-left: 1rem;" />
</div>

This TypeScript library provides a simple and efficient way to parse different types of config files, including JSON, YAML, INI, .env, and TOML.
Additionally, it supports retrieving files stored on AWS S3 or Azure Blob.

---

## Supported File Types

The library current supports the following file types:

- **JSON**
- **YAML**
- **INI**
- **.env**
- **TOML**

---

## Installation

To install the package you can use npm or yarn:

```bash
npm install confignition
```

or

```bash
yarn add confignition
```

---

## Usage

To use this library, first import it (supports both ES5 and ES6+):

```js
const { parse, getConfig } = require('confignition');
```

or

```js
import { parse, getConfig } from 'confignition';
```

---

## Examples

- For the following example config:

  ```toml
  [server]
  host = "localhost"
  port = 5000

  [database]
  url = "postgres://username:password@localhost/mydatabase"


  [[database.options]]
  https = true
  auth = "basic"
  ```

- Parse a local file

  ```js
  const config = parse('src/configs/config.toml');

  /**
   {
    port: 5000,
    host: 'localhost',
   }
   */
  ```

  > NOTE: you can also specify the file type if the extension does not match the file format

  ```js
  const config = parse('src/configs/config.txt', { type: 'toml' });
  ```

- Retrieve the parsed configurationn object

  ```js
  const config = getConfig();

  /**
   {
    port: 5000,
    host: 'localhost',
   }
   */
  ```

- Update configuration file

  ```js
  const updatedConfig = update({ newConfig: 'updated' });
  ```

---

## Parse configuration

To parse the configuration, you can use the `parse` function. The function accepts 2 arguments:

- The file path - relative to the root directory of the project
- An object to specify options (optional)

```js
// The type is inferred
import { parse } from 'confignition';
const config = parse('src/configs/.env');

// or

// The type must be specified because the file extension does not match the format type
const config = parse('src/config/config.txt', { type: 'dotenv' });
```

---

## Custom parsing

In additional to the parsing algorithms provided, you can write your own. Especially useful if the config format is not currently supported or requires extra steps.

```js
import { customParse } from 'confignition';

const config = customParse(
  'src/config/config.cfg',
  (content) => {
    let conf;
    // ...parsing logic
    return conf;
  },
  { type: 'cfg' } // the type is required as it is not inferred.
);
```

## Dynamically update config file

To update the existing configuration or create a new file and subscribe to it, you can use the `update` function. The function accepts 2 arguments:

- The new configuration object or a callback similar to React's useState hook.

```js
// Override configuration
const updatedConfig = update({ override: true });

// or

// Add additional fields to existing configuration
const updatedConfig = update((prev) => ({
  ...prev,
  additionalSection: {
    updatedConfig: true,
  },
}));

// Create a new configuration file and subscribe to it
const updateConfig = update(
  { newConfig: true, version: '0.2.0' },
  {
    createNewFile: true,
    newFileOptions: {
      path: 'src/configs/newConfig.json', // if the file already exists, it will override its content.
      type: 'json', // optional. Type will be inferred from the file name
    },
  }
);
```

---

## Remote Configurations (STILL IN PROGRESS)

Currently, the library supports retrieving files from AWS S3 Buckets and Azure Blob Storages. Pass the remote file name as the file path and add the configurations needed to access the remote storage.

- AWS:

```js
const config = parse('config_on_aws', {
  type: 'json',
  fromCloud: true,
  cloudConfig: {
    aws: {
      s3Bucket: 'my-bucket',
      awsConfig: {
        /* aws configs */
      },
      // refer to the AWS SDK Docs: https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-s3/interfaces/s3clientconfig.html
    },
  },
});
```

- Azure:

```js
const config = parse('config_on_azure', {
  type: 'ini',
  fromCloud: true,
  cloudConfig: {
    azure: {
      connectionString: 'my-bucket',
      containerName: 'my-container',
      // refer to the Azure SDK Docs: https://learn.microsoft.com/en-us/javascript/api/@azure/storage-blob/blobserviceclient?view=azure-node-latest#@azure-storage-blob-blobserviceclient-constructor-1
    },
  },
});
```

---

## Hot Reload

The library supports hot reloading of the config file. Set the `hotReload` to `true`

```js
const config = parse('../config.toml', {
  hotReload: true,
  hotReloadInterval: 2000, // in ms. Default: 1000ms
});
```

> NOTE: Hot reload only works for local files. Changes to remote files will not trigger an update.

---

## Express Integration

A middleware is available for integration with the Express framework. The middleware injects the existing configuration or parsed a new one (if the filepath is specified) into the request object.

```js
import * as express from 'express';
import { expressConfignition } from 'confignition';
const app = express();

app.use(expressConfignition('src/configs/config.ini'));

app.get('/', (req, res) => {
  const { config, params } = req;
  // ...
});
```

or

```js
import * as express from 'express';
import { parse, expressConfignition } from 'confignition';

parse('src/configs/config.yaml');

const app = express();

app.use(expressConfignition());

app.get('/', (req, res) => {
  const { config, params } = req;
  // ...
});
```

---

## Encryption (Coming Soon)

In a future release, the library will support encryption of the config files (or part of them). This will allow you to store sensitive information such as API keys, passwords, and tokens securely.

---

## Author

👤 **Andrea Pallotta**

- Github: [@AndreaPallotta](https://github.com/AndreaPallotta)

> For inquiries, suggestions, and criticisms, you can reach me via:
>
> - email: [andreapallotta.dev@gmail.com](mailto:andreapallotta.dev@gmail.com)
> - LinkedIn: [@andreapallotta9](https://linkedin.com/in/andreapallotta9)

---

## 🤝 Contributing

Contributions, issues and feature requests are welcome!<br />Feel free to check [issues page](https://github.com/AndreaPallotta/confignition/issues).

If you have your own template repository, I suggest to clone this tool and change the source repository!

---

## Show your support

Give a ⭐️ if you found this tool useful or interesting!

---

## 📝 License

This project is [MIT](https://github.com/AndreaPallotta/confignition/blob/master/LICENSE) licensed.

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