cosmic-esbuild

0.7.2 verified Fri May 01 auth: no javascript

A configuration loader for esbuild that integrates with cosmiconfig, allowing users to define esbuild build options in familiar config formats (JSON, YAML, TOML, JS, TS, etc.) without custom scripts. Current stable version is 0.7.2, with monthly releases. Supports ESM and CommonJS, ships TypeScript types. Unlike esbuild's CLI, it auto-loads config from standard locations and supports watch mode. Requires Node >=20 and esbuild >=0.25.

Common errors

error Error: Cannot find module 'cosmic-esbuild' ↓

cause Package not installed or not in node_modules.

fix

Run npm install cosmic-esbuild in your project.

error TypeError: cosmicEsbuild is not a function ↓

cause Importing named export when default export should be used.

fix

Use import cosmicEsbuild from 'cosmic-esbuild' (default import).

error Error: esbuild version >=0.25 is required ↓

cause Installed esbuild version is too old.

fix

Upgrade esbuild: npm install esbuild@latest

error Error: Config file not found ↓

cause No configuration file in standard locations or specified path is wrong.

fix

Create a config file like esbuild.config.js, or use --config flag with correct path.

Warnings

breaking Required Node.js >=20 as of v0.6.0 ↓

fix Upgrade Node.js to version 20 or higher.

breaking Peer dependency esbuild >=0.25 required since v0.7.0 ↓

fix Ensure esbuild is installed at version 0.25 or later.

deprecated Direct e18e dependency removed in v0.7.2 ↓

fix No action needed; dependency was removed.

gotcha CLI does not support all esbuild options; only basic flags are available. ↓

fix Use a configuration file for full esbuild build options.

gotcha Default outdir is not cwd; must be set explicitly or via config. ↓

fix Set 'outdir' in config or use --outdir flag.

Install

npm install cosmic-esbuild

yarn add cosmic-esbuild

pnpm add cosmic-esbuild

Imports

cosmicEsbuild
wrong
```
const cosmicEsbuild = require('cosmic-esbuild')
```
correct
```
import cosmicEsbuild from 'cosmic-esbuild'
```
Default export; CJS require() works in Node but the package is ESM-first.
cosmicEsbuild
```
import cosmicEsbuild from 'cosmic-esbuild'
```
Default export; CJS require() works in Node but the package is ESM-first.

build

wrong

import build from 'cosmic-esbuild'

correct

import { build } from 'cosmic-esbuild'

Named export for programmatic use; not the default export.

Quickstart

Shows both config file and programmatic usage of cosmic-esbuild to build an esbuild project.

// Install: npm install cosmic-esbuild

// cosmic-esbuild.config.js
export default {
  entryPoints: ['src/index.js'],
  outdir: 'dist',
  bundle: true,
  minify: true,
  sourcemap: true,
  platform: 'node',
  target: 'node20'
}

// Run:
// npx cosmic-esbuild
// or programmatically:
import cosmicEsbuild from 'cosmic-esbuild';
const result = await cosmicEsbuild();
console.log('Build completed', result);