⚙️ c12

c12 (pronounced as /siːtwelv/, like c-twelve) is a smart configuration loader.

[!NOTE] See the Migration section for upgrading from v3 to v4.

✅ Features

.js, .ts, .mjs, .cjs, .mts, .cts .json config loader with customizable import or unjs/jiti fallback.
.jsonc, .json5, .yaml, .yml, .toml config loader with unjs/confbox
.config/ directory support (config dir proposal)
.rc config support with unjs/rc9
.env support with variable interpolation and optional _FILE references resolution
Multiple sources merged with unjs/defu
Reads config from the nearest package.json file
Extends configurations from multiple local or git sources
Overwrite with environment-specific configuration
Config watcher with auto-reload and HMR support
Create or update configuration files with magicast

???? Used by

Usage

Install package:

# ✨ Auto-detect
npx nypm install c12

Import:

// ESM import
import { loadConfig, watchConfig } from "c12";

// or using dynamic import
const { loadConfig, watchConfig } = await import("c12");

Load configuration:

// Get loaded config
const { config } = await loadConfig({});

// Get resolved config and extended layers
const { config, configFile, layers } = await loadConfig({});

Loading priority

c12 merged config sources with unjs/defu by below order:

Config overrides passed by options
Config file in CWD
RC file in CWD
Global RC file in the user's home directory
Config from package.json
Default config passed by options
Extended config layers

Options

`cwd`

Resolve configuration from this working directory. The default is process.cwd()

`name`

Configuration base name. The default is config.

`configFile`

Configuration file name without extension. Default is generated from name (f.e., if name is foo, the config file will be => foo.config).

`rcFile`

RC Config file name. Default is generated from name (name=foo => .foorc).

Set to false to disable loading RC config.

`globalRc`

Load RC config from the workspace directory and the user's home directory. Only enabled when rcFile is provided. Set to false to disable this functionality.

`dotenv`

Loads .env file when true or an options object is passed. It is disabled by default.

Supports loading multiple files that extend eachother in left-to-right order when a fileNames array of relative/absolute paths is passed in the options object.

Example:

# .env
CONNECTION_POOL_MAX="10"
DATABASE_URL="<...rds...>"

# .env.local
DATABASE_URL="<...localhost...>"

export default {
  connectionPoolMax: process.env.CONNECTION_POOL_MAX,
  databaseURL: process.env.DATABASE_URL,
};

import { loadConfig } from "c12";

const config = await loadConfig({
  dotenv: {
    fileName: [".env", ".env.local"],
  },
});

console.log(config.config.connectionPoolMax); // "10"
console.log(config.config.databaseURL); // "<...localhost...>"

`expandFileReferences`

Disabled by default. Environment variables ending with _FILE are resolved by reading the file at the specified path and assigning its trimmed content to the base key (without the _FILE suffix). This is useful for container secrets (e.g. Docker, Kubernetes) where sensitive values are mounted as files. Set to true to enable.

# .env
DATABASE_PASSWORD_FILE="/run/secrets/db_password"

import { loadConfig } from "c12";

const config = await loadConfig({
  dotenv: {
    expandFileReferences: true,
  },
});

// DATABASE_PASSWORD is now set to the contents of /run/secrets/db_password

`packageJson`

Loads config from nearest package.json file. It is disabled by default.

If true value is passed, c12 uses name field from package.json.

You can also pass either a string or an array of strings as a value to use those fields.

`defaults`

Specify default configuration. It has the lowest priority and is applied after extending config.

`defaultConfig`

Specify default configuration. It is applied before extending config.

`overrides`

Specify override configuration. It has the highest priority and is applied before extending config.

`omit$Keys`

Exclude environment-specific and built-in keys start with $ in the resolved config. The default is false.

`import`

Custom import function used to load configuration files. By default, c12 uses native import() with unjs/jiti as fallback.

Example: Using a custom jiti instance with options:

import { createJiti } from "jiti";

const jiti = createJiti(import.meta.url, {
  /* jiti options */
});

const { config } = await loadConfig({
  import: (id) => jiti.import(id),
});

`resolveModule`

Custom resolver for picking which export to use from the loaded module. Default: (mod) => mod.default || mod.

Example: Using a named export:

const { config } = await loadConfig({
  resolveModule: (mod) => mod.myConfig,
});

`giget`

Options passed to unjs/giget when extending layer from git source.

`merger`

Custom options merger function. Default is defu.

Note: Custom merge function should deeply merge options with arguments high -> low priority.

`envName`

Environment name used for environment specific configuration.

The default is process.env.NODE_ENV. You can set envName to false or an empty string to disable the feature.

`context`

Context object passed to dynamic config functions.

`resolve`

You can define a custom function that resolves the config.

`configFileRequired`

If this option is set to true, loader fails if the main config file does not exists.

Extending configuration

If resolved config contains a extends key, it will be used to extend the configuration.

Extending can be nested and each layer can extend from one base or more.

The final config is merged result of extended options and user options with unjs/defu.

Each item in extends is a string that can be either an absolute or relative path to the current config file pointing to a config file for extending or the directory containing the config file. If it starts with either github:, gitlab:, bitbucket:, or https:, c12 automatically clones it.

For custom merging strategies, you can directly access each layer with layers property.

Example:

// config.ts
export default {
  colors: {
    primary: "user_primary",
  },
  extends: ["./theme"],
};

// config.dev.ts
export default {
  dev: true,
};

// theme/config.ts
export default {
  extends: "../base",
  colors: {
    primary: "theme_primary",
    secondary: "theme_secondary",
  },
};

// base/config.ts
export default {
  colors: {
    primary: "base_primary",
    text: "base_text",
  },
};

The loaded configuration would look like this:

const config = {
  dev: true,
  colors: {
    primary: "user_primary",
    secondary: "theme_secondary",
    text: "base_text",
  },
};

Layers:

[
  {
    config: {
      /* theme config */
    },
    configFile: "/path/to/theme/config.ts",
    cwd: "/path/to/theme ",
  },
  {
    config: {
      /* base  config */
    },
    configFile: "/path/to/base/config.ts",
    cwd: "/path/to/base",
  },
  {
    config: {
      /* dev   config */
    },
    configFile: "/path/to/config.dev.ts",
    cwd: "/path/",
  },
];

Extending config layer from remote sources

[!NOTE] Extending from remote sources requires the giget peer dependency to be installed.
# ✨ Auto-detect
npx nypm install giget

You can also extend configuration from remote sources such as npm or github.

In the repo, there should be a config.ts (or config.{name}.ts) file to be considered as a valid config layer.

Example: Extend from a github repository

// config.ts
export default {
  extends: "gh:user/repo",
};

Example: Extend from a github repository with branch and subpath

// config.ts
export default {
  extends: "gh:user/repo/theme#dev",
};

Example: Extend a private repository and install dependencies:

// config.ts
export default {
  extends: ["gh:user/repo", { auth: process.env.GITHUB_TOKEN, install: true }],
};

You can pass more options to giget: {} in layer config or disable it by setting it to false.

Refer to unjs/giget for more information.

Environment-specific configuration

Users can define environment-specific configuration using these config keys:

$test: {...}
$development: {...}
$production: {...}
$env: { [env]: {...} }

c12 tries to match envName and override environment config if specified.

Note: Environment will be applied when extending each configuration layer. This way layers can provide environment-specific configuration.

Example:

export default {
  // Default configuration
  logLevel: "info",

  // Environment overrides
  $test: { logLevel: "silent" },
  $development: { logLevel: "warning" },
  $production: { logLevel: "error" },
  $env: {
    staging: { logLevel: "debug" },
  },
};

Watching configuration

you can use watchConfig instead of loadConfig to load config and watch for changes, add and removals in all expected configuration paths and auto reload with new config.

[!NOTE] Watching requires the chokidar peer dependency to be installed.
# ✨ Auto-detect
npx nypm install chokidar

Lifecycle hooks

onWatch: This function is always called when config is updated, added, or removed before attempting to reload the config.
acceptHMR: By implementing this function, you can compare old and new functions and return true if a full reload is not needed.
onUpdate: This function is always called after the new config is updated. If acceptHMR returns true, it will be skipped.

import { watchConfig } from "c12";

const config = watchConfig({
  cwd: ".",
  // chokidarOptions: {}, // Default is { ignoreInitial: true }
  // debounce: 200 // Default is 100. You can set it to false to disable debounced watcher
  onWatch: (event) => {
    console.log("[watcher]", event.type, event.path);
  },
  acceptHMR({ oldConfig, newConfig, getDiff }) {
    const diff = getDiff();
    if (diff.length === 0) {
      console.log("No config changed detected!");
      return true; // No changes!
    }
  },
  onUpdate({ oldConfig, newConfig, getDiff }) {
    const diff = getDiff();
    console.log("Config updated:\n" + diff.map((i) => i.toJSON()).join("\n"));
  },
});

console.log("watching config files:", config.watchingFiles);
console.log("initial config", config.config);

// Stop watcher when not needed anymore
// await config.unwatch();

Updating config

[!NOTE] This feature is experimental

Update or create a new configuration files.

Add magicast peer dependency:

# ✨ Auto-detect
npx nypm install -D magicast

Import util from c12/update

const { configFile, created } = await updateConfig({
  cwd: ".",
  configFile: "foo.config",
  onCreate: ({ configFile }) => {
    // You can prompt user if wants to create a new config file and return false to cancel
    console.log(`Creating new config file in ${configFile}...`);
    return "export default { test: true }";
  },
  onUpdate: (config) => {
    // You can update the config contents just like an object
    config.test2 = false;
  },
});

console.log(`Config file ${created ? "created" : "updated"} in ${configFile}`);

Configuration functions

You can use a function to define your configuration dynamically based on context.

// config.ts
export default (ctx) => {
  return {
    apiUrl: ctx?.dev ? "http://localhost:3000" : "https://api.example.com",
  };
};

// Usage
import { loadConfig } from "c12";

const config = await loadConfig({
  context: { dev: true },
});

Migration

v3 to v4

c12 install size is now down to 380kB from 3.44MB (20 deps to 7 deps).

Loading TypeScript files is significantly faster (on cold cache) — simple TS config loads ~2.5x faster (bench).

If you need extends feature with remote/git source, install giget as a peer dependency (docs)
If you are using watchConfig, install chokidar as a peer dependency (docs).
If you need legacy TypeScript support (mixed ESM/CJS, no import extensions, etc.), install jiti as a peer dependency (c12 automatically falls back) or provide a custom import config (docs).
Dotenv parsing now uses native runtime features (see #296). You might need to add dotenv as a peer dependency only for legacy/Deno support.

Contribution

<summary>Local development</summary>

Clone this repository
Install the latest LTS version of Node.js
Enable Corepack using corepack enable
Install dependencies using pnpm install
Run tests using pnpm dev or pnpm test

License

Published under the MIT license. Made by @pi0 and community ????

???? auto updated with automd

Current Tags

3.3.4 ... 3x (9 days ago)
4.0.0-beta.4 ... latest (a month ago)

⚙️ c12

✅ Features

???? Used by

Usage

Loading priority

Options

cwd

name

configFile

rcFile

globalRc

dotenv

expandFileReferences

packageJson

defaults

defaultConfig

overrides

omit$Keys

import

resolveModule

giget

merger

envName

context

resolve

configFileRequired

Extending configuration

Extending config layer from remote sources

Environment-specific configuration

Watching configuration

Lifecycle hooks

Updating config

Configuration functions

Migration

v3 to v4

Contribution

License

Current Tags

64 Versions

`cwd`

`name`

`configFile`

`rcFile`

`globalRc`

`dotenv`

`expandFileReferences`

`packageJson`

`defaults`

`defaultConfig`

`overrides`

`omit$Keys`

`import`

`resolveModule`

`giget`

`merger`

`envName`

`context`

`resolve`

`configFileRequired`