できない.dev

Vite「Failed to load transformWithEsbuild」の原因と直し方

Vite 8 の Failed to load transformWithEsbuild は、esbuild を別に入れるか esbuild を使う設定を外せば直る。
8 から esbuild は Vite の任意の依存になり、一緒には入らなくなった。

公開:

要約

Vite 8 で npx vite build を打つと、次のエラーで止まることがある。

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.

Vite 8 は esbuild を直接使わなくなり、esbuild を任意の依存に下げた(公式の移行ガイド(新しいタブで開く))。
ほかの依存が esbuild を入れていなければ、npm install -D vite@8 のあとに esbuild は無い。
そこへ esbuild を名指しした設定やプラグインがあると、esbuild を読み込めずに build が止まる。
esbuild を devDependencies に入れるか、esbuild を使う設定を外せば直る。

解決策

1. esbuild を名指しする設定を外す

import { defineConfig } from "vite";
 
export default defineConfig({});

build.minify の行を消すと、8 の既定の Oxc で圧縮されて build が通った。
移行ガイドによると、build.minify: "esbuild" は非推奨で、将来の版で無くなる。
build.cssMinify: "esbuild" の行も、消すと通った。

2. esbuild を devDependencies に入れる

npm install -D esbuild

esbuild での圧縮を続けたいときや、プラグインがまだ transformWithEsbuild を呼んでいるときは、エラー文のとおり esbuild を入れる。
入れたあとは minify: "esbuild" のままでも build が通った。
人が作ったプラグインなら、Oxc に移った新しい版が出ていないかも確かめる。

3. 自作のプラグインは transformWithOxc に書き換える

import { defineConfig, transformWithOxc } from "vite";
 
export default defineConfig({
  plugins: [
    {
      name: "my-transform",
      async transform(code, id) {
        if (!id.endsWith(".js")) return;
        const result = await transformWithOxc(code, id);
        return result.code;
      },
    },
  ],
});

移行ガイドは、transformWithEsbuild を非推奨とし、将来の版で無くすと書いている。
代わりに勧めているのが transformWithOxc で、上の形に書き換えると esbuild を入れないまま build が通った。

よくある原因

  1. build.minify: "esbuild" を残したまま Vite を 8 に上げた。
    エラー文の transformWithEsbuild は、Vite が esbuild で圧縮するときに中で呼ぶ関数である。
    自分で呼んでいなくても、この関数の読み込みで止まる。
  2. Vite のプラグインが transformWithEsbuild を呼んでいる。
    transform の中でこの関数を呼ぶだけのプラグインを作って Vite 8.3.8 で試すと、同じエラー文で止まった。
  3. build.cssMinify: "esbuild" を指定している。
    この場合のエラー文は Cannot find package 'esbuild' で、transformWithEsbuild の行は出なかった。

npm ls esbuild が (empty) を返すなら、プロジェクトに esbuild は入っていない。