npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@rainbow-industries/rainbow-config

v3.2.3

Published

A YAML config file loader

Readme

Rainbow Config

YAML configuration for Node.js — environment-aware, typed getters, and secret substitution.

npm version TypeScript ESM


Table of contents


Features

  • Load per-environment YAML files from a configurable directory
  • Resolve ${SECRET_KEY} placeholders from environment variables or a secrets file
  • Built-in environments with short aliases (dev, test, int, prod)
  • Dot-path access (db.main.port) with optional typed getters
  • Full TypeScript types and ESM-first design

Installation

npm install @rainbow-industries/rainbow-config

Quick start

config/development.yml

db:
  main:
    port: 5432
    host: ${db_host}
    password: ${DB_PASSWORD}
myKey: myValue
anArray:
  - itemOne
  - itemTwo

secrets.development.yml (at project root, or a custom secrets directory)

db_host: db.example.com
DB_PASSWORD: soSecureICantBelieveIt

app.ts

import RainbowConfig from '@rainbow-industries/rainbow-config';
import path from 'path';
import { fileURLToPath } from 'url';

const __dirname = path.dirname(fileURLToPath(import.meta.url));
const rootDir = path.join(__dirname, '..');

const config = new RainbowConfig();

await config.load(rootDir);

console.log(config.getEnvironment());           // development
console.log(config.get<number>('db.main.port')); // 5432
console.log(config.getString('db.main.password')); // soSecureICantBelieveIt

Project layout

By default, Rainbow Config expects this structure relative to the rootPath you pass to load():

your-project/
├── config/
│   ├── development.yml
│   ├── testing.yml
│   ├── integration.yml
│   └── production.yml
├── secrets.development.yml    # optional; see Secrets
├── secrets.testing.yml
└── src/
    └── app.ts

| File | Location | Purpose | |------|----------|---------| | Environment config | {rootPath}/{configDir}/{environment}.yml | Main YAML config (default configDir is config) | | Secrets | {rootPath or secretsDir}/secrets.{environment}.yml | Fallback values for ${...} placeholders |

Change the config directory with setConfigDir() before calling load().


Environments

Rainbow Config picks one environment file: config/{environment}.yml.

Built-in environments

| Canonical name | Aliases | |----------------|---------| | development | dev | | testing | test | | integration | int | | production | prod |

Register more with addEnvironment('staging', 'stg').

How the environment is chosen

Detection runs in this order (first match wins):

flowchart TD
    A[Start] --> B{Constructor env?}
    B -->|yes| C[Translate alias → validate]
    B -->|no| D{CLI flag --name?}
    D -->|known env| E[Use translated name]
    D -->|no match| F{RAINBOW_ENV set?}
    F -->|valid| E
    F -->|invalid| G[Throw]
    F -->|unset| H{NODE_ENV set?}
    H -->|valid| E
    H -->|invalid| G
    H -->|unset| I[Throw: no environment]
    C --> E
  1. Constructor — new RainbowConfig('dev') (aliases are translated)
  2. Command line — any process.argv entry after stripping --, e.g. --development or --prod
  3. RAINBOW_ENV — environment variable (preferred over NODE_ENV)
  4. NODE_ENV — standard Node environment variable

If none of the above yields a registered environment name, load() throws.


Secrets

Placeholders in YAML must be a single string value matching:

${key_name}

Rules for key_name:

  • Starts with a lowercase letter
  • Contains only lowercase letters, digits, and underscores (a–z, 0–9, _)

Examples: ${db_host}, ${DB_PASSWORD} ✓ — ${DbHost} or ${my-secret} ✗

Resolution order

For each placeholder, the value is resolved in order:

  1. process.env[key_name] — if set, that value is used
  2. secrets.{environment}.yml — otherwise the key must exist in the secrets file

Secrets file values must be a string, number, or boolean. Other types throw when the file is loaded.

Secrets file location

  • Default: {rootPath}/secrets.{environment}.yml
  • Custom: pass a second argument to load(rootPath, secretsDir) to load secrets.{environment}.yml from another directory

The secrets file is read once per load() and cached in memory.


API reference

Import

import RainbowConfig from '@rainbow-industries/rainbow-config';
import type { RainbowConfigType } from '@rainbow-industries/rainbow-config';

new RainbowConfig(env?: string)

Creates a config loader. Optionally pin the environment in the constructor; otherwise detection runs at load() time.

const config = new RainbowConfig();
const pinned = new RainbowConfig('dev'); // loads config/development.yml

| Parameter | Type | Description | |-----------|------|-------------| | env | string (optional) | Environment name or alias (dev → development) |


setConfigDir(configDir: string): void

Sets the directory name under rootPath where YAML files live. Default: 'config'.

Must be called before load().

config.setConfigDir('conf');
// → conf/development.yml

addEnvironment(name: string, alternativeName?: string): void

Registers a custom environment and an optional CLI/env alias.

Must be called before load().

config.addEnvironment('staging');
config.addEnvironment('staging', 'stg');
// --stg or RAINBOW_ENV=stg → staging

load(rootPath: string, secretsDir?: string): Promise<void>

Loads and parses the environment YAML file, substitutes secrets, and marks the instance ready for reads.

await config.load('/path/to/project');
await config.load('/path/to/project', '/path/to/secrets-only-dir');

| Parameter | Type | Description | |-----------|------|-------------| | rootPath | string | Base directory containing the config folder (and default secrets file) | | secretsDir | string (optional) | Directory containing secrets.{environment}.yml instead of rootPath |

Throws if the config file is missing, unreadable, invalid YAML, environment cannot be determined, or a secret cannot be resolved.


getEnvironment(): string

Returns the resolved canonical environment name (e.g. development).

Requires load() to have completed.

const env = config.getEnvironment();

getTranslatedEnvironment(env: string): string

Maps a known alias to its canonical name; returns env unchanged if no alias exists. Does not require load().

config.getTranslatedEnvironment('dev');  // 'development'
config.getTranslatedEnvironment('prod'); // 'production'

get<T>(key?: string): T

Returns the full config object or a nested value by dot-separated path.

Requires load() to have completed.

const all = config.get();                    // entire parsed config
const db = config.get<{ main: { port: number } }>('db');
const port = config.get<number>('db.main.port');

| Parameter | Type | Description | |-----------|------|-------------| | key | string (optional) | Dot path, e.g. 'db.main.password' |

Throws if the path does not exist.


getOptional<T>(key?: string): T | undefined

Same as get(), but returns undefined when the path is missing instead of throwing.

const maybe = config.getOptional<string>('feature.flag');

has(key: string): boolean

Returns whether a dot path exists in the loaded config.

if (config.has('db.main.port')) { /* ... */ }

Typed primitive getters

Strict helpers that require the value to exist and match the expected JavaScript type.

| Method | Returns | Throws when | |--------|---------|-------------| | getString(key) | string | Missing key or wrong type | | getNumber(key) | number | Missing key or wrong type | | getBoolean(key) | boolean | Missing key or wrong type | | getOptionalString(key) | string \| undefined | Wrong type (missing → undefined) | | getOptionalNumber(key) | number \| undefined | Wrong type (missing → undefined) | | getOptionalBoolean(key) | boolean \| undefined | Wrong type (missing → undefined) |

const password = config.getString('db.main.password');
const port = config.getNumber('db.main.port');
const enabled = config.getBoolean('test');

const optionalFlag = config.getOptionalString('feature.flag');

Type mismatch errors include the actual type (array, null, etc.) in the message.


TypeScript

The package ships with declaration files. Use generics on get / getOptional for nested shapes, or primitive getters when you want runtime type checks:

interface DbConfig {
  main: {
    port: number;
    host: string;
    password: string;
  };
}

const config = new RainbowConfig('development');
await config.load(rootDir);

const db = config.get<DbConfig>('db');
const port: number = config.getNumber('db.main.port');

Export type for dependency injection or wrappers:

import type { RainbowConfigType } from '@rainbow-industries/rainbow-config';

function createApp(cfg: RainbowConfigType) { /* ... */ }

Errors

Common failure modes:

| Situation | Typical error | |-----------|----------------| | get() / has() before load() | Please call the load() method on the RainbowConfig first! | | setConfigDir() / addEnvironment() after load() | Cannot set the config dir... / Cannot add an environment... | | Missing config file | Failed to load the configuration: Failed to load the file ... | | Unknown RAINBOW_ENV / NODE_ENV | Unknown environment '...' | | No environment detected | Failed to determine the environment... | | Invalid constructor env | The environment ... is not a valid environment! | | Missing config path | section ... does not exist! | | Unresolved secret | Failed to load secret ... neither provided as environment variable nor set in the secrets file | | Invalid secret file value | Secrets in file ... need to be a string, bool or number! | | Wrong type in getter | expected string but received number! |


Changelog

Version 3.x

  • load(path) — the config root path is passed to load(), not the constructor
  • TypeScript — rewritten in TypeScript with exported types
  • New API — getOptional, typed getters (getString, getNumber, …), has, getEnvironment, getTranslatedEnvironment
  • JavaScript — still usable from plain JS with the same ESM import

Earlier 2.x docs that referenced @rainbow-config/RainbowConfig or constructor-based paths are obsolete; use @rainbow-industries/rainbow-config and load(rootPath) as shown above.


License

See repository license terms for @rainbow-industries/rainbow-config.