c12 3.1.0 → 3.3.0

package/README.md

@@ -14,7 +14,7 @@ c12 (pronounced as /siːtwelv/, like c-twelve) is a smart configuration loader.
 
 - `.js`, `.ts`, `.mjs`, `.cjs`, `.mts`, `.cts` `.json` config loader with [unjs/jiti](https://jiti.unjs.io)
 - `.jsonc`, `.json5`, `.yaml`, `.yml`, `.toml` config loader with [unjs/confbox](https://confbox.unjs.io)
-- `.config/` directory support following [config dir proposal](https://github.com/pi0/config-dir)
+- `.config/` directory support ([config dir proposal](https://github.com/pi0/config-dir))
 - `.rc` config support with [unjs/rc9](https://github.com/unjs/rc9)
 - `.env` support with [dotenv](https://www.npmjs.com/package/dotenv)
 - Multiple sources merged with [unjs/defu](https://github.com/unjs/defu)
@@ -26,43 +26,24 @@ c12 (pronounced as /siːtwelv/, like c-twelve) is a smart configuration loader.
 
 ## 🦴 Used by
 
-- [Nuxt](https://nuxt.com/)
-- [Nitro](https://nitro.build/)
-- [Unbuild](https://unbuild.unjs.io)
-- [Automd](https://automd.unjs.io)
-- [Changelogen](https://changelogen.unjs.io)
-- [RemixKit](https://github.com/jrestall/remix-kit)
 - [Hey API](https://github.com/hey-api/openapi-ts)
-- [kysely-ctl](https://github.com/kysely-org/kysely-ctl)
+- [Kysely](https://github.com/kysely-org/kysely-ctl)
+- [Nitro](https://nitro.build/)
+- [Nuxt](https://nuxt.com/)
+- [Prisma](https://github.com/prisma/prisma)
+- [Trigger.dev](https://github.com/triggerdotdev/trigger.dev)
+- [UnJS](https://github.com/unjs)
+- [WXT](https://github.com/wxt-dev/wxt)
 
 ## Usage
 
 Install package:
 
-<!-- automd:pm-install -->
-
 ```sh
 # ✨ Auto-detect
 npx nypm install c12
-
-# npm
-npm install c12
-
-# yarn
-yarn add c12
-
-# pnpm
-pnpm install c12
-
-# bun
-bun install c12
-
-# deno
-deno install c12
 ```
 
-<!-- /automd -->
-
 Import:
 
 ```js
@@ -121,7 +102,42 @@ Load RC config from the workspace directory and the user's home directory. Only
 
 ### `dotenv`
 
-Loads `.env` file if enabled. It is disabled by default.
+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 `fileName`s array of relative/absolute paths is passed in the options object.
+
+**Example:**
+
+```ini
+# .env
+CONNECTION_POOL_MAX="10"
+DATABASE_URL="<...rds...>"
+```
+
+```ini
+# .env.local
+DATABASE_URL="<...localhost...>"
+```
+
+```js
+export default {
+  connectionPoolMax: process.env.CONNECTION_POOL_MAX,
+  databaseURL: process.env.DATABASE_URL,
+};
+```
+
+```ts
+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...>"
+```
 
 ### `packageJson`
 
@@ -171,10 +187,17 @@ Environment name used for [environment specific configuration](#environment-spec
 
 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
 
@@ -386,30 +409,11 @@ Update or create a new configuration files.
 
 Add `magicast` peer dependency:
 
-<!-- automd:pm-install name="magicast" dev -->
-
 ```sh
 # ✨ Auto-detect
 npx nypm install -D magicast
-
-# npm
-npm install -D magicast
-
-# yarn
-yarn add -D magicast
-
-# pnpm
-pnpm install -D magicast
-
-# bun
-bun install -D magicast
-
-# deno
-deno install --dev magicast
 ```
 
-<!-- /automd -->
-
 Import util from `c12/update`
 
 ```js
@@ -430,6 +434,28 @@ const { configFile, created } = await updateConfig({
 console.log(`Config file ${created ? "created" : "updated"} in ${configFile}`);
 ```
 
+## Configuration functions
+
+You can use a function to define your configuration dynamically based on context.
+
+```ts
+// config.ts
+export default (ctx) => {
+  return {
+    apiUrl: ctx?.dev ? "http://localhost:3000" : "https://api.example.com",
+  };
+};
+```
+
+```ts
+// Usage
+import { loadConfig } from "c12";
+
+const config = await loadConfig({
+  context: { dev: true },
+});
+```
+
 ## Contribution
 
 <details>

package/dist/index.d.mts

@@ -6,13 +6,16 @@ import { diff } from 'ohash/utils';
 interface DotenvOptions {
     /**
      * The project root directory (either absolute or relative to the current working directory).
+     *
+     * Defaults to `options.cwd` in `loadConfig` context, or `process.cwd()` when used as standalone.
      */
-    cwd: string;
+    cwd?: string;
     /**
-     * What file to look in for environment variables (either absolute or relative
+     * What file or files to look in for environment variables (either absolute or relative
      * to the current working directory). For example, `.env`.
+     * With the array type, the order enforce the env loading priority (last one overrides).
      */
-    fileName?: string;
+    fileName?: string | string[];
     /**
      * Whether to interpolate variables within .env.
      *
@@ -92,8 +95,12 @@ interface ResolvedConfig<T extends UserInputConfig = UserInputConfig, MT extends
     config: T;
     layers?: ConfigLayer<T, MT>[];
     cwd?: string;
+    _configFile?: string;
 }
 type ConfigSource = "overrides" | "main" | "rc" | "packageJson" | "defaultConfig";
+interface ConfigFunctionContext {
+    [key: string]: any;
+}
 interface ResolvableConfigContext<T extends UserInputConfig = UserInputConfig> {
     configs: Record<ConfigSource, T | null | undefined>;
     rawConfigs: Record<ConfigSource, ResolvableConfig<T> | null | undefined>;
@@ -113,6 +120,8 @@ interface LoadConfigOptions<T extends UserInputConfig = UserInputConfig, MT exte
     defaultConfig?: ResolvableConfig<T>;
     overrides?: ResolvableConfig<T>;
     omit$Keys?: boolean;
+    /** Context passed to config functions */
+    context?: ConfigFunctionContext;
     resolve?: (id: string, options: LoadConfigOptions<T, MT>) => null | undefined | ResolvedConfig<T, MT> | Promise<ResolvedConfig<T, MT> | undefined | null>;
     jiti?: Jiti;
     jitiOptions?: JitiOptions;
@@ -121,6 +130,7 @@ interface LoadConfigOptions<T extends UserInputConfig = UserInputConfig, MT exte
     extend?: false | {
         extendKey?: string | string[];
     };
+    configFileRequired?: boolean;
 }
 type DefineConfig<T extends UserInputConfig = UserInputConfig, MT extends ConfigLayerMeta = ConfigLayerMeta> = (input: InputConfig<T, MT>) => InputConfig<T, MT>;
 declare function createDefineConfig<T extends UserInputConfig = UserInputConfig, MT extends ConfigLayerMeta = ConfigLayerMeta>(): DefineConfig<T, MT>;
@@ -154,4 +164,4 @@ interface WatchConfigOptions<T extends UserInputConfig = UserInputConfig, MT ext
 declare function watchConfig<T extends UserInputConfig = UserInputConfig, MT extends ConfigLayerMeta = ConfigLayerMeta>(options: WatchConfigOptions<T, MT>): Promise<ConfigWatcher<T, MT>>;
 
 export { SUPPORTED_EXTENSIONS, createDefineConfig, loadConfig, loadDotenv, setupDotenv, watchConfig };
-export type { C12InputConfig, ConfigLayer, ConfigLayerMeta, ConfigSource, ConfigWatcher, DefineConfig, DotenvOptions, Env, InputConfig, LoadConfigOptions, ResolvableConfig, ResolvableConfigContext, ResolvedConfig, SourceOptions, UserInputConfig, WatchConfigOptions };
+export type { C12InputConfig, ConfigFunctionContext, ConfigLayer, ConfigLayerMeta, ConfigSource, ConfigWatcher, DefineConfig, DotenvOptions, Env, InputConfig, LoadConfigOptions, ResolvableConfig, ResolvableConfigContext, ResolvedConfig, SourceOptions, UserInputConfig, WatchConfigOptions };

package/dist/index.mjs

@@ -1,5 +1,5 @@
-import { l as loadConfig, S as SUPPORTED_EXTENSIONS } from './shared/c12.BXpNC6YI.mjs';
-export { a as loadDotenv, s as setupDotenv } from './shared/c12.BXpNC6YI.mjs';
+import { l as loadConfig, S as SUPPORTED_EXTENSIONS } from './shared/c12.Bzgyhsy6.mjs';
+export { a as loadDotenv, s as setupDotenv } from './shared/c12.Bzgyhsy6.mjs';
 import { debounce } from 'perfect-debounce';
 import { resolve } from 'pathe';
 import 'node:fs';

package/dist/shared/{c12.BXpNC6YI.mjs → c12.Bzgyhsy6.mjs}

@@ -31,10 +31,16 @@ async function setupDotenv(options) {
 }
 async function loadDotenv(options) {
   const environment = /* @__PURE__ */ Object.create(null);
-  const dotenvFile = resolve(options.cwd, options.fileName);
+  const cwd = resolve(options.cwd || ".");
+  const _fileName = options.fileName || ".env";
+  const dotenvFiles = typeof _fileName === "string" ? [_fileName] : _fileName;
   const dotenvVars = getDotEnvVars(options.env || {});
   Object.assign(environment, options.env);
-  if (statSync(dotenvFile, { throwIfNoEntry: false })?.isFile()) {
+  for (const file of dotenvFiles) {
+    const dotenvFile = resolve(cwd, file);
+    if (!statSync(dotenvFile, { throwIfNoEntry: false })?.isFile()) {
+      continue;
+    }
     const parsed = dotenv.parse(await promises.readFile(dotenvFile, "utf8"));
     for (const key in parsed) {
       if (key in environment && !dotenvVars.has(key)) {
@@ -144,7 +150,8 @@ async function loadConfig(options) {
     config: {},
     cwd: options.cwd,
     configFile: resolve(options.cwd, options.configFile),
-    layers: []
+    layers: [],
+    _configFile: void 0
   };
   const rawConfigs = {
     overrides: options.overrides,
@@ -163,6 +170,7 @@ async function loadConfig(options) {
   if (_mainConfig.configFile) {
     rawConfigs.main = _mainConfig.config;
     r.configFile = _mainConfig.configFile;
+    r._configFile = _mainConfig._configFile;
   }
   if (_mainConfig.meta) {
     r.meta = _mainConfig.meta;
@@ -194,18 +202,22 @@ async function loadConfig(options) {
     const value = rawConfigs[key];
     configs[key] = await (typeof value === "function" ? value({ configs, rawConfigs }) : value);
   }
-  r.config = _merger(
-    configs.overrides,
-    configs.main,
-    configs.rc,
-    configs.packageJson,
-    configs.defaultConfig
-  );
-  if (options.extend) {
-    await extendConfig(r.config, options);
-    r.layers = r.config._layers;
-    delete r.config._layers;
-    r.config = _merger(r.config, ...r.layers.map((e) => e.config));
+  if (Array.isArray(configs.main)) {
+    r.config = configs.main;
+  } else {
+    r.config = _merger(
+      configs.overrides,
+      configs.main,
+      configs.rc,
+      configs.packageJson,
+      configs.defaultConfig
+    );
+    if (options.extend) {
+      await extendConfig(r.config, options);
+      r.layers = r.config._layers;
+      delete r.config._layers;
+      r.config = _merger(r.config, ...r.layers.map((e) => e.config));
+    }
   }
   const baseLayers = [
     configs.overrides && {
@@ -231,6 +243,9 @@ async function loadConfig(options) {
       }
     }
   }
+  if (options.configFileRequired && !r._configFile) {
+    throw new Error(`Required config (${r.configFile}) cannot be resolved.`);
+  }
   return r;
 }
 async function extendConfig(config, options) {
@@ -295,6 +310,7 @@ const GIGET_PREFIXES = [
 ];
 const NPM_PACKAGE_RE = /^(@[\da-z~-][\d._a-z~-]*\/)?[\da-z~-][\d._a-z~-]*($|\/.*)/;
 async function resolveConfig(source, options, sourceOptions = {}) {
+  const originalSource = source;
   if (options.resolve) {
     const res2 = await options.resolve(source, options);
     if (res2) {
@@ -352,10 +368,11 @@ async function resolveConfig(source, options, sourceOptions = {}) {
   res.configFile = tryResolve(resolve(cwd, source), options) || tryResolve(
     resolve(cwd, ".config", source.replace(/\.config$/, "")),
     options
-  ) || tryResolve(resolve(cwd, ".config", source), options) || source;
+  ) || tryResolve(resolve(cwd, ".config", source), options) || tryResolve(resolve(options.cwd || cwd, originalSource), options) || source;
   if (!existsSync(res.configFile)) {
     return res;
   }
+  res._configFile = res.configFile;
   const configFileExt = extname(res.configFile) || "";
   if (configFileExt in ASYNC_LOADERS) {
     const asyncLoader = await ASYNC_LOADERS[configFileExt]();
@@ -367,7 +384,7 @@ async function resolveConfig(source, options, sourceOptions = {}) {
     });
   }
   if (typeof res.config === "function") {
-    res.config = await res.config();
+    res.config = await res.config(options.context);
   }
   if (options.envName) {
     const envConfig = {

package/dist/update.mjs

@@ -1,5 +1,5 @@
 import { resolveModulePath } from 'exsolve';
-import { S as SUPPORTED_EXTENSIONS } from './shared/c12.BXpNC6YI.mjs';
+import { S as SUPPORTED_EXTENSIONS } from './shared/c12.Bzgyhsy6.mjs';
 import { join, normalize } from 'pathe';
 import { mkdir, writeFile, readFile } from 'node:fs/promises';
 import { dirname, extname } from 'node:path';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c12",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "description": "Smart Config Loader",
   "repository": "unjs/c12",
   "license": "MIT",
@@ -34,28 +34,28 @@
     "chokidar": "^4.0.3",
     "confbox": "^0.2.2",
     "defu": "^6.1.4",
-    "dotenv": "^16.6.1",
+    "dotenv": "^17.2.2",
     "exsolve": "^1.0.7",
     "giget": "^2.0.0",
-    "jiti": "^2.4.2",
+    "jiti": "^2.5.1",
     "ohash": "^2.0.11",
     "pathe": "^2.0.3",
-    "perfect-debounce": "^1.0.0",
-    "pkg-types": "^2.2.0",
+    "perfect-debounce": "^2.0.0",
+    "pkg-types": "^2.3.0",
     "rc9": "^2.1.2"
   },
   "devDependencies": {
-    "@types/node": "^24.0.13",
+    "@types/node": "^24.4.0",
     "@vitest/coverage-v8": "^3.2.4",
     "automd": "^0.4.0",
     "changelogen": "^0.6.2",
-    "eslint": "^9.31.0",
+    "eslint": "^9.35.0",
     "eslint-config-unjs": "^0.5.0",
     "expect-type": "^1.2.2",
     "magicast": "^0.3.5",
     "prettier": "^3.6.2",
-    "typescript": "^5.8.3",
-    "unbuild": "^3.5.0",
+    "typescript": "^5.9.2",
+    "unbuild": "^3.6.1",
     "vitest": "^3.2.4"
   },
   "peerDependencies": {
@@ -66,5 +66,5 @@
       "optional": true
     }
   },
-  "packageManager": "pnpm@10.13.1"
+  "packageManager": "pnpm@10.16.1"
 }