toml-x

CLI tool and library to merge TOML files using deep merge strategy.

This simple project uses smol-toml to parse and stringify TOML files and defu to merge them.

Installation

# Install globally for CLI usage
npm i -g toml-x

# Or use with npx
npx toml-x [...]

# Install as a library
npm i toml-x

CLI Usage

toml-x <command> [flags] [...files]

Commands

merge

Merge multiple TOML files where later files override earlier ones.

# Merge two files and output to stdout
toml-x merge base.toml overrides.toml

# Save merged output to a new file
toml-x merge base.toml overrides.toml > new_config.toml

# Merge multiple files
toml-x merge base.toml overrides1.toml overrides2.toml > final.toml

# Format numbers as floats
toml-x merge --numbers-as-float base.toml overrides.toml

# Don't add the auto-generated comment at the top
toml-x merge --skip-comment base.toml overrides.toml

Flags

• --numbers-as-float - Preserve float formatting (e.g., 1.0 instead of 1)
• --skip-comment - Skip adding the auto-generated comment at the top
• --help, -h - Show help message

How it works

The tool:

1. Parses all TOML files using smol-toml
2. Merges them using defu with deep merge strategy
3. Outputs the merged TOML to stdout

Library Usage

You can also use toml-x as a library in your Node.js projects:

import { merge } from 'toml-x'

const base = `
[server]
host = "localhost"
port = 8080
`

const override = `
[server]
port = 3000
debug = true
`

// Merge configs
const result = merge([base, override])
console.log(result)
// Output:
// # This file is autogenerated by toml-x
//
// [server]
// host = "localhost"
// port = 3000
// debug = true

// With options
const result2 = merge([base, override], {
  numbersAsFloat: true      // Format numbers as floats
})

API

merge(configs: string[], options?: { numbersAsFloat?: boolean }): string

Merge multiple TOML file contents using deep merge strategy.

Parameters:

• configs - Array of TOML file contents as strings
• options - Optional merge options
  • numbersAsFloat?: boolean - Format numbers as floats (default: false)

Returns: Merged TOML as a string

Throws: Error if configs array is empty or if any config has invalid TOML syntax

Development

# Install dependencies
pnpm install

# Build
pnpm run build

# Run tests
pnpm test

# Run tests once
pnpm test:run

License

ISC