configmanager

README

go-config-manager

Per-app configuration stored as JSON in the user config directory. Zero dependencies.

---

For Users

Install

go get github.com/mesopix/go-config-manager

import "github.com/mesopix/go-config-manager"

Usage

tpl := map[string]any{"port": 8080, "debug": true}
c, err := configmanager.LoadAppConfig("myapp", tpl) // always returns a config
if err != nil { ... }

port, _ := c.Get("port")
c.Set("port", 9090)
if err := c.Save(); err != nil { ... }

The file lives at <user config dir>/myapp/config.json; on first run it is created from the template.

Note: JSON numbers come back as float64 from Get.

API Reference

Full API documentation is available on pkg.go.dev.

---

For Developers

Project Structure

.
├── config.go           # Core library: LoadAppConfig, Config, Get, Set, Save
├── config_test.go      # Tests
└── examples/
    └── demo/
        └── main.go     # Runnable demo

Single package at module root, zero external dependencies.

Development Guide

Run tests and static analysis:

go test -v ./...
go vet ./...

Tests use t.TempDir() and override AppData / XDG_CONFIG_HOME / HOME via t.Setenv, so they never touch real user config.

Design Decisions

• No auto-detection of executable name: Renaming the binary would silently create a new config file, losing previous settings. Test binaries would also use different config paths. Multiple binaries in the same project often share one config. The caller explicitly provides appName.
• Re-read after first save: On first run, LoadAppConfig writes the template to disk then reads it back. This ensures numeric types are always float64 (matching subsequent runs), avoiding subtle type mismatches between first and later launches.
• Atomic save: Save() writes to a temp file in the same directory, calls Sync() to flush to disk, then Renames over the target. A crash during save never leaves a half-written config.
• Zero dependencies: Only stdlib (encoding/json, os, path/filepath). Keeps the dependency tree minimal for a utility library.

Release Process

1. Ensure all tests pass: go test -v ./... && go vet ./...

2. Commit all changes to main.

3. Create and push a semantic version tag:

   git tag v0.x.y
   git push origin main --tags
   

4. pkg.go.dev will automatically pick up the new version within minutes.

⚠️ Published tags are immutable — never delete or move them. Use a new version number for any change.

Documentation

Overview

Package configmanager is a tiny JSON-file-backed configuration store.

Index

• type Config
  • func LoadAppConfig(appName string, template map[string]any) (*Config, error)
  • func (c *Config) Get(key string) (any, bool)
  • func (c *Config) Save() error
  • func (c *Config) Set(key string, value any)

Types

type Config

type Config struct {
	// contains filtered or unexported fields
}

Config holds configuration values backed by a JSON file on disk.

func LoadAppConfig

func LoadAppConfig(appName string, template map[string]any) (*Config, error)

LoadAppConfig loads the config for appName. On first run the file is created from template, so a config is always returned unless an I/O or parse error occurs. Values are read back from disk, so numbers are float64.

func (*Config) Get

func (c *Config) Get(key string) (any, bool)

Get returns the value stored under key and whether it exists. JSON numbers unmarshal as float64.

func (*Config) Save

func (c *Config) Save() error

Save writes the current values back to the JSON file atomically. It writes to a temporary file first, syncs to disk, then renames over the target so a crash never leaves a half-written config.

func (*Config) Set

func (c *Config) Set(key string, value any)

Set stores value under key.