vitejs/vite · error · Error

Failed to load `transformWithEsbuild`. It is deprecated and

Error message

Failed to load `transformWithEsbuild`. It is deprecated and it now requires esbuild to be installed separately. If you are a package author, please migrate to `transformWithOxc` instead.

What it means

Thrown by the deprecated `transformWithEsbuild` API when the `esbuild` package cannot be dynamically imported. Vite no longer bundles esbuild, so calling this legacy helper requires the project to install esbuild itself. The message directs package authors to migrate to `transformWithOxc`.

Source

Thrown at packages/vite/src/node/plugins/esbuild.ts:224

    ...options,
    loader,
    tsconfigRaw,
  }

  // Some projects in the ecosystem are calling this function with an ESBuildOptions
  // object and esbuild throws an error for extra fields
  // @ts-expect-error include exists in ESBuildOptions
  delete resolvedOptions.include
  // @ts-expect-error exclude exists in ESBuildOptions
  delete resolvedOptions.exclude
  // @ts-expect-error jsxInject exists in ESBuildOptions
  delete resolvedOptions.jsxInject

  let transform: typeof import('esbuild').transform
  try {
    transform = (await importEsbuild()).transform
  } catch (e) {
    throw new Error(
      'Failed to load `transformWithEsbuild`. ' +
        'It is deprecated and it now requires esbuild to be installed separately. ' +
        'If you are a package author, please migrate to `transformWithOxc` instead.',
      { cause: e },
    )
  }

  if (!ignoreEsbuildWarning) {
    warnTransformWithEsbuildUsageOnce()
  }

  try {
    const result = await transform(code, resolvedOptions)
    let map: SourceMap
    if (inMap && resolvedOptions.sourcemap) {
      const nextMap = JSON.parse(result.map)
      nextMap.sourcesContent = []
      map = combineSourcemaps(filename, [

View on GitHub (pinned to 89620f09af)

Solutions

1. Run `npm i -D esbuild` if you genuinely need the legacy transform.
2. Migrate the call site from `transformWithEsbuild` to `transformWithOxc` (the message's recommendation).
3. If a plugin triggers it, update/replace that plugin or open an issue with the author to migrate.
4. Stop calling the deprecated helper directly — use Vite's built-in TS/JSX pipeline.

Example fix

// before
import { transformWithEsbuild } from 'vite';
const out = await transformWithEsbuild(code, 'a.ts', { loader: 'ts' });
// after
import { transformWithOxc } from 'vite';
const out = await transformWithOxc(code, 'a.ts', { typescript: {} });

import { createRequire } from 'node:module';
const require = createRequire(import.meta.url);

function ensureEsbuildOrMigrate() {
  try { require.resolve('esbuild'); }
  catch { throw new Error('esbuild not installed — install it or migrate to transformWithOxc'); }
}
// call only if you intentionally use transformWithEsbuild

try {
  await transformWithEsbuild(code, 'a.ts');
} catch (e) {
  if (/Failed to load `transformWithEsbuild`/.test(e.message)) {
    await installMissing('esbuild'); // or switch to transformWithOxc
  }
  throw e;
}

When it happens

Trigger: Calling `transformWithEsbuild(code, filename)` (or a plugin that calls it) when `esbuild` is not resolvable — the `importEsbuild()` dynamic import throws and is caught, then re-thrown with this message and `{ cause: e }`.

Common situations: A third-party Vite plugin still calling `transformWithEsbuild`; code migrated from an older Vite that bundled esbuild; explicitly using `transformWithEsbuild` in config without installing esbuild.

Related errors

• oxc transform error
• oxc transform error
• [module runner] "import.meta.glob" is statically replaced du
• [vite]: Rolldown failed to resolve import "${exporter}" from
• Not implemented

AI-assisted analysis of vitejs/vite@89620f09af (2026-08-03). Data as JSON: /data/errors/e509cdfcb8f91115.json. Report an issue: GitHub.