DEV Community

Cover image for Stop Hand-Copying Java .properties Into Your JS Stack
Emre YARTAŞI
Emre YARTAŞI

Posted on

Stop Hand-Copying Java .properties Into Your JS Stack

#javascript #typescript #cli #java

Stop Hand-Copying Java .properties Into Your JS Stack

If you have ever straddled a Java backend and a JavaScript frontend, you have probably stared at a .properties file and thought: I just need this as JSON—or as a module I can import.

You could transcribe keys by hand. You could write a one-off script that breaks on the first escaped newline. Or you could use a small tool that speaks the real Java properties format and hands you JavaScript, TypeScript, or JSON in a shape you control.

This post introduces @yartasdev/properties-to-js—a CLI and library that does exactly that, with options for nesting, flattening, key casing, and readable formatting.

The problem in one sentence

.properties files are a lingua franca on the JVM; modern Node and browser code usually want structured JS or JSON. Bridging the two should be boring, reliable, and repeatable.

What is a .properties file, really?

Java’s classic configuration format looks deceptively simple:

  • Lines starting with # or ! are comments.
  • Each entry is typically key=value or key:value.
  • Values can span lines when you end a line with \.
  • Escape sequences like \n, \r, \t, and Unicode \uXXXX are part of the spec.

That last part matters. “Almost parsing” properties with a few split('=') lines works until it does not—until someone adds a multiline value, a colon in the right place, or an escape sequence your regex did not anticipate.

properties-to-js is built around treating the input as a real properties document, then emitting output your stack can consume without surprises.

What you get out of the box

Multiple output formats

Point the tool at an input file and choose an output path whose extension is .js, .ts, or .json. The extension drives the format. No separate flags to remember for “mode”—the filename is the contract.

Nested structure by default

Keys with dot segments such as app.name or database.host naturally become nested objects:

app.name=MyApp
database.port=5432
Enter fullscreen mode Exit fullscreen mode

becomes a tree:

{
  app: {
    name: 'MyApp',
  },
  database: {
    port: '5432',
  },
}
Enter fullscreen mode Exit fullscreen mode

That mirrors how many teams think about configuration: sections and fields, not a flat bag of strings—unless you explicitly want the flat bag.

Optional flattening with a custom delimiter

Some systems, environment-variable conventions, or legacy integrations prefer a single level of keys. Enable flattening and pick a delimiter (for example _):

properties-to-js -i config.properties -o config.js --flatted -d "_"
Enter fullscreen mode Exit fullscreen mode

You might get app_name, database_port, and so on—predictable and easy to grep or map into other tools.

Case transformation for keys

Need uppercase or lowercase keys for consistency with APIs, env vars, or team style? Flags like --uppercase and --lowercase apply to the key material so you do not have to post-process with another script.

CLI and programmatic API

Use it as a global or npx-invoked CLI (properties-to-js when installed globally), or import { Converter } from '@yartasdev/properties-to-js' and call Converter.convert(options) from your own build scripts, tests, or scaffolding tools.

Prettier-formatted output

Generated files are run through Prettier so diffs stay readable and your repository does not fill with accidental formatting noise every time someone regenerates config.

Installation and first run

Global install (gives you the properties-to-js command):

npm install -g @yartasdev/properties-to-js
Enter fullscreen mode Exit fullscreen mode

Project dependency:

npm install @yartasdev/properties-to-js
Enter fullscreen mode Exit fullscreen mode

No install, one-off run (note the scoped package name for npx):

npx @yartasdev/properties-to-js -i input.properties -o output.js
Enter fullscreen mode Exit fullscreen mode

If your shell mangles flags after npx, this pattern is your friend:

npx @yartasdev/properties-to-js -- -i input.properties -o output.js
Enter fullscreen mode Exit fullscreen mode

When the package is installed locally in a project, you can also run:

npx properties-to-js -i input.properties -o output.js
Enter fullscreen mode Exit fullscreen mode

A concrete walkthrough

Imagine config.properties:

# Application Configuration
app.name=MyApp
app.version=1.0.0
app.debug=true

# Database Settings
database.host=localhost
database.port=5432
database.name=mydb
Enter fullscreen mode Exit fullscreen mode

Default (nested) output is easy to read and maps cleanly to nested types in TypeScript if you emit .ts or wrap the object in your app.

Flattened with _:

properties-to-js -i config.properties -o config.js --flatted -d "_"
Enter fullscreen mode Exit fullscreen mode

You get one object with keys like app_name, database_host—useful when you must not assume nesting in downstream code.

Uppercase nested keys:

properties-to-js -i config.properties -o config.js --uppercase
Enter fullscreen mode Exit fullscreen mode

Sections become APP, DATABASE, and so on—handy when your style guide or integration expects shouting keys.

Programmatic usage

For repeatable pipelines or custom tooling, call the converter from Node:

import { Converter } from '@yartasdev/properties-to-js';

await Converter.convert({
  input: 'config.properties',
  output: 'config.js',
  flatted: false,
  uppercase: false,
  lowercase: false,
  delimiter: '.',
});
Enter fullscreen mode Exit fullscreen mode

Swap output to config.ts or config.json when that is what your build expects.

CLI reference (quick)

Option Short Description Default
--input -i Path to the .properties file Required
--output -o Output path (extension selects format) Required
--delimiter -d Delimiter used when keys are flattened .
--flatted -f Flatten nested keys to a single level false
--uppercase -u Uppercase keys false
--lowercase -l Lowercase keys false

When this tool shines

  1. Backend and frontend share a source of truth. The JVM side keeps canonical .properties; your Vite, Next, or Node service generates checked-in or CI-built JS/JSON from the same file.

  2. You are documenting or prototyping. Turn a small sample properties file into JSON for an OpenAPI example, a Storybook mock, or a README snippet without manual transcription errors.

  3. You want CI to own regeneration. A single command in GitHub Actions (or any runner) refreshes artifacts before tests or deploys—no “forgot to update the JSON” drift.

  4. You value boring correctness. Comments, escapes, and multiline rules exist for a reason; a dedicated converter is less exciting than a bespoke five-line parser—and that is the point.

Honest scope

This tool solves properties → JS/TS/JSON with sensible structural options. It is not a full configuration platform: it does not merge profiles, resolve Spring placeholders, or replace your secrets manager. If your properties layer does heavy macro expansion, you may still need a JVM-side step—or a documented subset of keys—for the JS output to match production exactly.

Where it fits is the straightforward path: standard files, clear keys, predictable output.

Try it and shape it

If you hit an edge case—a surprising escape, a Unicode edge, a key pattern you need supported—open an issue with a minimal .properties sample. Real files beat abstract specs every time.

Takeaway

@yartasdev/properties-to-js exists so you spend less time being a human clipboard between JVM config and JS-friendly data. One command (or one await Converter.convert(...)) gives you nested or flat structures, optional casing, and Prettier-clean output—so you can focus on the application, not on re-parsing = for the hundredth time.

If this sounds useful for your stack, install it, run it on a properties file you already have, and see whether the generated module drops straight into your project. If it does, that is the whole story—and a good reason to star the repo or leave a note on dev.to about how you wired it in.

Top comments (0)