unconfig

unconfig is a universal configuration loader for JavaScript and TypeScript tools. It lets tool authors accept configuration from many sources, dedicated config files (.myconfigrc, my.config.ts/js/mjs/cjs/json), a custom field in package.json, or embedded inside another tool’s config like vite.config.js, and resolve them through a single loadConfig() call.

It handles the messy reality of config fragmentation: multiple file extensions, ESM, CommonJS, TypeScript, and JSON, with configurable source precedence and rewrite hooks to reshape whatever it finds. Widely used across the antfu/UnoCSS ecosystem, unconfig is downloaded over a million times a week and powers config loading for many popular dev tools.

What You Get

• A single loadConfig() function that resolves config from files, package.json fields, and inline sources
• Support for TypeScript, ESM, CommonJS, and JSON config files with configurable extensions
• Ordered source precedence with optional merge of all matched sources
• rewrite hooks to reshape or extract config from arbitrary structures (e.g. a field inside vite.config)
• Return of both the resolved config and the list of source files that produced it

Common Use Cases

• Loading a dev tool’s configuration from multiple possible file names and formats
• Reading a tool’s settings from a custom field in the user’s package.json
• Extracting embedded config from another tool’s config file via a rewrite hook

Under The Hood

Architecture - unconfig is a pnpm monorepo whose primary package exposes loadConfig(). Given an ordered list of source descriptors (file globs, extensions, optional rewrite functions), it walks up the directory tree to find matching files, loads each via a runtime loader that transpiles TypeScript/ESM on the fly, applies any rewrite to reshape the result, and returns the resolved config along with the sources array. It can stop at the first match or merge all matched sources depending on options.

Tech Stack - Written in TypeScript, built with tsdown, tested with Vitest, and linted with the antfu ESLint config. It relies on esbuild-based transpilation to load TypeScript and ESM config files at runtime without a separate build step.

Code Quality - The repo has a Vitest config and test suite, a shared ESLint config, and frequent releases (45+) under the well-maintained antfu-collective, signalling solid engineering conventions despite modest recent commit volume.

API Design - The public surface is essentially one async function, loadConfig(), configured declaratively through a sources array. The design pushes complexity into data (source descriptors and rewrite callbacks) rather than a large API, so tool authors integrate it with minimal code while retaining fine control over precedence and shape.