# @web/config-loader

> Load a esm or cjs config from the file system

Latest version **1.0.0** (published 2026-07-07) · MIT license · 0 weekly downloads

## Install

```sh
npm install @web/config-loader
pnpm add @web/config-loader
yarn add @web/config-loader
bun add @web/config-loader
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2026-07-07 |
| First published | 2020-06-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=22.0.0 |
| Dependencies | 0 |
| Unpacked size | 10.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 2451 |
| Author | modern-web |
| Maintainers | d4kmor, passle, jorenbroekema, bennyp, larsdenbakker, westbrook, modern-web |
| Keywords | web, node, config, loader, esm, es module |

## Links

- npm: https://www.npmjs.com/package/@web/config-loader
- Repository: https://github.com/modernweb-dev/web
- Homepage: https://github.com/modernweb-dev/web/tree/master/packages/config-loader
- Issues: https://github.com/modernweb-dev/web/issues
- npm.io page: https://npm.io/package/@web/config-loader

## Alternatives

- [jsforce](https://npm.io/package/jsforce.md) — 851.2K weekly downloads
- [react-native-qrcode-svg](https://npm.io/package/react-native-qrcode-svg.md) — 693.5K weekly downloads
- [@salesforce/plugin-data](https://npm.io/package/@salesforce/plugin-data.md) — 394.9K weekly downloads
- [@backstage/plugin-search-common](https://npm.io/package/@backstage/plugin-search-common.md) — 308.5K weekly downloads
- [@chain-registry/types](https://npm.io/package/@chain-registry/types.md) — 38.4K weekly downloads

## Recent versions

- 1.0.0 (latest) — 2026-07-07
- 0.0.0-canary-20240219104536 (canary) — 2024-02-19
- 0.3.3 — 2025-04-02
- 0.3.2 — 2024-08-30
- 0.0.0-canary-20240219104126 — 2024-02-19
- 0.0.0-canary-20240212171943 — 2024-02-12
- 0.0.0-canary-20240105101412 — 2024-01-05
- 0.0.0-canary-20240105095248 — 2024-01-05
- 0.0.0-canary-20240105093823 — 2024-01-05
- 0.0.0-canary-20240105092607 — 2024-01-05
- 0.0.0-canary-20240105091725 — 2024-01-05
- 0.0.0-canary-20231122093600 — 2023-11-22
- 0.3.1 — 2023-11-13
- 0.3.0 — 2023-11-01
- 0.2.2 — 2023-10-19
- … 15 more at https://npm.io/package/@web/config-loader/versions

## README

# Config Loader

Load user config files for node js projects. Supports loading config as es module or common js module, based on the user's node version, package type and file extension. Prints helpful error messages when invalid syntax combinations are used.

Follows node's logic for deciding how to load a file. `.mjs` files are loaded as es module, `.cjs` as common js. `.js` files are loaded based on the `type` field of the package.json.

## Usage

```bash
npm i --save-dev @web/config-loader
```

```js
import { readConfig, ConfigLoaderError } from '@web/config-loader';
// Or as a commonjs module
// const { readConfig, ConfigLoaderError } = require('@web/config-loader');

(async () => {
  try {
    // will look for:
    // process.cwd() + 'my-project.config.mjs'
    // process.cwd() + 'my-project.config.cjs'
    // process.cwd() + 'my-project.config.js'
    const config = await readConfig('my-project.config');
  } catch (error) {
    if (error instanceof ConfigLoaderError) {
      // If the error is a ConfigLoaderError it has a human readable error message
      // there is no need to print the stack trace.
      console.error(error.message);
      return;
    }
    console.error(error);
    return;
  }
})();
```

### Custom config file

If you want to let users define a custom config file location, you can pass this as a second optional parameter.

```js
const { readConfig, ConfigLoaderError } = require('@web/config-loader');

(async () => {
  try {
    const optionalCustomConfigFilePath = '...';
    const config = await readConfig('my-project.config', optionalCustomConfigFilePath);
  } catch (error) {
    if (error instanceof ConfigLoaderError) {
      // If the error is a ConfigLoaderError it has a human readable error message
      // there is no need to print the stack trace.
      console.error(error.message);
      return;
    }
    console.error(error);
    return;
  }
})();
```

---
_Source: https://npm.io/package/@web/config-loader · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._