c12 4.0.0-beta.1 → 4.0.0-beta.2

package/README.md

@@ -16,7 +16,7 @@ c12 (pronounced as /siːtwelv/, like c-twelve) is a smart configuration loader.
 - `.jsonc`, `.json5`, `.yaml`, `.yml`, `.toml` config loader with [unjs/confbox](https://confbox.unjs.io)
 - `.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)
+- `.env` support with variable interpolation and `_FILE` references resolution
 - Multiple sources merged with [unjs/defu](https://github.com/unjs/defu)
 - Reads config from the nearest `package.json` file
 - [Extends configurations](https://github.com/unjs/c12#extending-configuration) from multiple local or git sources
@@ -139,6 +139,25 @@ console.log(config.config.connectionPoolMax); // "10"
 console.log(config.config.databaseURL); // "<...localhost...>"
 ```
 
+#### `expandFileReferences`
+
+Enabled 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 `false` to disable.
+
+```ini
+# .env
+DATABASE_PASSWORD_FILE="/run/secrets/db_password"
+```
+
+```ts
+import { loadConfig } from "c12";
+
+const config = await loadConfig({
+  dotenv: 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.
@@ -172,7 +191,9 @@ Custom import function used to load configuration files. By default, c12 uses na
 ```js
 import { createJiti } from "jiti";
 
-const jiti = createJiti(import.meta.url, { /* jiti options */ });
+const jiti = createJiti(import.meta.url, {
+  /* jiti options */
+});
 
 const { config } = await loadConfig({
   import: (id) => jiti.import(id),
@@ -315,6 +336,14 @@ Layers:
 
 ## Extending config layer from remote sources
 
+> [!NOTE]
+> Extending from remote sources requires the [`giget`](https://giget.unjs.io) peer dependency to be installed.
+>
+> ```sh
+> # ✨ 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.

package/dist/index.d.mts

@@ -31,6 +31,22 @@ interface DotenvOptions {
    * An object describing environment variables (key, value pairs).
    */
   env?: NodeJS.ProcessEnv;
+  /**
+   * Resolve `_FILE` suffixed environment variables by reading the file at the
+   * specified path and assigning its trimmed content to the base key.
+   *
+   * This is useful for container secrets (e.g. Docker, Kubernetes) where
+   * sensitive values are mounted as files.
+   *
+   * @default true
+   *
+   * @example
+   * ```env
+   * DATABASE_PASSWORD_FILE="/run/secrets/db_password"
+   * # resolves to DATABASE_PASSWORD=<contents of /run/secrets/db_password>
+   * ```
+   */
+  expandFileReferences?: boolean;
 }
 type Env = typeof process.env;
 /**
@@ -168,4 +184,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>>;
 //#endregion
-export { C12InputConfig, ConfigFunctionContext, ConfigLayer, ConfigLayerMeta, ConfigSource, ConfigWatcher, DefineConfig, DotenvOptions, Env, InputConfig, LoadConfigOptions, ResolvableConfig, ResolvableConfigContext, ResolvedConfig, SUPPORTED_EXTENSIONS, SourceOptions, UserInputConfig, WatchConfigOptions, createDefineConfig, loadConfig, loadDotenv, setupDotenv, watchConfig };
+export { C12InputConfig, ConfigFunctionContext, ConfigLayer, ConfigLayerMeta, ConfigSource, type ConfigWatcher, DefineConfig, type DotenvOptions, type Env, InputConfig, LoadConfigOptions, ResolvableConfig, ResolvableConfigContext, ResolvedConfig, SUPPORTED_EXTENSIONS, SourceOptions, UserInputConfig, type WatchConfigOptions, createDefineConfig, loadConfig, loadDotenv, setupDotenv, watchConfig };

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import { t as debounce } from "./_chunks/libs/perfect-debounce.mjs";
-import { existsSync, promises, statSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import * as nodeUtil from "node:util";
 import { basename, dirname, extname, join, normalize, resolve } from "pathe";
-import * as dotenv from "dotenv";
 import { readFile, rm } from "node:fs/promises";
 import { pathToFileURL } from "node:url";
 import { homedir } from "node:os";
@@ -15,7 +15,8 @@ async function setupDotenv(options) {
 		cwd: options.cwd,
 		fileName: options.fileName ?? ".env",
 		env: targetEnvironment,
-		interpolate: options.interpolate ?? true
+		interpolate: options.interpolate ?? true,
+		expandFileReferences: options.expandFileReferences ?? true
 	});
 	const dotenvVars = getDotEnvVars(targetEnvironment);
 	for (const key in environment) {
@@ -34,16 +35,39 @@ async function loadDotenv(options) {
 	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"));
+		const parsed = await readEnvFile(dotenvFile);
 		for (const key in parsed) {
 			if (key in environment && !dotenvVars.has(key)) continue;
 			environment[key] = parsed[key];
 			dotenvVars.add(key);
 		}
 	}
+	if (options.expandFileReferences !== false) {
+		for (const key in environment) if (key.endsWith("_FILE")) {
+			const targetKey = key.slice(0, -5);
+			if (environment[targetKey] === void 0) {
+				const filePath = environment[key];
+				if (filePath && statSync(filePath, { throwIfNoEntry: false })?.isFile()) {
+					environment[targetKey] = readFileSync(filePath, "utf8").trim();
+					dotenvVars.add(targetKey);
+				}
+			}
+		}
+	}
 	if (options.interpolate) interpolate(environment);
 	return environment;
 }
+let _parseEnv = nodeUtil.parseEnv;
+async function readEnvFile(path) {
+	const src = readFileSync(path, "utf8");
+	if (!_parseEnv) try {
+		const dotenv = await import("dotenv");
+		_parseEnv = (src) => dotenv.parse(src);
+	} catch {
+		throw new Error("Failed to parse .env file: `node:util.parseEnv` is not available and `dotenv` package is not installed. Please upgrade your runtime or install `dotenv` as a dependency.");
+	}
+	return _parseEnv(src);
+}
 function interpolate(target, source = {}, parse = (v) => v) {
 	function getValue(key) {
 		return source[key] === void 0 ? target[key] : source[key];
@@ -263,7 +287,9 @@ async function resolveConfig(source, options, sourceOptions = {}) {
 	const customProviderKeys = Object.keys(sourceOptions.giget?.providers || {}).map((key) => `${key}:`);
 	const gigetPrefixes = customProviderKeys.length > 0 ? [...new Set([...customProviderKeys, ...GIGET_PREFIXES])] : GIGET_PREFIXES;
 	if (options.giget !== false && gigetPrefixes.some((prefix) => source.startsWith(prefix))) {
-		const { downloadTemplate } = await import("giget");
+		const { downloadTemplate } = await import("giget").catch((error) => {
+			throw new Error(`Extending config from \`${source}\` requires \`giget\` peer dependency to be installed.\n\nInstall it with: \`npx nypm i giget\``, { cause: error });
+		});
 		const { digest } = await import("./_chunks/libs/ohash.mjs").then((n) => n.n);
 		const cloneName = source.replace(/\W+/g, "_").split("_").splice(0, 3).join("_") + "_" + digest(source).slice(0, 10).replace(/[-_]/g, "");
 		let cloneDir;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c12",
-  "version": "4.0.0-beta.1",
+  "version": "4.0.0-beta.2",
   "description": "Smart Config Loader",
   "license": "MIT",
   "repository": "unjs/c12",
@@ -26,9 +26,7 @@
   "dependencies": {
     "confbox": "^0.2.4",
     "defu": "^6.1.4",
-    "dotenv": "^17.2.4",
     "exsolve": "^1.0.8",
-    "giget": "^3.1.2",
     "pathe": "^2.0.3",
     "pkg-types": "^2.3.0",
     "rc9": "^3.0.0"
@@ -40,8 +38,10 @@
     "automd": "^0.4.3",
     "changelogen": "^0.6.2",
     "chokidar": "^5.0.0",
+    "dotenv": "^17.2.4",
     "eslint-config-unjs": "^0.6.2",
     "expect-type": "^1.3.0",
+    "giget": "^3.1.2",
     "jiti": "^2.6.1",
     "magicast": "^0.5.2",
     "obuild": "^0.4.27",
@@ -54,10 +54,15 @@
   },
   "peerDependencies": {
     "chokidar": "^5",
+    "dotenv": "*",
+    "giget": "*",
     "jiti": "*",
     "magicast": "*"
   },
   "peerDependenciesMeta": {
+    "dotenv": {
+      "optional": true
+    },
     "magicast": {
       "optional": true
     },
@@ -66,6 +71,9 @@
     },
     "jiti": {
       "optional": true
+    },
+    "giget": {
+      "optional": true
     }
   },
   "packageManager": "pnpm@10.28.2"