cfgo

A Go code generator that converts JSON configuration files into type-safe Go structs with environment variable support.

Features

• Type-Safe Configuration: Generate strongly-typed Go structs from JSON config files
• Environment Variables: Load sensitive data from .env files using @ imports
• Variable Interpolation: Reference other config values using ${path.to.value} syntax
• Batch Processing: Convert entire directories of config files at once
• Go Generate Integration: Works seamlessly with go:generate directives
• Zero Runtime Overhead: All parsing happens at build time

Installation

go install github.com/xySaad/cfgo@latest

Quick Start

1. Create a Configuration File

Create a config/config.json file with your configuration:

{
  "@ENV": ".env",
  "address": "0.0.0.0:5051",
  "domain": "https://example.com",
  "database": {
    "host": "localhost",
    "port": 5432,
    "password": "@ENV.DB_PASSWORD"
  },
  "api": {
    "endpoint": "${domain}/api",
    "timeout": 30
  }
}

2. Create an .env File

Store sensitive values in a .env file:

DB_PASSWORD=your_secret_password

3. Generate Go Code

cfgo config

Syntax

Environment Variable Imports

Use @ prefix to import external configuration files:

{
  "@ENV": ".env"
}

Reference values from imported files using @<name>.<key>:

{
  "@ENV": ".env",
  "secret": "@ENV.API_KEY"
}

Variable Interpolation

Reference other values in your configuration using ${path.to.value}:

{
  "baseUrl": "https://example.com",
  "apiUrl": "${baseUrl}/api",
  "endpoints": {
    "users": "${baseUrl}/api/users",
    "posts": "${baseUrl}/api/posts"
  }
}

Nested Objects

Create nested configuration structures:

{
  "server": {
    "host": "localhost",
    "port": 8080,
    "tls": {
      "enabled": true,
      "certPath": "/path/to/cert"
    }
  }
}

This generates:

type Tls struct {
    Enabled  bool
    CertPath string
}

type Server struct {
    Host string
    Port float64
    Tls  Tls
}

type Config struct {
  	Server Server
}
func GetConfig() Config { return config }

Generated Code

For each top-level key in your JSON, cfgo generates:

1. A struct type with properly typed fields
2. A package-level variable initialized with your values
3. A getter function to access the configuration

Example:

// Code generated by github.com/xySaad/cfgo; DO NOT EDIT.
package config

type Database struct {
    Host     string
    Port     float64
    Password string
}

var database = Database{
    Host:     "localhost",
    Port:     5432,
    Password: env_ENV["DB_PASSWORD"], //package level environment map
}

func GetDatabase() Database { return database }

Usage Example

See the example directory for a complete working example.

Command Line Usage

cfgo supports three usage modes:

1. Default Directory Mode

cfgo

• Converts all JSON files in the config/ directory
• Generates Go files in config/generated/
• Package name is derived from the directory name

2. Custom Directory Mode

cfgo <directory>

• Converts all JSON files in the specified directory
• Generates Go files in <directory>/generated/
• Package name is derived from the directory name

Example:

cfgo config
# Processes config/*.json → config/generated/*.go

3. Single File Mode

cfgo <input.json> <output.go>

• Converts a single JSON file to a specific output location

Arguments:

• input.json - Path to your JSON configuration file
• output.go - Path where the generated Go code will be written

Example:

cfgo config/database.json pkg/config/db.go

Note: The package name of the generated code is either the directory name where the file exists or 'main' if the file is in the root directory

Using with go:generate:

//go:generate cfgo config
package main

import "yourmodule/config"

func main() {
    cfg := config.GetDatabase()
    fmt.Println(cfg.Host)
}

Then run:

go generate ./...

Supported Types

same as json.Unmarshal from 'encoding/json'

Environment File Support

Currently supported external file formats:

• ✅ .env files (using godotenv)

Requirements

• Go 1.24.1 or later

Contributing

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

Author

xySaad