Application Configuration

npm install -g @yartasdev/properties-to-js

npm install @yartasdev/properties-to-js

npx @yartasdev/properties-to-js -i input.properties -o output.js -t js

npx @yartasdev/properties-to-js -- -i input.properties -o output.js -t js

also run:

npx properties-to-js -i input.properties -o output.js -t js

JSON only (default type is json, matches .json):

npx @yartasdev/properties-to-js -i input.properties -o output.json

Programmatic Usage

File → file

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

await Converter.convertForFile({
  input: 'config.properties',
  output: 'config.js',
  type: 'js',
  flatted: false,
  uppercase: false,
  lowercase: false,
  delimiter: '.',
});

Paths are resolved under process.cwd(). Use type: 'json' | 'js' | 'ts' and an output path whose extension matches.

String → string (no filesystem)

Ideal for HTTP bodies, tests, or generated snippets:

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

const source = 'app.name=Demo\napp.port=3000\n';

const moduleText = await Converter.convertForContent({
  content: source,
  type: 'ts',
  flatted: false,
  delimiter: '.',
  uppercase: false,
  lowercase: false,
});
// moduleText is a Prettier-formatted string (e.g. export default { ... };)

Architecture Decisions & Features

• Nested Structure by Default: Dot-separated keys (app.name, database.host) automatically resolve into hierarchical objects, mirroring frontend configuration patterns.
• Optional Flattening: Use --flatted and --delimiter to collapse nested keys into a single level (e.g., app_name, database_port) for environment variable mapping or legacy integrations.
• Case Transformation: --uppercase and --lowercase flags apply exclusively to key material, ensuring consistency with API contracts or team style guides without post-processing.
• Prettier Integration: All generated output passes through Prettier, guaranteeing deterministic formatting, readable diffs, and zero accidental whitespace noise in version control.

Pitfall Guide

1. Output Extension/Type Mismatch: The --type flag must match the output file extension (e.g., -t js requires .js, -t ts requires .ts). Mismatched extensions cause runtime import failures or TypeScript compiler errors.
2. Naive Regex Parsing Assumptions: Assuming split('=') or basic regex handles all .properties files leads to silent corruption when encountering \uXXXX Unicode escapes, \ line continuations, or key:value syntax. Always use a spec-compliant parser.
3. Flattening Delimiter Conflicts: Using . or _ as a flattening delimiter without verifying downstream expectations can break environment variable parsers or configuration loaders that reserve those characters for nesting or naming conventions.
4. Ignoring Scope Limitations: This tool converts raw properties to JS/TS/JSON. It does not resolve Spring placeholders (${...}), macro expansions, or secrets manager integrations. Expecting full JVM-side resolution will result in incomplete or broken configuration artifacts.
5. Case Transformation Applied to Values: The --uppercase and --lowercase flags only transform keys. Applying them when values require case sensitivity (e.g., passwords, API tokens, file paths) will corrupt configuration data.
6. CI/CD Regeneration Drift: Failing to automate config regeneration in pipelines leads to "stale JSON" drift. Always include the conversion command in pre-build or pre-deploy steps to ensure frontend artifacts match the canonical backend properties.

Deliverables

📘 Integration Blueprint

A reference architecture for embedding @yartasdev/properties-to-js into monorepos and CI/CD pipelines:

• Source of Truth: JVM backend maintains canonical .properties files.
• Build Step: Pre-commit hook or CI job runs properties-to-js to generate .js/.ts/.json artifacts.
• Consumption: Frontend/Node services import generated modules directly, eliminating manual sync.
• Validation: TypeScript strict mode + Prettier CI check ensure type safety and formatting consistency.

✅ Pre-Conversion Checklist

• Verify .properties file follows Java spec (comments, escapes, multiline continuations).
• Confirm output extension matches --type flag (json, js, or ts).
• Decide on structure: nested (default) vs flattened (--flatted -d "_").
• Apply case transformation only if downstream consumers require it (--uppercase/--lowercase).
• Add regeneration command to CI pipeline (package.json scripts or GitHub Actions).
• Validate generated output against TypeScript interfaces or runtime config loaders.

⚙️ Configuration Templates

package.json script example:

"scripts": {
  "generate:config": "properties-to-js -i src/config.properties -o src/config.ts -t ts --uppercase"
}

GitHub Actions snippet:

- name: Generate JS/TS Config
  run: npx @yartasdev/properties-to-js -i config.properties -o src/config.js -t js --flatted -d "_"

Programmatic config object:

const config = {
  input: 'config.properties',
  output: 'config.ts',
  type: 'ts',
  flatted: false,
  delimiter: '.',
  uppercase: false,
  lowercase: false,
};