esbuild Target Mismatch Error — Fix (2026)

The Error

X [ERROR] Transforming top-level await is not supported with the "cjs" output format
  src/index.ts:5:0:
    5 | const data = await fetchConfig();
      ^ Top-level await requires "esm" format or target "node18" or higher

This error occurs when esbuild’s target setting does not support syntax features used in your code. Top-level await, import assertions, and decorators require specific target configurations.

The Fix

  1. Update the esbuild target to match your runtime:
// esbuild.config.js
require('esbuild').build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  platform: 'node',
  target: 'node22',
  format: 'esm',
  outfile: 'dist/index.js'
});
  1. Or via CLI:
npx esbuild src/index.ts --bundle --platform=node --target=node22 --format=esm --outfile=dist/index.js
  1. Verify the build:
node dist/index.js

Why This Happens

esbuild transforms modern JavaScript syntax to match the specified target. When the target is older than the syntax used (e.g., target node14 with top-level await which requires Node 14.8+ in ESM), esbuild cannot downcompile certain features and throws an error. Claude-generated code often uses the latest syntax without checking the build target.

If That Doesn’t Work

  • If building for browsers, set appropriate targets:
npx esbuild src/index.ts --bundle --target=chrome100,firefox100,safari15
  • Wrap top-level await in an async IIFE for CJS output:
(async () => {
  const data = await fetchConfig();
})();
  • Check if your tsconfig target conflicts with esbuild target — they should agree.

Prevention

Add this to your CLAUDE.md:

# esbuild Configuration
- Target: node22 for backend, chrome100 for frontend.
- Format: esm for new projects. Only use cjs for legacy compatibility.
- Do not use top-level await in CJS output format.

This fix also applies if you see these related error messages:

  • Error: Claude Code requires Node.js 18 or later
  • SyntaxError: Unexpected token '??' — Node 14 detected
  • MODULE_NOT_FOUND: Cannot find module 'node:fs'
  • Error reading configuration file
  • JSON parse error in config

Frequently Asked Questions

What Node.js version does Claude Code require?

Claude Code requires Node.js 18 or later. Node.js 20 LTS is recommended for the best compatibility and performance. Check your version with node --version.

How do I manage multiple Node.js versions?

Use nvm (Node Version Manager): nvm install 20 && nvm use 20. This lets you switch between Node.js versions per-project without affecting other applications. Add a .nvmrc file with 20 to your project root so nvm automatically selects the right version.

Why does Claude Code fail with the node:fs prefix?

The node: prefix for built-in modules was introduced in Node.js 16. If you see errors about node:fs or node:path, you are running an older Node.js version that does not support this syntax. Upgrade to Node.js 18 or later.

Where does Claude Code store its configuration?

Configuration is stored in ~/.claude/config.json for global settings and .claude/config.json in the project root for project-specific settings. Project settings override global settings for any overlapping keys.

Try it: Paste your error into our Error Diagnostic for an instant fix.

Build Tool Configuration with Claude Code

When Claude Code generates or modifies build configurations, ensure the output matches your project’s build pipeline:

Webpack specifics. Claude Code may generate webpack 4 syntax when your project uses webpack 5. Key differences: module.rules (not module.loaders), asset/resource (not file-loader), and native module federation. Always specify your webpack version in CLAUDE.md.

Vite projects. Claude Code sometimes generates Create React App patterns when the project uses Vite. Add to CLAUDE.md: “This project uses Vite, not CRA. Use import.meta.env for environment variables, not process.env. Dev server runs on port 5173.”

Tree-shaking requirements. For tree-shaking to work, modules must use ES module syntax (import/export), not CommonJS (require/module.exports). Claude Code defaults to whichever pattern it finds in existing code. If your project mixes both, add a CLAUDE.md rule specifying which to use.

Build Error Debugging Steps

When Claude Code’s generated code causes build failures:

  1. Read the full error output. Build tools often show the root cause at the beginning of the output, not the end. Scroll up to find the first error.
  2. Check the import graph. Circular dependencies cause subtle build failures. Run your bundler’s analyze mode to visualize the dependency graph.
  3. Verify TypeScript configuration. If tsconfig.json has strict settings, Claude Code’s generated code must comply. Common issues: missing null checks, implicit any types, and unused imports.