{"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,"search_vec":"'2.0.2':34 'allow':54 'alongsid':122 'api':2,6,14 'base':13 'cadenc':101 'chang':109 'cjs':121 'class':12,39 'class-bas':11 'comment':65 'compon':49 'config':128 'configur':22 'creat':20 'current':30 'develop':82 'distinct':38 'distinguish':67 'edit':18 'enabl':81 'environ':28 'esm':114,123 'familiar':89 'file':23,53,87 'granular':56 'ini':1,5,21,41,52,86,125 'ini-api':4 'inilin':44 'inisect':42 'interact':84 'introduct':119 'isn':96 'javascript':25,124 'key':61 'key-valu':60 'librari':36 'like':40 'manipul':57 'model':74 'object':73,91 'object-ori':90 'offer':37 'orient':92 'packag':7 'pair':63 'pars':17,79,127 'pattern':93 'programmat':16 'project':103 'provid':8,70 'rather':75 're':118 're-introduct':117 'receiv':104 'recent':107 'releas':100 'repres':46 'robust':10 'section':59 'signific':108 'simpl':77 'stabl':31 'strict':99 'string':78 'stringifi':126 'structur':48,72 'transit':112 'typescript':27 'updat':105 'use':88 'util':80 'v2.0.0':111 'v2.0.2':116 'valu':62 'version':32","created_at":"2026-04-20T01:53:56.119036+00:00","updated_at":"2026-04-20T01:53:56.119036+00:00","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,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/matortheeternal/ini-api","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/ini-api","openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}