Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
getProperties
✓ import { getProperties } from 'properties-file'
✗ const { getProperties } = require('properties-file')
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.
Properties
✓ import { Properties } from 'properties-file/parser'
✗ import { Properties } from 'properties-file'
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.
PropertiesEditor
✓ import { PropertiesEditor } from 'properties-file/editor'
✗ import { PropertiesEditor } from 'properties-file'
The `PropertiesEditor` for modifying properties files while preserving formatting is found in the `/editor` subpath. Importing from the root module directly is incorrect.
Webpack Loader
✓ import 'properties-file/bundler/webpack'
✗ import 'properties-file/webpack-loader'
Since v4.0.0, the Webpack loader path was moved and renamed to `properties-file/bundler/webpack` for consistency with other bundler integrations.
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.
import { readFileSync } from 'node:fs';
import { getProperties, Properties, PropertiesNodeType } from 'properties-file/parser';
import { PropertiesEditor } from 'properties-file/editor';
// Example .properties content
const fileContent = `
# This is a comment
hello=world
foo:bar\n\r
key.with.escapes=value with spaces and \\ backslashes
duplicate=first
duplicate=second
`;
// 1. Basic key-value parsing
const simpleObject = getProperties(fileContent);
console.log('Simple object:', simpleObject);
// Expected: { hello: 'world', 'foo:bar': '', 'key.with.escapes': 'value with spaces and \ backslashes', duplicate: 'second' }
// 2. Lossless parsing with full data model
const properties = new Properties(fileContent);
console.log('\nLossless Nodes:');
for (const node of properties.nodes) {
switch (node.type) {
case PropertiesNodeType.PROPERTY:
console.log(`PROPERTY: ${node.key} = ${node.value}`);
break;
case PropertiesNodeType.COMMENT:
console.log(`COMMENT: ${node.body}`);
break;
case PropertiesNodeType.BLANK:
console.log('BLANK LINE');
break;
}
}
// 3. Editing properties
const editor = new PropertiesEditor(fileContent);
editor.upsert('new_key', 'new_value');
editor.delete('duplicate', { occurrence: 'first' }); // Delete the first 'duplicate'
editor.update('hello', 'updated_world');
console.log('\nEdited properties:');
console.log(editor.format());
Errors
Common errors & fixes
TypeError: (0 , properties_file_1.PropertiesEditor) is not a constructor
Attempting to import `PropertiesEditor` from the root `properties-file` module instead of its specific subpath.
fixChange your import statement to `import { PropertiesEditor } from 'properties-file/editor'`. Module not found: Error: Can't resolve 'properties-file/webpack-loader' in '...' OR Cannot find module 'properties-file/webpack-loader'
Using the old Webpack loader path which was changed in v4.0.0.
fixUpdate the import or configuration path for the Webpack loader to `properties-file/bundler/webpack`.
Property 'someMethod' does not exist on type 'Properties'.
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.
fixFor 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.
Audit
Dependencies
No dependency data recorded yet.