hoconfmt

Opinionated HOCON formatter - zero configuration, one way to format.

Philosophy

Like Standard.js for JavaScript - no configuration, no debates. One way to format HOCON files.

Installation

# npm
npm install hoconfmt

# yarn
yarn add hoconfmt

# pnpm
pnpm add hoconfmt

# global install for CLI
npm install -g hoconfmt

Usage

CLI

# Check if files are formatted (validates without modifying)
hoconfmt --check file.conf

# Check multiple files with glob pattern
hoconfmt --check "src/**/*.conf"

# Check all .conf files in current directory
hoconfmt --check "*.conf"

# Check all .conf files in directory (recursive)
hoconfmt --check src/

# Format files in-place (overwrites)
hoconfmt --write file.conf

# Format multiple files with glob pattern
hoconfmt --write "src/**/*.conf"

# Format all .conf files in directory (recursive)
hoconfmt --write src/

# Show help
hoconfmt --help

# Show version
hoconfmt --version

Glob patterns support:

• * - matches any characters except path separator
• ** - matches any characters including path separator (recursive)
• ? - matches single character
• {a,b} - matches either pattern

Exit codes:

• 0 - All files are formatted correctly (check) or formatted successfully (write)
• 1 - Some files need formatting, errors occurred, or no mode specified

API

import { check, format } from 'hoconfmt';

// Check if HOCON string is formatted correctly
const isFormatted = check('key = "value"');
console.log(isFormatted); // true or false

// Format HOCON string
const formatted = format('key="value"');
console.log(formatted); // 'key = "value"\n'

CommonJS

const { check, format } = require('hoconfmt');

const formatted = format('key = "value"');

Browser (UMD)

<script src="https://unpkg.com/hoconfmt/dist/hoconfmt.umd.js"></script>
<script>
  const formatted = hoconfmt.format('key = "value"');
</script>

Docker

# Check a file
docker run --rm -v $(pwd):/data ghcr.io/jojoee/hoconfmt --check /data/file.conf

# Check all .conf files in a directory
docker run --rm -v $(pwd):/data ghcr.io/jojoee/hoconfmt --check /data/

# Format a file
docker run --rm -v $(pwd):/data ghcr.io/jojoee/hoconfmt --write /data/file.conf

Formatting Rules

These rules are not configurable - that's the point!

| Rule | Value | |------|-------| | Indentation | 2 spaces | | Key-value separator | = with spaces (key = value) | | Brace style | Same line (key {) | | Comments | Normalized to // style, indented to match scope | | Trailing whitespace | Removed | | Blank lines | Preserved (max 1 between elements and comments) | | End of file | Single newline | | String quotes | Double quotes | | Array style | Single line if < 80 chars | | Value concatenation | Combined into single quoted string (60 seconds → "60 seconds") | | Substitution extension | Space preserved (${ref} { }) | | Triple-quoted strings | Content preserved without extra spacing |

API Reference

check(input: string): boolean

Check if a HOCON string is formatted correctly.

check('key = "value"\n');  // true
check('key="value"');      // false (missing spaces)

format(input: string): string

Format a HOCON string according to the opinionated rules.

format('key="value"');
// Returns: 'key = "value"\n'

HOCON Features Supported

• Key-value pairs with = or :
• Nested objects with {}
• Arrays with []
• Comments (// and #)
• Include statements
• Variable substitution (${path} and ${?path})
• Triple-quoted strings ("""...""")
• Concatenation
• Dotted key paths (server.host = "localhost")

Integration

Pre-commit Hook

# .husky/pre-commit
npx hoconfmt --check "src/**/*.conf"

VS Code Task

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Check HOCON",
      "type": "shell",
      "command": "npx hoconfmt --check src/"
    }
  ]
}

CI/CD

# GitHub Actions
- name: Check HOCON formatting
  run: npx hoconfmt --check "src/**/*.conf"

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Build
npm run build

# Build CLI
npm run build:cli

# Lint
npm run lint

# Run locally

# Check a single file
node bin/hoconfmt.js --check resource/all-cases.conf

# Check entire resource folder
node bin/hoconfmt.js --check resource/

# Format a single file (writes changes)
node bin/hoconfmt.js --write resource/all-cases.conf

# Format entire resource folder (writes changes)
node bin/hoconfmt.js --write resource/

TODO

• [ ] Add Mutation test

Related

• HOCON Specification
• pyhocon - Python HOCON parser
• Standard.js - Inspiration for zero-config philosophy