properties-file
Advanced tools
The properties-file npm package allows you to read, write, and manipulate .properties files, which are commonly used for configuration settings in Java applications. This package provides a simple API to handle these files in a Node.js environment.
Read properties file
This feature allows you to read a .properties file and parse its contents into a JavaScript object. The `read` method takes the file path as an argument and returns an object with key-value pairs.
const properties = require('properties-file');
const config = properties.read('config.properties');
console.log(config);Write properties file
This feature allows you to write a JavaScript object to a .properties file. The `write` method takes the file path and the object to be written as arguments.
const properties = require('properties-file');
const config = { key1: 'value1', key2: 'value2' };
properties.write('config.properties', config);Update properties file
This feature allows you to update an existing .properties file. You can read the file into a JavaScript object, modify the object, and then write it back to the file.
const properties = require('properties-file');
let config = properties.read('config.properties');
config.key3 = 'value3';
properties.write('config.properties', config);The properties-reader package provides similar functionality for reading and manipulating .properties files. It offers a more fluent API for accessing properties and supports nested properties. Compared to properties-file, it may be more user-friendly for complex configurations.
The node-properties package is another alternative for handling .properties files. It provides basic read and write capabilities but lacks some of the advanced features found in properties-file. It is a simpler option for straightforward use cases.
The config package is a more comprehensive solution for managing configuration files in Node.js applications. It supports multiple file formats, including .properties, JSON, and YAML. While it offers more features, it may be overkill for simple .properties file manipulation.
.properties file parser, JSON converter and Webpack loader.
⚠ in June 2022 we have released version 2 of this package which is not compatible with the previous versions. Make sure to read the documentation before upgrading.
Add the package as a dependency:
npm install properties-file
propertiesToJson allows quick conversion from .properties files to JSON.getProperties returns a Properties object that allows insights into parsing issues such as key collisions.propertiesToJson & getProperties also have a browser-compatible version when passing directly the content of a file using the APIs under properties-file/content.import .properties files directly in your application.We put a lot of effort into adding TSDoc to all our APIs. Please check directly in your IDE if you are unsure how to use certain APIs provided in our examples.
Both APIs (getProperties and propertiesToJson) directly under properties-file depend on fs which means they cannot be used by browsers. If you cannot use fs and already have a .properties file content, the same APIs are available under properties-file/content. Instead of taking the filePath as the first argument, they take content. The example below will use "fs" APIs since they are the most common use cases.
propertiesToJsonThis API is probably the most used. You have a .properties file that you want to open and access like a simple key/value JSON object. Here is how this can be done with a single API call:
import { propertiesToJson } from 'properties-file'
console.log(propertiesToJson('hello-world.properties'))
Output:
{ hello: 'hello', world: 'world' }
If you cannot use fs and already have the content of a .properties file, your code would look like this instead:
import { propertiesToJson } from 'properties-file/content'
// ...some code to get the .properties file content into a variable called `propertiesFileContent`
console.log(propertiesToJson(propertiesFileContent))
getProperties (advanced use case)Java's implementation of Properties is quite resilient. In fact, there are only two ways an exception can be thrown:
\u) Unicode escape character is malformed.This means that almost all files will be valid.
But what about a file that has duplicate keys? Duplicate keys have no reason to exist and they probably should have thrown errors as well but instead Java decided to simply overwrite the value with the latest occurrence in a file.
So how can we know if there were duplicate keys if we want to log some warnings? Simply by using getProperties which will return all the data that was used to parse the content. Here is an example on how it can be used:
# collisions-test.properties
hello: hello1
world: world1
world: world2
hello: hello2
world: world3
import { getProperties } from 'properties-file'
const properties = getProperties('assets/tests/collisions-test.properties')
properties.collection.forEach((property) => {
console.log(`${property.key} => '${property.value}'`)
})
/**
* Outputs:
*
* hello => 'hello2'
* world => 'world3'
*
*/
const keyCollisions = properties.getKeyCollisions()
keyCollisions.forEach((keyCollision) => {
console.warn(
`Found a key collision for key '${
keyCollision.key
}' on lines ${keyCollision.startingLineNumbers.join(
', '
)} (will use the value at line ${keyCollision.getApplicableLineNumber()}).`
)
})
/**
* Outputs:
*
* Found a key collision for key 'hello' on lines 1, 4 (will use the value at line 4).
* Found a key collision for key 'world' on lines 2, 3, 5 (will use the value at line 5).
*
*/
If you would like to import .properties directly using import, this package comes with its own Webpack file loader located under properties-file/webpack-loader. Here is an example of how to configure it:
// webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.properties$/i,
use: [
{
loader: 'properties-file/webpack-loader',
},
],
},
],
},
}
As soon as you configure Webpack, the .properties type should be available in your IDE when using import. If you ever need to add it manually, you can add a *.properties type declaration file at the root of your application, like this:
// properties-file.d.ts
declare module '*.properties' {
const properties: { readonly [key: string]: string };
export default properties;
}
By adding these configurations you should now be able to import directly .properties files just like this:
import helloWorld from './hello-world.properties'
console.dir(helloWorld)
Output:
{ "hello": "world" }
.properties file package?There are probably over 20 similar packages available but:
Unfortunately the .properties file specification is not well documented. One reason for this is that it was originally used in Java to store configurations. Most applications will handle this using JSON, YAML or other modern formats today because the formats are more flexible.
.properties files?While many options exists today to handle configurations, .properties file remain one of the best option to store localizable strings (also known as messages). On the Java side, PropertyResourceBundle is how most implementations handle localization today. Because of its simplicity and maturity, .properties files remain one of the best options today when it comes to internationalization (i18n):
| File format | Key/value based | Supports inline comments | Built for localization | Good linguistic tools support |
|---|---|---|---|---|
.properties | Yes | Yes | Yes (Resource Bundles) | Yes |
JSON | No (can do more) | No (requires JSON5) | No | Depends on the schema |
YAML | No (can do more) | Yes | No | Depends on the schema |
By having good JavaScript/TypeScript support for .properties files, it provides more options when it comes to i18n.
Basically our goal was to offer parity with the Java implementation, which is the closest thing to a specification .properties file have. Here is in a nutshell the logic behind this package:
LineObjects by combining multi-line properties and removing trailing backslashPropertyObjects from LineObjects that combined all lines of a propertyPropertiesObject that will include all PropertyObjects while removing collisionsJust like Java, if a Unicode escaped characters (\u) is malformed, it will throw an error. But of course, we do not recommend using Unicode escaped characters but rather UTF-8 encoding that supports more characters.
Properties class documentationPropertyResourceBundle documentationThanks to @calibr, the creator of properties-file version 1.0, for letting us use the https://www.npmjs.com/package/properties-file package name. We hope that it will make it easier to find our package.
FAQs
.properties file parser, editor, formatter and Webpack loader.
The npm package properties-file receives a total of 0 weekly downloads. As such, properties-file popularity was classified as not popular.
We found that properties-file demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
The Socket Research Team investigates a malicious npm package that appears to be an Advcash integration but triggers a reverse shell during payment success, targeting servers handling transactions.
Security Fundamentals
The Socket Threat Research Team uncovers how threat actors weaponize shell techniques across npm, PyPI, and Go ecosystems to maintain persistence and exfiltrate data.
Security News
At VulnCon 2025, NIST scrapped its NVD consortium plans, admitted it can't keep up with CVEs, and outlined automation efforts amid a mounting backlog.