@onurege3467/zero-config

A powerful, lightweight config loader for Node.js applications. Supports multiple file formats (JSON, YAML, TOML, INI), .env files, environment variables, file watching, validation, optional caching, global config storage, and full TypeScript autocomplete.

Features

• Multi-format support: JSON, YAML, TOML, INI
• Environment integration: .env files and env vars with prefixes
• Global config: System-wide variables stored in ~/.zero-config/global.json
• Watching: Auto-reload on file changes
• Validation: JSON schema-based validation
• Caching: Optional in-memory caching with light-fs
• TypeScript: Full type safety and autocomplete
• CLI: Command-line tools for management
• Autocomplete: Bash completion and dynamic suggestions

Installation

npm install @onurege3467/zero-config

Optional dependencies:

npm install @onurege3467/light-fs  # For caching

Quick Start

import { load } from '@onurege3467/zero-config';

const config = await load('./config.json');
console.log(config.database.url); // Access config

Usage

Loading Config Files

Supports JSON, YAML, TOML, and INI formats. Detected automatically by file extension.

const jsonConfig = await load('./config.json');
const yamlConfig = await load('./config.yaml');
const tomlConfig = await load('./config.toml');
const iniConfig = await load('./config.ini');

Environment Variables

Load .env files or merge env vars with prefixes.

// Load .env file
const config = await load('./config.json', { env: true });

// Use env prefix
const config = await load('./config.json', { envPrefix: 'APP_' });
// APP_PORT becomes config.port

Global Config

Store variables globally for all projects.

# Set global var
zero-config set-global PG_USER myuser

# Get global var
zero-config get-global PG_USER

# Get all
zero-config get-global

Global vars are automatically merged into every load.

TypeScript Autocomplete

Generate interfaces for autocomplete.

# For global config
zero-config generate-types > global.d.ts

# For local config
zero-config generate-types --file ./config.json > local.d.ts

Use in code:

import { GlobalConfig, LocalConfig } from './global.d.ts';
import { load } from '@onurege3467/zero-config';

interface MyConfig extends GlobalConfig, LocalConfig {}

const config = await load<MyConfig>('./config.json');
config.PG_USER; // Autocomplete!

Watching Files

Reload config on changes.

import { watch } from '@onurege3467/zero-config';

const watcher = watch('./config.json', (newConfig) => {
  console.log('Config reloaded:', newConfig);
  // Restart server or update app
});

// Stop watching
watcher.close();

Validation

Validate config against JSON schema.

const config = await load('./config.json', {
  validate: true,
  schema: {
    type: 'object',
    properties: {
      port: { type: 'number', minimum: 1000 },
      debug: { type: 'boolean' }
    },
    required: ['port']
  }
});

Caching

Cache parsed configs for performance (requires light-fs).

const config = await load('./config.json', { cache: true });

CLI Reference

Install globally for CLI:

npm install -g @onurege3467/zero-config

Commands

• zero-config load <file> [options]: Load and print config

  • -e, --env-prefix <prefix>: Env var prefix
  • --env: Load .env file

• zero-config set-global <key> <value>: Set global variable

• zero-config get-global [key]: Get global variables

• zero-config generate-types [--file <path>]: Generate TypeScript interface

• zero-config completion: Generate bash completion script

Bash Autocomplete

Enable tab completion:

zero-config completion >> ~/.bashrc
source ~/.bashrc

Now zero-config <tab> suggests commands, and zero-config get-global <tab> suggests keys.

API Reference

load(configPath, options?)

Asynchronously load config.

• configPath: Path to config file
• options: LoadOptions
• Returns: Promise

loadSync(configPath, options?)

Synchronously load config.

• configPath: Path to config file
• options: LoadOptions
• Returns: T

watch(configPath, callback, options?)

Watch config file for changes.

• configPath: Path to config file
• callback: Function called with updated config
• options: WatchOptions
• Returns: Watcher object with close() method

validate(config, schema)

Validate config against schema.

• config: Config object
• schema: Validation schema
• Returns: ValidationResult

Cache

Class for managing cache.

• get(key): Get cached config
• set(key, config): Set cached config
• clear(): Clear cache
• getStats(): Get cache statistics

Types

• Config: Base config interface
• LoadOptions: Options for loading
• WatchOptions: Options for watching
• ValidationResult: Validation result
• CacheStats: Cache statistics

Examples

Full Example

import { load, watch, validate } from '@onurege3467/zero-config';

interface AppConfig {
  port: number;
  database: {
    url: string;
    poolSize: number;
  };
  features: string[];
}

const config = await load<AppConfig>('./config.json', {
  env: true,
  envPrefix: 'APP_',
  validate: true,
  schema: {
    type: 'object',
    properties: {
      port: { type: 'number' },
      database: { type: 'object' }
    },
    required: ['port']
  }
});

console.log(`Server running on port ${config.port}`);

// Watch for changes
const watcher = watch('./config.json', (newConfig) => {
  console.log('Config updated');
});

Global Config Example

# Set global vars
zero-config set-global DB_HOST localhost
zero-config set-global DB_PORT 5432

# Generate types
zero-config generate-types > global.d.ts

# Use in code
import { GlobalConfig } from './global.d.ts';

interface MyConfig extends GlobalConfig {
  appName: string;
}

const config = await load<MyConfig>('./config.json');
console.log(config.DB_HOST); // Autocomplete works!

Contributing

Contributions welcome! Please open issues or PRs on GitHub.

License

ISC