{"id":12986,"library":"confbox","title":"confbox","description":"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.","status":"active","version":"0.2.4","language":"javascript","source_language":"en","source_url":"https://github.com/unjs/confbox","tags":["javascript","config","ini","json5","jsonc","toml","unjs","yaml","typescript"],"install":[{"cmd":"npm install confbox","lang":"bash","label":"npm"},{"cmd":"yarn add confbox","lang":"bash","label":"yarn"},{"cmd":"pnpm add confbox","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"confbox became ESM-only in v0.2.0. Use named imports with 'import'.","wrong":"const { parseYAML } = require('confbox')","symbol":"parseYAML","correct":"import { parseYAML } from 'confbox'"},{"note":"All utility functions are named exports; there is no default export.","wrong":"import confbox from 'confbox'; const result = confbox.stringifyJSON5(...);","symbol":"stringifyJSON5","correct":"import { stringifyJSON5 } from 'confbox'"},{"note":"INI parsing and stringifying are available, but note that style and indentation are not preserved.","symbol":"parseINI","correct":"import { parseINI, stringifyINI } from 'confbox'"}],"quickstart":{"code":"import { parseYAML, stringifyYAML } from 'confbox';\n\nconst yamlString = `\n# My App Configuration\nversion: 1.0.0\nenvironment: development\ndatabase:\n  host: localhost\n  port: 5432\n  user: admin\n  password: ${process.env.DB_PASSWORD ?? 'supersecret'}\nsettings:\n  debug: true\n`;\n\ntry {\n  const config = parseYAML(yamlString);\n  console.log('Parsed config:', config);\n\n  // Modify a value\n  config.environment = 'production';\n  config.settings.debug = false;\n\n  const modifiedYamlString = stringifyYAML(config);\n  console.log('\\nModified YAML string:\\n', modifiedYamlString);\n} catch (error) {\n  console.error('Error processing YAML:', error);\n}","lang":"typescript","description":"Demonstrates parsing a YAML string, modifying the resulting object, and stringifying it back."},"warnings":[{"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.","message":"confbox 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.","severity":"breaking","affected_versions":">=0.2.0"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=0.2.0"},{"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).","message":"While `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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=0.2.2"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change `const { parseYAML } = require('confbox');` to `import { parseYAML } from 'confbox';` and ensure your project is configured for ES modules.","cause":"Attempting to use CommonJS `require()` syntax to import `confbox` in a module context after version 0.2.0.","error":"ReferenceError: require is not defined in ES module scope"},{"fix":"Verify that you are using named imports for the specific functions you need, e.g., `import { parseYAML } from 'confbox';`.","cause":"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.","error":"TypeError: parseYAML is not a function"},{"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.","cause":"The `confbox` package has not been installed, or the module resolver cannot locate it (common in monorepos or unusual build setups).","error":"Error: Cannot find module 'confbox'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}