{"id":13331,"library":"ini-api","title":"INI API","description":"The `ini-api` package provides a robust, class-based API for programmatically parsing, editing, and creating INI configuration files in JavaScript and TypeScript environments. The current stable version is 2.0.2. This library offers distinct classes like `Ini`, `IniSection`, and `IniLine` to represent the structural components of an INI file, allowing for granular manipulation of sections, key-value pairs, and comments. It distinguishes itself by providing a structured object model rather than simple string parsing utilities, enabling developers to interact with INI files using familiar object-oriented patterns. While there isn't a strict release cadence, the project receives updates, with recent significant changes in v2.0.0 (transition to ESM) and v2.0.2 (re-introduction of CJS alongside ESM).","status":"active","version":"2.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/matortheeternal/ini-api","tags":["javascript","ini","stringify","parse","config"],"install":[{"cmd":"npm install ini-api","lang":"bash","label":"npm"},{"cmd":"yarn add ini-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add ini-api","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary class for interacting with INI files. Since v2.0.2, both ESM and CommonJS exports are available. Prior to v2.0.2 (specifically v2.0.0 and v2.0.1), it was ESM-only.","wrong":"const Ini = require('ini-api').Ini;","symbol":"Ini","correct":"import { Ini } from 'ini-api';"},{"note":"Represents an individual section within an INI file, including its lines. Part of the named exports for direct manipulation of sections.","wrong":"const IniSection = require('ini-api').IniSection;","symbol":"IniSection","correct":"import { IniSection } from 'ini-api';"},{"note":"An object containing constants that define different types of lines found in an INI file (e.g., header, property, comment).","wrong":"const lineTypes = require('ini-api').lineTypes;","symbol":"lineTypes","correct":"import { lineTypes } from 'ini-api';"}],"quickstart":{"code":"import { Ini, IniSection, IniLine } from 'ini-api';\nimport fs from 'fs';\nimport path from 'path';\n\n// Example 1: Creating an empty INI file\nconst emptyIni = new Ini();\nconsole.log('Empty INI:\\n', emptyIni.stringify());\n\n// Example 2: Parsing existing INI content\nconst iniText = `\n; This is a comment\n[General]\nkey1 = value1\nkey2 = 123\n\n[Database]\nhost = localhost\nport = 5432\n`;\nconst parsedIni = new Ini(iniText);\nconsole.log('\\nParsed INI:\\n', parsedIni.stringify());\n\n// Example 3: Modifying an INI file\nconst generalSection = parsedIni.getSection('General');\nif (generalSection) {\n    generalSection.setValue('key3', 'new_value');\n}\nparsedIni.addSection('Security').setValue('admin_email', 'admin@example.com');\nconsole.log('\\nModified INI:\\n', parsedIni.stringify());\n\n// Example 4: Loading from a file (placeholder for actual file ops)\n// In a real scenario, you'd read a file:\n// const configFilePath = path.join(__dirname, 'config.ini');\n// const fileContent = fs.readFileSync(configFilePath, 'utf-8');\n// const configIni = new Ini(fileContent);\n// console.log('\\nINI from file (simulated):\\n', configIni.stringify());","lang":"typescript","description":"Demonstrates parsing, creating, and modifying INI file content using the `Ini` class, showing how to interact with sections and key-value pairs, and generating string output."},"warnings":[{"fix":"For projects requiring CommonJS, upgrade to `ini-api@2.0.2` or later, which reintroduces CommonJS exports alongside ESM. Alternatively, refactor your project to use ESM imports (`import ... from 'ini-api';`).","message":"Version 2.0.0 converted `ini-api` to an ES Module (ESM) only, which was a breaking change for applications built with CommonJS (CJS) that relied on `require()`. This was partially mitigated in v2.0.2.","severity":"breaking","affected_versions":">=2.0.0 <2.0.2"},{"fix":"Ensure your bundler (e.g., Webpack, Rollup) or Node.js environment is configured to correctly resolve CommonJS modules if you intend to use `require()`. For Node.js, explicitly setting `\"type\": \"commonjs\"` in your `package.json` for older projects can help, or migrate to ESM imports.","message":"While v2.0.2 reintroduced CommonJS exports, environments with complex module resolution or specific bundler configurations might still encounter issues when attempting to use `require()` if the ESM entry point is prioritized incorrectly.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Explicitly pass options to `stringify()` to control the output. For example, use `ini.stringify({ removeBlankLines: true, removeCommentLines: true })` to get a cleaner INI string without unnecessary whitespace and full comment lines.","message":"The `stringify()` method has default options that preserve blank lines and comments. If a more compact or standardized output is required, these defaults need to be overridden.","severity":"gotcha","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 to `ini-api@2.0.2` or later and use `require()` syntax, or convert your project to an ES Module by adding `\"type\": \"module\"` to `package.json` and updating your scripts.","cause":"Attempting to use `import` syntax in a CommonJS project (e.g., a script without `\"type\": \"module\"` in `package.json`) with `ini-api` versions `>=2.0.0 <2.0.2`.","error":"SyntaxError: Cannot use import statement outside a module"},{"fix":"For `ini-api@2.0.2+`, ensure your environment correctly resolves the CJS export if you insist on `require()`. Otherwise, refactor to use `import { Ini } from 'ini-api';` and ensure your project is configured for ESM.","cause":"Attempting to use `require()` in an ES Module context (e.g., a file with `import` statements or within a project with `\"type\": \"module\"`) when `ini-api` was ESM-only (`>=2.0.0 <2.0.2`). This can also occur with `v2.0.2+` if an environment incorrectly resolves the CJS export.","error":"TypeError: require is not a function"},{"fix":"Standardize on either `import` (recommended for modern Node.js/browser environments) or `require()` consistently throughout your project. If using `require()`, explicitly ensure your project isn't configured as an ES Module unless necessary.","cause":"While `ini-api@2.0.2` provides both CJS and ESM exports, mixing `require()` and `import` in complex project setups or specific Node.js environments can sometimes lead to warnings about module interoperability.","error":"(node:xyz) DeprecationWarning: require() of ES Module ... (or similar warnings)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}