confbox

library0.1.4jsnpmunverified

confbox is a utility library for parsing and serializing various configuration file formats, including YAML, TOML, JSONC (JSON with Comments), JSON5, INI, and standard JSON. The current stable version is 0.2.4, and the package maintains an active development cadence, releasing minor updates and patches regularly. Key differentiators include its claim of zero runtime dependencies for the end-user, tree-shakability for efficient bundling, and out-of-the-box TypeScript type definitions. It also features logic to preserve code style, such as indentation and whitespace, for certain formats during round-trip parsing and stringifying. While it wraps several established parsing libraries internally, it presents a unified, simplified API. For more complex configuration loading scenarios, the unjs/c12 library is recommended as an alternative.

serialization data

npm install confbox

github ↗package ↗

INSTALL

IMPORT

SIG · CONFBOX

confbox

serializationjavascriptv0.1.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parseYAML

✓ import { parseYAML } from 'confbox'

✗ const { parseYAML } = require('confbox')

confbox became ESM-only in v0.2.0. Use named imports with 'import'.

stringifyJSON5

✓ import { stringifyJSON5 } from 'confbox'

✗ import confbox from 'confbox'; const result = confbox.stringifyJSON5(...);

All utility functions are named exports; there is no default export.

parseINI

✓ import { parseINI, stringifyINI } from 'confbox'

INI parsing and stringifying are available, but note that style and indentation are not preserved.

Demonstrates parsing a YAML string, modifying the resulting object, and stringifying it back.

import { parseYAML, stringifyYAML } from 'confbox'; const yamlString = ` # My App Configuration version: 1.0.0 environment: development database: host: localhost port: 5432 user: admin password: ${process.env.DB_PASSWORD ?? 'supersecret'} settings: debug: true `; try { const config = parseYAML(yamlString); console.log('Parsed config:', config); // Modify a value config.environment = 'production'; config.settings.debug = false; const modifiedYamlString = stringifyYAML(config); console.log('\nModified YAML string:\n', modifiedYamlString); } catch (error) { console.error('Error processing YAML:', error); }

Debug

Known issues

breakingconfbox switched to an ESM-only distribution model starting from version 0.2.0. This means CommonJS 'require()' statements will no longer work, and you must use ES module 'import' syntax.

fix

Migrate all imports from `const { someFunc } = require('confbox')` to `import { someFunc } from 'confbox'`. Ensure your project environment (Node.js version, bundler configuration) supports ESM.

affects: >=0.2.0

gotchaWhen working with INI files, `parseINI` and `stringifyINI` currently do not preserve original style, comments, or indentation. Round-tripping INI files may result in a reformatted output.

fix

Be aware that INI output will be canonicalized. If style preservation is critical for INI, consider alternative dedicated INI parsers or processing the raw text directly.

affects: >=0.2.0

gotchaWhile `confbox` is advertised as 'zero dependency' for end-users, it internally utilizes several third-party parsers (e.g., `js-yaml`, `smol-toml`, `jsonc-parser`). Issues or breaking changes in these underlying libraries could indirectly affect `confbox` behavior.

fix

Monitor `confbox` release notes for dependency updates. If encountering unexpected parsing behavior, consult the documentation or issues of the respective underlying parser library (e.g., `js-yaml` for YAML).

affects: >=0.1.0

gotchaThe default indentation for `stringifyJSON` was changed to `2` in v0.2.2. If you relied on unindented or custom indented JSON output without specifying `options.indent`, your output format might have changed.

fix

If specific JSON indentation is required, always explicitly pass an `options` object to `stringifyJSON`, e.g., `stringifyJSON(value, { indent: 4 })` or `stringifyJSON(value, { indent: null })` for no indentation.

affects: >=0.2.2

Errors

Common errors & fixes

ReferenceError: require is not defined in ES module scope

Attempting to use CommonJS `require()` syntax to import `confbox` in a module context after version 0.2.0.

fix

Change `const { parseYAML } = require('confbox');` to `import { parseYAML } from 'confbox';` and ensure your project is configured for ES modules.

TypeError: parseYAML is not a function

Incorrect import syntax, such as attempting a default import (e.g., `import confbox from 'confbox'`) when all functions are named exports, or misspelling a named export.

fix

Verify that you are using named imports for the specific functions you need, e.g., `import { parseYAML } from 'confbox';`.

Error: Cannot find module 'confbox'

The `confbox` package has not been installed, or the module resolver cannot locate it (common in monorepos or unusual build setups).

fix

Run `npm install confbox`, `yarn add confbox`, or `pnpm add confbox` to install the package. If the issue persists, check your module resolution configuration.

Upgrade

Version history

0.1.4latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

28 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/unjs/confbox ↗

packagehttps://www.npmjs.com/package/confbox ↗