{"id":11083,"library":"ini","title":"INI File Parser and Serializer","description":"The `ini` package provides a robust encoder and decoder for INI file formats in Node.js environments. As of version 6.0.0, it targets Node.js `^20.17.0 || >=22.9.0`. The library is actively maintained, with frequent major version bumps primarily driven by updates to supported Node.js engine ranges. Key features include parsing INI strings into nested JavaScript objects, handling section-less items as globals, and supporting bracketed arrays (e.g., `key[] = value`). It also offers comprehensive serialization with options for whitespace, alignment, sorting of sections and keys, platform-specific line endings, and custom section identifiers. It differentiates itself by offering fine-grained control over output format and careful handling of common INI parsing quirks. The project maintains a healthy release cadence, with at least one new version released in the past 12 months.","status":"active","version":"6.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/npm/ini","tags":["javascript"],"install":[{"cmd":"npm install ini","lang":"bash","label":"npm"},{"cmd":"yarn add ini","lang":"bash","label":"yarn"},{"cmd":"pnpm add ini","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primary function to convert INI string to object. The `decode` alias also exists. Modern Node.js projects should use ESM imports.","wrong":"const parse = require('ini').parse","symbol":"parse","correct":"import { parse } from 'ini'"},{"note":"Primary function to convert an object to an INI string. The `encode` alias also exists. Modern Node.js projects should use ESM imports.","wrong":"const stringify = require('ini').stringify","symbol":"stringify","correct":"import { stringify } from 'ini'"},{"note":"Utility to escape a string for use as a key or value in an INI file.","wrong":"const safe = require('ini').safe","symbol":"safe","correct":"import { safe } from 'ini'"},{"note":"Utility to unescape a string previously escaped for an INI file.","wrong":"const unsafe = require('ini').unsafe","symbol":"unsafe","correct":"import { unsafe } from 'ini'"}],"quickstart":{"code":"import { writeFile , readFile } from 'node:fs/promises'\nimport { stringify , parse } from 'ini'\n\nconst iniContent = `\n; This comment is being ignored\nscope = global\n\n[database]\nuser = dbuser\npassword = dbpassword\ndatabase = use_this_database\n\n[paths.default]\ndatadir = /var/lib/data\narray[] = first value\narray[] = second value\narray[] = third value\n`\n\nasync function manageIni() {\n  // Simulate reading INI file content\n  let text = iniContent;\n\n  // Parse text data to object\n  const config = parse(text)\n\n  // Modify data object\n  config.scope = 'local'\n  config.database.database = 'use_another_database'\n  config.paths.default.tmpdir = '/tmp'\n  delete config.paths.default.datadir\n  if (config.paths.default.array && Array.isArray(config.paths.default.array)) {\n    config.paths.default.array.push('fourth value')\n  }\n\n  // Stringify data object with a section prefix\n  text = stringify(config, {\n    section : 'newSection',\n    whitespace: true // Optional: Add spaces around = for readability\n  })\n\n  console.log('Modified INI content:\\n', text)\n  // In a real app, you'd write this back to a file:\n  // await writeFile(`./Modified.ini`,text)\n}\n\nmanageIni().catch(console.error);\n","lang":"javascript","description":"This example demonstrates reading INI data, parsing it into a JavaScript object, modifying properties (including nested sections and arrays), and then stringifying the object back into an INI formatted string with a custom top-level section."},"warnings":[{"fix":"Upgrade Node.js to a compatible version (e.g., Node.js 20.17.0+ or 22.9.0+) or pin `ini` to an earlier major version if an upgrade is not feasible.","message":"Version 6.0.0 introduces a breaking change by tightening Node.js engine compatibility, now requiring Node.js `^20.17.0 || >=22.9.0`. Ensure your environment meets these requirements before upgrading.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Upgrade Node.js to a compatible version (e.g., Node.js 18.17.0+ or 20.5.0+) or pin `ini` to a v4.x release.","message":"Version 5.0.0 updated Node.js engine compatibility to `^18.17.0 || >=20.5.0`. Projects on older Node.js versions must upgrade Node.js or remain on `ini` v4.x.","severity":"breaking","affected_versions":">=5.0.0 <6.0.0"},{"fix":"Upgrade Node.js to a supported LTS version (e.g., Node.js 14.17.0+, 16.13.0+, or 18.0.0+) or use `ini` v2.x.","message":"Version 3.0.0 dropped support for Node.js 10 and non-LTS versions of Node.js 12 and 14, requiring Node.js `^14.17.0 || ^16.13.0 || >=18.0.0` for v4.0.0. Projects using these older Node.js versions will break upon upgrade.","severity":"breaking","affected_versions":">=3.0.0 <4.0.0"},{"fix":"Pass `{ whitespace: true }` or `{ align: true }` as the options object to `stringify`.","message":"When using `stringify`, the `whitespace` option defaults to `false`. This can result in INI output like `key=value` instead of `key = value`. If you require spaces for readability or compatibility with specific parsers, explicitly set `whitespace: true` or use the `align: true` option which implies `whitespace: true`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If your parser expects duplicate keys without brackets for arrays, set `bracketedArray: false` in the options for `stringify`.","message":"The `stringify` function's `bracketedArray` option defaults to `true`, appending `[]` to array keys (e.g., `array[] = value`). While common, some older INI parsers might treat duplicate keys without brackets as arrays. Ensure this default matches your target parser's expectations.","severity":"gotcha","affected_versions":">=4.1.0"},{"fix":"Always pass an options object, e.g., `stringify(obj, { section: 'mySection' })`.","message":"For backwards compatibility, passing a string directly as the second argument to `stringify` is treated as the `section` option. While still supported, it's recommended to pass an options object for clarity and to utilize other formatting options.","severity":"deprecated","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Upgrade your Node.js environment to a compatible version (e.g., Node.js 20.17.0+ or 22.9.0+), or downgrade the `ini` package to a version compatible with your current Node.js setup (e.g., `npm install ini@4` for older Node.js LTS versions).","cause":"Your Node.js version does not meet the minimum requirements specified in the `engines` field of the `ini` package's `package.json` for the installed version (6.0.0).","error":"The \"ini\" package is not compatible with your Node.js version. Requires: ^20.17.0 || >=22.9.0"},{"fix":"For modern Node.js environments (which `ini` v3+ targets), use ESM `import` statements: `import { parse, stringify } from 'ini';`. If you must use CommonJS, ensure your `package.json` configuration properly handles dual CommonJS/ESM exports, or consult the package's `exports` field if available.","cause":"This error typically occurs when attempting to use CommonJS `require()` syntax with an ESM-first package that only exposes named exports or has different CJS entry points, or if the `require` call is incorrect.","error":"TypeError: ini.parse is not a function OR ini.stringify is not a function (when using require())"},{"fix":"Explicitly configure the `stringify` options to match your desired output. For example, `stringify(obj, { whitespace: true, bracketedArray: false })`.","cause":"The default options for `ini.stringify` (like `whitespace: false` and `bracketedArray: true`) may not align with your expected INI format or the requirements of another INI parser.","error":"Unexpected output format from `ini.stringify` (e.g., missing spaces around `=`, or array format issues)"}],"ecosystem":"npm"}