Universal Config Converter (UCC)

One tool to convert between .yaml, .json, .toml, .xml, .ini, and .env seamlessly.

Features

• 🔄 Convert between YAML, JSON, TOML, XML, INI, and ENV formats
• 💻 Use as CLI tool or Web UI
• 🌐 REST API for programmatic access
• 📦 Use as Node.js library
• 🎨 Pretty printing and formatting options
• 🔑 Sort keys alphabetically
• 🌲 Nested object support (with ENV using underscore notation)
• ⚡ Fast and lightweight
• 🔌 Plugin architecture - easily add custom formats
• 🖱️ Drag & drop file upload
• 🔴 Live preview with real-time conversion
• 📋 Copy to clipboard
• 📥 Batch conversion support

From Source

git clone https://github.com/atomicman57/universal-config-converter
cd universal-config-converter
npm install
npm run build

Usage

Web UI

Start the web server:

npm start
# or
npm run start:server

Then open your browser to http://localhost:3000

Features:

• Dual editor layout with live preview
• Drag & drop file upload
• Copy/paste text directly
• Batch conversion for multiple files
• Download converted files
• Real-time conversion as you type

CLI Usage

Convert Files

# Basic conversion
ucc convert config.json config.yaml

# With options
ucc convert config.yaml config.json --pretty --sort

# Custom indentation
ucc convert config.json config.yaml --indent 4

Parse and Display

# Parse and display in JSON
ucc parse config.yaml

# Parse and display in specific format
ucc parse config.json --format yaml

Library Usage

import { UniversalConfigConverter } from 'universal-config-converter';

const converter = new UniversalConfigConverter();

// Convert string content
const yaml = converter.convert(jsonString, 'json', 'yaml', {
  pretty: true,
  indent: 2,
  sort: true
});

// Convert files
converter.convertFile('config.json', 'config.yaml', {
  pretty: true,
  sort: true
});

// Parse config
const data = converter.parse(yamlString, 'yaml');

// Stringify config
const json = converter.stringify(data, 'json', { pretty: true });

API Usage

The web server exposes a REST API:

Convert Endpoint

POST /api/convert
Content-Type: application/json

{
  "content": "database:\n  host: localhost",
  "fromFormat": "yaml",
  "toFormat": "json",
  "options": {
    "pretty": true,
    "indent": 2,
    "sort": false
  }
}

Response:

{
  "result": "{\n  \"database\": {\n    \"host\": \"localhost\"\n  }\n}"
}

Batch Convert Endpoint

POST /api/convert/batch
Content-Type: multipart/form-data

files: [file1.json, file2.yaml]
toFormat: toml
options: {"pretty": true}

Get Supported Formats

GET /api/formats

Format Examples

JSON

{
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "mydb"
  },
  "server": {
    "port": 3000,
    "host": "0.0.0.0"
  },
  "debug": true
}

YAML

database:
  host: localhost
  port: 5432
  name: mydb
server:
  port: 3000
  host: 0.0.0.0
debug: true

TOML

debug = true

[database]
host = "localhost"
port = 5432
name = "mydb"

[server]
port = 3000
host = "0.0.0.0"

ENV

DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_NAME=mydb
SERVER_PORT=3000
SERVER_HOST=0.0.0.0
DEBUG=true

XML

<?xml version="1.0" encoding="UTF-8"?>
<config>
  <database>
    <host>localhost</host>
    <port>5432</port>
    <name>mydb</name>
  </database>
  <server>
    <port>3000</port>
    <host>0.0.0.0</host>
  </server>
  <debug>true</debug>
</config>

INI

[database]
host = localhost
port = 5432
name = mydb

[server]
port = 3000
host = 0.0.0.0

[settings]
debug = true

Format-Specific Notes

ENV Format

• Nested objects use underscore notation (e.g., DATABASE_HOST → database.host)
• Keys are automatically converted to SCREAMING_SNAKE_CASE
• Values with spaces or special characters are automatically quoted
• Arrays and objects are stored as JSON strings

XML Format

• Root element is automatically handled during conversion
• Attributes are merged into the parent object
• Arrays are properly detected and converted

INI Format

• Uses section headers for nested objects (e.g., [section])
• Supports key-value pairs with = delimiter
• Widely used for configuration files (Git, PHP, Windows apps)
• Nested sections use dot notation

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | pretty | boolean | false | Pretty print output (where applicable) | | indent | number | 2 | Indentation size for pretty printing | | sort | boolean | false | Sort keys alphabetically |

CLI Options

• --pretty, -p: Pretty print output (where applicable)
• --indent <number>, -i: Set indentation size (default: 2)
• --sort, -s: Sort keys alphabetically
• --format <format>, -f: Output format for parse command

Development

Setup

npm install

Build

npm run build

Run Tests

npm test

Development Mode

# Watch mode for TypeScript compilation
npm run dev

# In another terminal, start the server
npm run start:server

Project Structure

github-backdate/
├── src/
│   ├── core/                    # Core converter library
│   │   ├── index.ts            # Main converter class
│   │   ├── types.ts            # Type definitions
│   │   └── converters/         # Format converters
│   │       ├── json.ts
│   │       ├── yaml.ts
│   │       ├── toml.ts
│   │       └── env.ts
│   ├── cli.ts                  # CLI implementation
│   └── server.ts               # Web server
├── public/                     # Static web UI files
│   ├── index.html
│   ├── styles.css
│   └── app.js
├── tests/                      # Test files
│   └── converter.test.ts
└── dist/                       # Compiled output

Examples

Convert JSON to YAML

Input (config.json):

{
  "app": {
    "name": "MyApp",
    "version": "1.0.0"
  }
}

Command:

ucc convert config.json config.yaml --pretty

Output (config.yaml):

app:
  name: MyApp
  version: 1.0.0

Convert ENV to JSON

Input (.env):

APP_NAME=MyApp
APP_VERSION=1.0.0
DATABASE_HOST=localhost
DATABASE_PORT=5432

Command:

ucc convert .env config.json --pretty --sort

Output (config.json):

{
  "app": {
    "name": "MyApp",
    "version": "1.0.0"
  },
  "database": {
    "host": "localhost",
    "port": 5432
  }
}

Programmatic Usage

import { UniversalConfigConverter } from 'universal-config-converter';

const converter = new UniversalConfigConverter();

// Example 1: Convert between formats
const yamlConfig = `
database:
  host: localhost
  port: 5432
`;

const jsonConfig = converter.convert(yamlConfig, 'yaml', 'json', {
  pretty: true,
  indent: 2
});

console.log(jsonConfig);

// Example 2: Parse and manipulate
const data = converter.parse(yamlConfig, 'yaml');
data.database.port = 3306; // Modify the data

const toml = converter.stringify(data, 'toml');
console.log(toml);

// Example 3: File conversion
converter.convertFile('input.yaml', 'output.json', {
  pretty: true,
  sort: true
});

// Example 4: Query supported formats
console.log(converter.getSupportedFormats()); 
// Output: ['json', 'yaml', 'toml', 'env', 'xml']

console.log(converter.getSupportedExtensions()); 
// Output: ['.json', '.yaml', '.yml', '.toml', '.env', '.xml']

Plugin Architecture

UCC features a powerful plugin architecture that allows you to easily add custom format converters.

Adding a Custom Format

import { BaseConverter, UniversalConfigConverter } from 'universal-config-converter';
import { ConfigData, ConversionOptions, ConfigFormat } from 'universal-config-converter';

// 1. Create your custom converter by extending BaseConverter
class INIConverter extends BaseConverter {
  readonly format: ConfigFormat = 'ini' as ConfigFormat;
  readonly extensions = ['.ini'];

  parse(content: string): ConfigData {
    try {
      // Your parsing logic here
      const ini = require('ini');
      return ini.parse(content);
    } catch (error) {
      this.handleError('parse', error);
    }
  }

  stringify(data: ConfigData, options: ConversionOptions = {}): string {
    try {
      const processedData = this.preprocess(data, options);
      const ini = require('ini');
      return ini.stringify(processedData);
    } catch (error) {
      this.handleError('stringify', error);
    }
  }
}

// 2. Register your converter
const converter = new UniversalConfigConverter();
converter.registerConverter(new INIConverter());

// 3. Use it immediately!
const ini = converter.convert(jsonString, 'json', 'ini');

Benefits of the Architecture

• DRY Principle: Common functionality (sorting, error handling) is inherited from BaseConverter
• SOLID Design: Clean separation of concerns with strategy pattern
• Easy Extension: Add new formats with ~30 lines of code
• Type Safe: Full TypeScript support
• Automatic Integration: File extension detection, format validation, and error messages work automatically

## Deployment

### Deploy Web UI

#### Vercel/Netlify

1. Build the project: `npm run build`
2. Set the output directory to `dist` and public directory to `public`
3. Configure the start command: `node dist/server.js`

#### Docker

```dockerfile
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install --production
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "start"]

Build and run:

docker build -t universal-config-converter .
docker run -p 3000:3000 universal-config-converter

Environment Variables

• PORT: Server port (default: 3000)

Troubleshooting

Common Issues

Issue: "Cannot detect format from extension"

• Make sure your file has a valid extension (.json, .yaml, .yml, .toml, .xml, .ini, or .env)

Issue: "Failed to parse [FORMAT]"

• Verify your input file has valid syntax for the specified format
• Use online validators to check your config syntax

Issue: Port already in use

• Change the port: PORT=8080 npm start

Getting Help

If you encounter any issues:

1. Check the error message in the console
2. Verify your input format is valid
3. Try with a simpler config first
4. Check the examples in this README

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Supported Formats

| Format | Extensions | Description | |--------|-----------|-------------| | JSON | .json | JavaScript Object Notation | | YAML | .yaml, .yml | YAML Ain't Markup Language | | TOML | .toml | Tom's Obvious, Minimal Language | | XML | .xml | eXtensible Markup Language | | INI | .ini | INI Configuration Format | | ENV | .env | Environment Variables |

Acknowledgments

Built with:

• js-yaml - YAML parser
• @iarna/toml - TOML parser
• xml2js - XML parser
• ini - INI parser
• Commander.js - CLI framework
• Express - Web server
• TypeScript - Type safety

Made with ❤️ | Report Issues