Colony

Environment-aware config for Node.js. One file, multiple environments.

Try it in the Playground

# config/app.colony
*.database.host = "localhost";
prod.database.host = "prod-db.example.com";

import { loadColony } from "@ant.sh/colony";

const config = await loadColony({
  entry: "./config/app.colony",
  ctx: { env: "prod" }
});

config.database.host // => "prod-db.example.com"

Features

• Single config file for all environments (dev, staging, prod)
• Wildcard matching - * sets defaults, specific rules override
• Multiple dimensions - env, region, feature flags, anything
• Secret management - AWS Secrets Manager, Vault, OpenBao
• Interpolation - ${ENV:VAR}, ${ctx.region}, ${VAR:custom}
• CLI tools - validate, diff, lint, print
• TypeScript - Full type definitions included
• Zero runtime deps - Only fast-glob and json5

Installation

npm install @ant.sh/colony

Quick Start

1. Create config/app.colony

@dims env;

# Defaults
*.app.name = "MyApp";
*.database.host = "localhost";
*.database.port = 5432;

# Production overrides
prod.database.host = "prod-db.example.com";

2. Load in your app

import { loadColony } from "@ant.sh/colony";

const config = await loadColony({
  entry: "./config/app.colony",
  ctx: { env: process.env.NODE_ENV || "dev" }
});

console.log(config.database.host);
// dev:  "localhost"
// prod: "prod-db.example.com"

Multiple Dimensions

@dims env, region;

*.*.database.host = "localhost";
prod.*.database.host = "prod-db.example.com";
prod.eu.database.host = "prod-db-eu.example.com";

const config = await loadColony({
  entry: "./config/app.colony",
  ctx: { env: "prod", region: "eu" }
});
// => "prod-db-eu.example.com"

Secrets Integration

*.db.password = "${AWS:myapp/db#password}";
*.api.key = "${OPENBAO:secret/data/app#api_key}";

import { loadColony, AwsSecretsProvider, OpenBaoProvider } from "@ant.sh/colony";

const config = await loadColony({
  entry: "./config/app.colony",
  secrets: {
    providers: [
      new AwsSecretsProvider({ region: "us-east-1" }),
      new OpenBaoProvider(),
    ],
  },
});

Built-in providers: AWS Secrets Manager, HashiCorp Vault, OpenBao

CLI

colony print --entry ./config/app.colony --ctx "env=prod"
colony diff --entry ./config/app.colony --ctx1 "env=dev" --ctx2 "env=prod"
colony validate --entry ./config/app.colony
colony lint --entry ./config/app.colony

package.json Setup

{
  "scripts": {
    "dev": "NODE_ENV=dev node src/index.js",
    "prod": "NODE_ENV=prod node src/index.js",
    "start": "node src/index.js",
    "config:validate": "colony validate --entry ./config/app.colony",
    "config:lint": "colony lint --entry ./config/app.colony",
    "config:diff": "colony diff --entry ./config/app.colony --ctx1 \"env=dev\" --ctx2 \"env=prod\""
  }
}

npm run dev    # Run with dev config
npm run prod   # Run with prod config

Your app picks up the environment automatically:

// src/index.js
import { loadColony } from "@ant.sh/colony";

const config = await loadColony({
  entry: "./config/app.colony",
  ctx: { env: process.env.NODE_ENV || "dev" }
});

console.log(`Running in ${process.env.NODE_ENV} mode`);
console.log(`Database: ${config.database.host}`);

Documentation

• Interactive Playground - Try Colony in your browser
• Online Docs - Full documentation
• DOCS.md - Local documentation file

Topics covered:

• Config syntax reference
• All operators (=, :=, +=, -=, |=)
• Interpolation patterns
• Secret providers
• Security sandbox options
• Framework integrations (Express, Fastify, Next.js)
• API reference
• TypeScript types

License

MIT