できない.dev

esbuild「No loader is configured for」の原因と直し方

esbuild の No loader is configured for は、画像やフォントなど既定のローダーが無い拡張子を import すると出る。
--loader:.png=file などで拡張子ごとにローダーを指定すれば直る。

公開: 更新:

症状できない · exit 1
npx esbuild src/app.js --bundle --outfile=out/app.js
…
✘ [ERROR] No loader is configured for ".png" files: src/logo.png
    src/app.js:1:17:
      1 │ import logo from "./logo.png";
解決後できた · exit 0
npx esbuild src/app.js --bundle --loader:.png=file --outdir=out
  out/app.js             123b
  out/logo-NJRUOINY.png   70b

⚡ Done in 1ms

2026-11-05 に node:22-bookworm-slim（esbuild 0.28.2 / Node.js 22.23.4） で実際に打って取った出力。検証環境の詳細

要約

画像を import した JavaScript を --bundle でまとめると、esbuild 0.28.2 は次のエラーで止まった。
終了コードは 1 だった。

✘ [ERROR] No loader is configured for ".png" files: src/logo.png
 
    src/app.js:1:17:
      1 │ import logo from "./logo.png";
        ╵                  ~~~~~~~~~~~~

No loader is configured for は、その拡張子をどう読むか（ローダー）が決まっていないことを示す。
esbuild が既定で読めるのは .js・.ts・.jsx・.tsx・.json・.css・.txt などに限られる。
画像やフォントに使う file と dataurl のローダーは、既定では有効になっていない（Content Types（新しいタブで開く））。

実行例

.png の import と CSS の url() で No loader is configured が出て、終了コードは 1 だった。--loader:.png=file と --loader:.png=dataurl では終了コード 0 で通り、.woff2 だけの指定では .svg で同じエラーが残った。.woff2 と .svg を両方指定すると通った。

$ npx esbuild --version
0.28.2
$ npx esbuild src/app.js --bundle --outfile=out/app.js
✘ [ERROR] No loader is configured for ".png" files: src/logo.png
 
    src/app.js:1:17:
      1 │ import logo from "./logo.png";
        ╵                  ~~~~~~~~~~~~
 
1 error
$ echo $?
1
$ npx esbuild src/style.css --bundle --outdir=out
✘ [ERROR] No loader is configured for ".svg" files: src/i.svg
 
    src/style.css:2:19:
      2 │ body { background: url(./i.svg); font-family: F; }
        ╵                    ~~~~~~~~~~~~
 
✘ [ERROR] No loader is configured for ".woff2" files: src/f.woff2
 
    src/style.css:1:34:
      1 │ @font-face { font-family: F; src: url(./f.woff2) format("woff2"); }
        ╵                                   ~~~~~~~~~~~~~~
 
2 errors
$ echo $?
1
$ npx esbuild src/app.js --bundle --loader:.png=file --outdir=out
  out/app.js             123b 
  out/logo-NJRUOINY.png   70b 
 
⚡ Done in 1ms
$ echo $?
0
$ ls out
app.js
logo-NJRUOINY.png
$ grep console out/app.js
  console.log(logo_default);
$ npx esbuild src/app.js --bundle --loader:.png=dataurl --outfile=out/app.js
  out/app.js  222b 
 
⚡ Done in 1ms
$ echo $?
0
$ grep -o 'data:image/png;base64,.\{12\}' out/app.js
data:image/png;base64,iVBORw0KGgoA
$ npx esbuild src/style.css --bundle --loader:.woff2=file --outdir=out
✘ [ERROR] No loader is configured for ".svg" files: src/i.svg
 
    src/style.css:2:19:
      2 │ body { background: url(./i.svg); font-family: F; }
        ╵                    ~~~~~~~~~~~~
 
1 error
$ echo $?
1
$ npx esbuild src/style.css --bundle --loader:.woff2=file --loader:.svg=file --outdir=out
  out/style.css         169b 
  out/i-ACF4LSM7.svg     63b 
  out/f-HS6QJUEO.woff2   20b 
 
⚡ Done in 1ms
$ echo $?
0
$ grep url out/style.css
  src: url("./f-HS6QJUEO.woff2") format("woff2");
  background: url("./i-ACF4LSM7.svg");

— 2026-11-05 時点の出力

検証環境Node.js 22.23.4 / npm 10.9.9 / esbuild 0.28.2 / 2026-11-05 検証
検証日
実行環境
node:22-bookworm-slim Debian GNU/Linux 12 (bookworm)
バージョン
  • Node.js 22.23.4
  • npm 10.9.9
  • esbuild 0.28.2

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

1. 別ファイルとして出力する

npx esbuild src/app.js --bundle --loader:.png=file --outdir=out

file ローダーは画像を出力先へコピーし、import した値はそのファイル名になる。
実行すると out/logo-IIHP73UV.png が作られ、バンドルの中では "./logo-IIHP73UV.png" という文字列になった。

2. 小さなファイルは埋め込む

npx esbuild src/app.js --bundle --loader:.png=dataurl --outfile=out/app.js

dataurl ローダーはファイルを Base64 の data URL にしてバンドルへ埋め込む。
リクエストは減るが、大きな画像を埋め込むとバンドルが重くなる。

3. 拡張子ごとに指定する

npx esbuild src/style.css --bundle --loader:.woff2=file --loader:.svg=file --outdir=out

ローダーは拡張子ごとの指定なので、使っている拡張子をすべて並べる。.woff2 だけを指定したときは、同じ CSS の .svg で同じエラーが出た。
両方を並べると、CSS の url() は出力したファイル名に書き換わった。
JavaScript API では loader: { ".png": "file", ".woff2": "file" } のように渡す。

4. JSX で別のエラーが出るとき

.js に JSX を書いている場合は、The JSX syntax extension is not currently enabled という別のエラーになる。
こちらも --loader:.js=jsx で .js を JSX として読ませると通った。

よくある原因

  1. JavaScript から画像を import している。
    Vite は画像の import を設定なしで扱うので、同じコードを esbuild でバンドルするとこのエラーになる。
  2. CSS の url() でフォントや画像を参照している。
    CSS をバンドルすると url() の先も読み込もうとするので、@font-face の url(./f.woff2) が No loader is configured for ".woff2" files で止まった。
#esbuild #loader #image #font #bundle