unconfig

A universal solution for loading configurations.

This is a fork

The goal of this fork is to remove importx as it brings in a large dependency graph. If you're:

• Using plain JSON, JS, or TS (that's supported by the environment, like Deno or Bun)
• Only editing the config file and not the files it's importing (those files would require a hard restart)
• Writing in plain ESM or CJS syntax (not mixed, no illegal use of __filename in ESM, etc)

In other words, have a very simple config file, then this fork should help reduce the dependencies needed to install in your project. (Sorry Anthony but I wanted to trim it down for my own projects 😅)

This fork is meant to be used as an override. For example:

{
  "overrides": {
    "unconfig": "npm:@bluwy/unconfig@^0.6.0"
  },
  "pnpm": {
    "overrides": {
      "unconfig": "npm:@bluwy/unconfig@^0.6.0"
    }
  }
}

DO NOT USE THIS FORK DIRECTLY.

Why?

Configuration is hard, especially when you want to build an ecosystem of your tools.

You want your tools to be general and easy to use, you allow your config to be defined in a custom field of package.json.

You want your tools to be easy to integrate, you allow the configs to be defined in other tools' configurations like vite.config.js or webpack.config.js.

You want the configs to be agnostic and probably need to be load by IDE, you create new config files like .myconfigrc.

You want the configs to also be flexible and dynamic, you make your config files a JavaScript file, like my.config.js.

Then you want users to be able to use ESM and TypeScript, you also make your config accepting .ts or .mjs.

So users' project root end up with a lot of config files like .npmrc, rollup.config.js, .eslintrc, tsconfig.json, jest.config.js, postcss.config.js, nuxt.config.js, vite.config.cjs, windi.config.ts, etc. And each of them use different syntax, in JSON, in CJS, in ESM, in TypeScript, in INI, in TOML...

unconfig can't solve this fragmentation entirely, but it's trying to make loading them easier for tool authors.

Usage

npm i unconfig

For example, to load config for my.config:

import { loadConfig } from 'unconfig'

const { config, sources } = await loadConfig({
  sources: [
    // load from `my.config.xx`
    {
      files: 'my.config',
      // default extensions
      extensions: ['ts', 'mts', 'cts', 'js', 'mjs', 'cjs', 'json', ''],
    },
    // load `my` field in `package.json` if no above config files found
    {
      files: 'package.json',
      extensions: [],
      rewrite(config) {
        return config?.my
      },
    },
    // load inline config from `vite.config`
    {
      files: 'vite.config',
      async rewrite(config) {
        const resolved = await (typeof config === 'function' ? config() : config)
        return resolved?.my
      },
    },
    // ...
  ],
  // if false, the only the first matched will be loaded
  // if true, all matched will be loaded and deep merged
  merge: false,
})

unconfig supports loading ts, mjs, js, json by default.

Sponsors

License

MIT License © 2021-PRESENT Anthony Fu