c12 1.9.0 → 1.11.0

package/README.md

@@ -22,6 +22,7 @@ c12 (pronounced as /siːtwelv/, like c-twelve) is a smart configuration loader.
 - [Extends configurations](https://github.com/unjs/c12#extending-configuration) from multiple local or git sources
 - Overwrite with [environment-specific configuration](#environment-specific-configuration)
 - Config watcher with auto-reload and HMR support
+- Create or update configuration files with [magicast](https://github.com/unjs/magicast)
 
 ## 🦴 Used by
 
@@ -40,33 +41,41 @@ Install package:
 
 ```sh
 # ✨ Auto-detect
-npx nypm i c12@^1.7.0
+npx nypm install c12
 
 # npm
-npm install c12@^1.7.0
+npm install c12
 
 # yarn
-yarn add c12@^1.7.0
+yarn add c12
 
 # pnpm
-pnpm install c12@^1.7.0
+pnpm install c12
 
 # bun
-bun install c12@^1.7.0
+bun install c12
 ```
 
 <!-- /automd -->
 
 Import:
 
+<!-- automd:jsimport cjs imports="loadConfig,watchConfig" -->
+
+**ESM** (Node.js, Bun)
+
 ```js
-// ESM
 import { loadConfig, watchConfig } from "c12";
+```
+
+**CommonJS** (Legacy Node.js)
 
-// CommonJS
+```js
 const { loadConfig, watchConfig } = require("c12");
 ```
 
+<!-- /automd -->
+
 Load configuration:
 
 ```js
@@ -155,6 +164,12 @@ Custom [unjs/jiti](https://github.com/unjs/jiti) options to import configuration
 
 Options passed to [unjs/giget](https://github.com/unjs/giget) when extending layer from git source.
 
+### `merger`
+
+Custom options merger function. Default is [defu](https://github.com/unjs/defu).
+
+**Note:** Custom merge function should deeply merge options with arguments high -> low priority.
+
 ### `envName`
 
 Environment name used for [environment specific configuration](#environment-specific-configuration).
@@ -208,36 +223,54 @@ export default {
 // base/config.ts
 export default {
   colors: {
-    primary: 'base_primary'
-    text: 'base_text'
-  }
-}
+    primary: "base_primary",
+    text: "base_text",
+  },
+};
 ```
 
 The loaded configuration would look like this:
 
 ```js
-{
+const config = {
   dev: true,
   colors: {
-    primary: 'user_primary',
-    secondary: 'theme_secondary',
-    text: 'base_text'
-  }
-}
+    primary: "user_primary",
+    secondary: "theme_secondary",
+    text: "base_text",
+  },
+};
 ```
 
 Layers:
 
 ```js
 [
- { 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/ */ },
-]
+  {
+    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
+## Extending config layer from remote sources
 
 You can also extend configuration from remote sources such as npm or github.
 
@@ -261,15 +294,17 @@ export default {
 };
 ```
 
-**Example:** Extend with clone configuration
+**Example:** Extend a private repository and install dependencies:
 
 ```js
 // config.ts
 export default {
-  extends: ["gh:user/repo", { giget: { auth: process.env.GITHUB_TOKEN } }],
+  extends: ["gh:user/repo", { auth: process.env.GITHUB_TOKEN, install: true }],
 };
 ```
 
+You can pass more options to `giget: {}` in layer config.
+
 Refer to [unjs/giget](https://giget.unjs.io) for more information.
 
 ## Environment-specific configuration
@@ -288,21 +323,21 @@ c12 tries to match [`envName`](#envname) and override environment config if spec
 **Example:**
 
 ```js
-{
+export default {
   // Default configuration
-  logLevel: 'info',
+  logLevel: "info",
 
   // Environment overrides
-  $test: { logLevel: 'silent' },
-  $development: { logLevel: 'warning' },
-  $production: { logLevel: 'error' },
+  $test: { logLevel: "silent" },
+  $development: { logLevel: "warning" },
+  $production: { logLevel: "error" },
   $env: {
-    staging: { logLevel: 'debug' }
-  }
-}
+    staging: { logLevel: "debug" },
+  },
+};
 ```
 
-## Watching Configuration
+## 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.
 
@@ -342,24 +377,88 @@ console.log("initial config", config.config);
 // await config.unwatch();
 ```
 
-## 💻 Development
+## Updating config
+
+> [!NOTE]
+> This feature is experimental
+
+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
+```
+
+<!-- /automd -->
+
+Import util from `c12/update`
+
+```js
+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}`);
+```
+
+## Contribution
+
+<details>
+  <summary>Local development</summary>
 
 - Clone this repository
-- Enable [Corepack](https://github.com/nodejs/corepack) using `corepack enable` (use `npm i -g corepack` for Node.js < 16.10)
+- Install the latest LTS version of [Node.js](https://nodejs.org/en/)
+- Enable [Corepack](https://github.com/nodejs/corepack) using `corepack enable`
 - Install dependencies using `pnpm install`
-- Run interactive tests using `pnpm dev`
+- Run tests using `pnpm dev` or `pnpm test`
+
+</details>
+
+<!-- /automd -->
 
 ## License
 
-Made with 💛 Published under [MIT License](./LICENSE).
+<!-- automd:contributors license=MIT author="pi0" -->
+
+Published under the [MIT](https://github.com/unjs/c12/blob/main/LICENSE) license.
+Made by [@pi0](https://github.com/pi0) and [community](https://github.com/unjs/c12/graphs/contributors) 💛
+<br><br>
+<a href="https://github.com/unjs/c12/graphs/contributors">
+<img src="https://contrib.rocks/image?repo=unjs/c12" />
+</a>
+
+<!-- /automd -->
 
-<!-- Badges -->
+<!-- automd:with-automd -->
 
-[npm-version-src]: https://img.shields.io/npm/v/c12?style=flat&colorA=18181B&colorB=F0DB4F
-[npm-version-href]: https://npmjs.com/package/c12
-[npm-downloads-src]: https://img.shields.io/npm/dm/c12?style=flat&colorA=18181B&colorB=F0DB4F
-[npm-downloads-href]: https://npmjs.com/package/c12
-[codecov-src]: https://img.shields.io/codecov/c/gh/unjs/c12/main?style=flat&colorA=18181B&colorB=F0DB4F
-[codecov-href]: https://codecov.io/gh/unjs/c12
-[license-src]: https://img.shields.io/github/license/unjs/c12.svg?style=flat&colorA=18181B&colorB=F0DB4F
-[license-href]: https://github.com/unjs/c12/blob/main/LICENSE
+---
+
+_🤖 auto updated with [automd](https://automd.unjs.io)_
+
+<!-- /automd -->