{"id":15479,"library":"properties-file","title":"properties-file parser & editor","description":"The `properties-file` library provides a high-performance, lossless parser, editor, and formatter for Java-style `.properties` files. Currently stable at version 5.0.4, it undergoes active maintenance with frequent releases (multiple patches per month based on recent history). A key differentiator is its lossless data model, preserving comments, blank lines, and duplicate keys, allowing for exact reconstruction or normalized output via `format()` options. It boasts 3–7x faster parsing than alternatives, zero dependencies, and a tiny bundle size (970 B min+gzip for `getProperties`). Compiled to ES5, it offers broad compatibility, running on Node.js versions back to 0.4.0 and any modern browser. It also includes bundler integrations for Webpack, Rollup/Vite, esbuild, and Bun to import `.properties` files directly.","status":"active","version":"5.0.4","language":"javascript","source_language":"en","source_url":"https://github.com/properties-file/properties-file","tags":["javascript",".properties","properties",".properties file","properties file","parser","editor","formatter","Java","typescript"],"install":[{"cmd":"npm install properties-file","lang":"bash","label":"npm"},{"cmd":"yarn add properties-file","lang":"bash","label":"yarn"},{"cmd":"pnpm add properties-file","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This is the entry point for quickly converting .properties content to a key-value object. While ES5 compatible, modern Node.js and browser environments should use ESM imports.","wrong":"const { getProperties } = require('properties-file')","symbol":"getProperties","correct":"import { getProperties } from 'properties-file'"},{"note":"The `Properties` class for lossless parsing and full data model access is exposed via the specific `/parser` subpath. Incorrectly importing from the root `properties-file` path will result in undefined or incomplete access.","wrong":"import { Properties } from 'properties-file'","symbol":"Properties","correct":"import { Properties } from 'properties-file/parser'"},{"note":"The `PropertiesEditor` for modifying properties files while preserving formatting is found in the `/editor` subpath. Importing from the root module directly is incorrect.","wrong":"import { PropertiesEditor } from 'properties-file'","symbol":"PropertiesEditor","correct":"import { PropertiesEditor } from 'properties-file/editor'"},{"note":"Since v4.0.0, the Webpack loader path was moved and renamed to `properties-file/bundler/webpack` for consistency with other bundler integrations.","wrong":"import 'properties-file/webpack-loader'","symbol":"Webpack Loader","correct":"import 'properties-file/bundler/webpack'"}],"quickstart":{"code":"import { readFileSync } from 'node:fs';\nimport { getProperties, Properties, PropertiesNodeType } from 'properties-file/parser';\nimport { PropertiesEditor } from 'properties-file/editor';\n\n// Example .properties content\nconst fileContent = `\n# This is a comment\nhello=world\nfoo:bar\\n\\r\nkey.with.escapes=value with spaces and \\\\ backslashes\nduplicate=first\nduplicate=second\n`;\n\n// 1. Basic key-value parsing\nconst simpleObject = getProperties(fileContent);\nconsole.log('Simple object:', simpleObject);\n// Expected: { hello: 'world', 'foo:bar': '', 'key.with.escapes': 'value with spaces and \\ backslashes', duplicate: 'second' }\n\n// 2. Lossless parsing with full data model\nconst properties = new Properties(fileContent);\nconsole.log('\\nLossless Nodes:');\nfor (const node of properties.nodes) {\n  switch (node.type) {\n    case PropertiesNodeType.PROPERTY:\n      console.log(`PROPERTY: ${node.key} = ${node.value}`);\n      break;\n    case PropertiesNodeType.COMMENT:\n      console.log(`COMMENT: ${node.body}`);\n      break;\n    case PropertiesNodeType.BLANK:\n      console.log('BLANK LINE');\n      break;\n  }\n}\n\n// 3. Editing properties\nconst editor = new PropertiesEditor(fileContent);\neditor.upsert('new_key', 'new_value');\neditor.delete('duplicate', { occurrence: 'first' }); // Delete the first 'duplicate'\neditor.update('hello', 'updated_world');\n\nconsole.log('\\nEdited properties:');\nconsole.log(editor.format());\n","lang":"typescript","description":"This quickstart demonstrates the core functionalities: `getProperties` for simple key-value extraction, `Properties` for lossless parsing and node inspection, and `PropertiesEditor` for modifying entries while preserving formatting."},"warnings":[{"fix":"Update your Webpack configuration or import statements to use `properties-file/bundler/webpack`.","message":"The Webpack loader export path changed from `properties-file/webpack-loader` to `properties-file/bundler/webpack`.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Review the migration guide for v5.0.0. Use `getProperties()` for simple key-value object conversion. For advanced use cases, interact with `Properties` via its `nodes` array and `format()` method, leveraging new options like `deduplicateKeys`.","message":"Version 5.0.0 introduced a significant architectural change to a lossless data model for the `Properties` class. This means every element (properties, comments, blank lines, whitespace, duplicate keys) is preserved as typed nodes. While this enables exact reconstruction and powerful transformations, code directly manipulating the internal structure of `Properties` instances or expecting a simple key-value object from `new Properties()` will break.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"To delete the first occurrence of a duplicate key, use `editor.delete(key, { occurrence: 'first' })`.","message":"When deleting duplicate keys, the default behavior of `delete()` removes the *last* occurrence. If you need to remove the first or a specific occurrence, you must explicitly use the `occurrence` option.","severity":"gotcha","affected_versions":">=5.0.2"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Change your import statement to `import { PropertiesEditor } from 'properties-file/editor'`.","cause":"Attempting to import `PropertiesEditor` from the root `properties-file` module instead of its specific subpath.","error":"TypeError: (0 , properties_file_1.PropertiesEditor) is not a constructor"},{"fix":"Update the import or configuration path for the Webpack loader to `properties-file/bundler/webpack`.","cause":"Using the old Webpack loader path which was changed in v4.0.0.","error":"Module not found: Error: Can't resolve 'properties-file/webpack-loader' in '...' OR Cannot find module 'properties-file/webpack-loader'"},{"fix":"For basic key-value access, use `getProperties()`. For the `Properties` class (v5+), interact with its `nodes` array for granular control and use `format()` to generate output, or refer to TSDoc for available methods on the lossless data model.","cause":"Attempting to use methods or properties on the `Properties` class that existed in v3.x or prior, or expecting it to behave like a simple key-value object after v5.0.0's lossless model change.","error":"Property 'someMethod' does not exist on type 'Properties'."}],"ecosystem":"npm"}