esbuild-resolve-config

1.0.9 verified Fri May 01 auth: no javascript

A utility to load and resolve JavaScript/TypeScript configuration files using esbuild. It reads configuration from .js, .ts, .mjs, or .cjs files, compiles them on-the-fly with esbuild, and returns the exported config object. Useful for tools that need to consume user config files (e.g., bundler plugins, CLI tools). Version 1.0.9 ships TypeScript type definitions and has no external dependencies beyond esbuild. Released under MIT license. Different from other config resolvers (like cosmiconfig) by leveraging esbuild for fast and correct TypeScript/ESM compilation.

Common errors

error TypeError: resolveConfig is not a function ↓

cause Named import used instead of default import.

fix

Change import to: import resolveConfig from 'esbuild-resolve-config'

error Error: Cannot find module 'esbuild' ↓

cause esbuild is not installed or not in the node_modules tree.

fix

Install esbuild: npm install esbuild --save-dev

error SyntaxError: Unexpected token 'export' ↓

cause The config file uses ES module syntax but the resolver expects a CommonJS export or esbuild handles it incorrectly due to misconfigured loader.

fix

Ensure the config file uses module.exports or default export; check esbuild loader settings if custom.

error Error: Dynamic require of "config.ts" is not supported ↓

cause The config file path resolves to a .ts file but the current Node.js version does not support TypeScript natively, and the resolver fails to invoke esbuild.

fix

Verify that esbuild is properly installed and that the file path is correct. Use an absolute path if necessary.

Warnings

gotcha The resolved config is evaluated via esbuild's transform, not via Node's module system. This means the config file must be self-contained (no Node.js built-ins unless polyfilled) and runs in a sandboxed environment. ↓

fix Ensure the config file does not rely on Node.js globals (e.g., process, require) unless they are provided by esbuild's define or inject features.

gotcha This package bundles esbuild as a dependency, which may lead to version conflicts if your project also uses esbuild with a different version. ↓

fix Ensure esbuild versions are compatible; consider using a single version via dependency resolution (e.g., npm dedupe or yarn resolutions).

breaking Version 1.0.0 changed the API from a named export to a default export. Existing code using named import will break. ↓

fix Use default import: import resolveConfig from 'esbuild-resolve-config' instead of import { resolveConfig }.

Install

npm install esbuild-resolve-config

yarn add esbuild-resolve-config

pnpm add esbuild-resolve-config

Imports

resolveConfig (default)

wrong

import { resolveConfig } from 'esbuild-resolve-config'

correct

import resolveConfig from 'esbuild-resolve-config'

This package uses a default export. Named import will result in undefined.

resolveConfig (require)
wrong
```
const { resolveConfig } = require('esbuild-resolve-config')
```
correct
```
const resolveConfig = require('esbuild-resolve-config')
```
CommonJS require returns the default export directly; destructuring will yield undefined.
resolveConfig (type import)
```
import resolveConfig from 'esbuild-resolve-config'
```
TypeScript users should use default import for type safety; the package exports types via its declaration file.

Quickstart

Demonstrates how to import and call resolveConfig with a TypeScript config file, handling errors.

import resolveConfig from 'esbuild-resolve-config';

async function main() {
  try {
    const config = await resolveConfig('./config.ts');
    console.log('Resolved config:', config);
  } catch (error) {
    console.error('Failed to resolve config:', error);
  }
}

main();