Node.jsのERR_PACKAGE_PATH_NOT_EXPORTEDの直し方

​​Node.js​ES Modules,JavaScript,npm,トラブルシュート

npm のパッケージを新しいバージョンに上げたら、require('uuid/v4') のような、パッケージの中のファイルを直接指す行で Error [ERR_PACKAGE_PATH_NOT_EXPORTED] が出て止まることがあります。原因は、そのパッケージの package.json に exports が書かれていて、読もうとしたパスがそこに含まれていないことです。パッケージが用意している入口(多くは require('uuid') のようなパッケージ名だけの形)から読み直すと、エラーは消えます。

自分で作ったパッケージやモノレポの中のパッケージでこのエラーが出たときは、package.json の exports に、そのパスを書き足すことでも直せます。この記事では、uuid 8 と、検証用に作った小さなパッケージでエラーを起こし、メッセージの全文と、直すと消えることを確かめた結果を載せます。

補足

検証環境は Ubuntu 24.04(x86_64)、Node.js 22.23.4、npm 10.9.9 です。パッケージは uuid 8.3.2 と、比べるための uuid 3.4.0 を使いました。Windows と macOS での動き、TypeScript や webpack・Vite などのツールを通したときに出る同じ種類のエラーは試していません。

uuid 8 で require('uuid/v4') を書くとエラーになる

検証環境で npm init -y を実行し、package.json から type の行を消して(npm pkg delete type)、npm install uuid@8.3.2 で uuid を入れました。uuid の package.json の exports は、次のとおりです。

text
$ node -e "console.log(JSON.stringify(require('./node_modules/uuid/package.json').exports, null, 2))"
{
  ".": {
    "node": {
      "module": "./dist/esm-node/index.js",
      "require": "./dist/index.js",
      "import": "./wrapper.mjs"
    },
    "default": "./dist/esm-browser/index.js"
  },
  "./package.json": "./package.json"
}

外から読めるのは、パッケージ名だけの "."(require('uuid'))と ./package.json の2つです。./v4 はありません。この状態で、古い書き方の index.js を実行します。

js
const uuidv4 = require('uuid/v4');

console.log(uuidv4());

node index.js を実行すると、次のように出て止まりました(終了コードは1。パスは例示用の値に置き換えています)。

text
$ node index.js
node:internal/modules/cjs/loader:671
      throw e;
      ^

Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package subpath './v4' is not defined by "exports" in /path/to/app/node_modules/uuid/package.json
    at exportsNotFound (node:internal/modules/esm/resolve:318:10)
    at packageExportsResolve (node:internal/modules/esm/resolve:665:9)
    at resolveExports (node:internal/modules/cjs/loader:664:36)
    at Function._findPath (node:internal/modules/cjs/loader:731:31)
    at Function._resolveFilename (node:internal/modules/cjs/loader:1415:27)
    at defaultResolveImpl (node:internal/modules/cjs/loader:1040:19)
    at resolveForCJSWithHooks (node:internal/modules/cjs/loader:1045:22)
    at Function._load (node:internal/modules/cjs/loader:1216:25)
    at wrapModuleLoad (node:internal/modules/cjs/loader:254:19)
    at Module.require (node:internal/modules/cjs/loader:1527:12) {
  code: 'ERR_PACKAGE_PATH_NOT_EXPORTED'
}

Node.js v22.23.4

メッセージは「パッケージの中のパス ./v4 は、この package.json の exports に書かれていない」という意味です。uuid/v4 のうち、パッケージ名の後ろの部分が ./v4 として示されます。どのパッケージの package.json を見ればよいかも、in の後ろに出ています。

import uuidv4 from 'uuid/v4'; と書いた ES モジュールの index.mjs でも、同じエラーになりました。違いは、メッセージの最後に読み込んだ側のファイルが付くことと、1行目の場所の表示です。

text
$ node index.mjs
node:internal/modules/esm/resolve:318
  return new ERR_PACKAGE_PATH_NOT_EXPORTED(
         ^

Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package subpath './v4' is not defined by "exports" in /path/to/app/node_modules/uuid/package.json imported from /path/to/app/index.mjs

(at … で始まる行から後は省略しています。)

ファイルが実在していても読めない

uuid 8 の中には dist/v4.js というファイルが実在します。そこで require('uuid/dist/v4.js') と、ファイルのパスを直接書いてみましたが、これも Package subpath './dist/v4.js' is not defined by "exports" で止まりました。exports がある package.json では、ファイルがあるかどうかではなく、exports に書かれているかどうかで読めるかが決まります。

Node.js の公式ドキュメントにある、パッケージの入口(main entry point)の説明にも、"exports" を書くとパッケージの中のパスはすべて外から読めなくなり、require('pkg/subpath.js') は ERR_PACKAGE_PATH_NOT_EXPORTED になる、とあります。エラーコードの一覧にある ERR_PACKAGE_PATH_NOT_EXPORTED の説明も、「exports が、求められたパスを公開していない」ときのエラーとしています。

バージョンを上げたときに出る理由

exports のない uuid 3.4.0 を入れた別のフォルダーでは、同じ index.js がエラーなく UUID を1つ表示しました。uuid の CHANGELOG によると、require('uuid/v4') のような読み方は 7.0.0 で非推奨になり、8.0.0 で使えなくなりました。このように、パッケージが新しいバージョンで exports を書き足したり減らしたりすると、それまで動いていた行でこのエラーが出ます。

使っているパッケージで出たら、用意された入口から読む

自分では直せない npm のパッケージで出たときは、読み方をパッケージに合わせます。uuid の CHANGELOG には、書き換え先として次の形が載っています。

js
const { v4: uuidv4 } = require('uuid');

console.log(uuidv4());

ES モジュールなら、次のように書きます。

js
import { v4 as uuidv4 } from 'uuid';

console.log(uuidv4());

検証環境では、どちらもエラーが出ずに UUID を1つ表示しました(終了コードは0)。

ほかのパッケージでも、まず node_modules/<パッケージ名>/package.json の exports を開いて、どのパスが書かれているかを確かめます。読みたい関数がパッケージ名だけの入口から使えるなら、そこから読みます。exports に書かれていないファイルを読む方法を探すより、そのパッケージの README や CHANGELOG にある書き換え先に従うほうが確実です。

自分のパッケージなら exports に書き足す

モノレポの中のパッケージなど、package.json を自分で直せるときは、exports にパスを足す方法もあります。検証のため、node_modules の中に neko-lib というパッケージを作りました。

json
{
  "name": "neko-lib",
  "version": "1.0.0",
  "exports": {
    ".": "./index.js"
  }
}

中には index.js のほかに lib/format.js があります。これを require('neko-lib/lib/format') で読むと、uuid と同じく Package subpath './lib/format' is not defined by "exports" で止まりました。

1つのパスを足す

exports に "./format": "./lib/format.js" を足しました。左が外から使う名前、右がパッケージの中のファイルです。

json
{
  "name": "neko-lib",
  "version": "1.0.0",
  "exports": {
    ".": "./index.js",
    "./format": "./lib/format.js"
  }
}

require('neko-lib/format') と書いた sub2.js は [neko] と表示しました。一方、元の require('neko-lib/lib/format') は、この状態でもエラーのままでした。足したのは ./format という名前で、./lib/format は書かれていないままだからです。外から使う名前は、ファイルの置き場所と同じでなくてかまいません。

フォルダーの中をまとめて公開する

ファイルが多いときは、* を使った書き方(サブパスパターン)でまとめて公開できます。

json
{
  "name": "neko-lib",
  "version": "1.0.0",
  "exports": {
    ".": "./index.js",
    "./lib/*": "./lib/*.js"
  }
}

この状態では、最初の require('neko-lib/lib/format') が [neko] と表示しました。ただし、require('neko-lib/lib/format.js') と拡張子を付けると、別のエラーになりました(パスは例示用の値に置き換えています)。

text
Error: Cannot find module '/path/to/app/node_modules/neko-lib/lib/format.js.js'

* には format.js がそのまま入り、右側の .js と合わせて format.js.js を探したためです。サブパスパターンの説明にあるとおり、* は文字をそのまま置き換えるだけで、拡張子を特別に扱いません。拡張子を付けて読ませたいなら、"./lib/*.js": "./lib/*.js" のように両側に .js を書きます。

注意

すでに公開しているパッケージに exports を足すと、それまで使えたパスがすべて読めなくなります。公式ドキュメントでも、require('your-package/package.json') まで読めなくなるため、互換性のない変更になりうると注意しています。"./package.json": "./package.json" のように、使われているパスは exports に書いておきます。

import でしか読めないパッケージを require すると「No "exports" main defined」になる

同じエラーコードで、文面が違うものもあります。exports に import の条件しか書かれていないパッケージを、require() で読んだときです。検証用に esm-only-lib を作りました。

json
{
  "name": "esm-only-lib",
  "version": "1.0.0",
  "exports": {
    ".": {
      "import": "./index.mjs"
    }
  }
}

require('esm-only-lib') と書いた cond.js を実行すると、次のように出ました(at … で始まる行から後は省略し、パスは例示用の値に置き換えています)。

text
$ node cond.js
node:internal/modules/cjs/loader:671
      throw e;
      ^

Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: No "exports" main defined in /path/to/app/node_modules/esm-only-lib/package.json

「この package.json の exports に、パッケージ名だけで読んだときの入口がない」という意味です。import の条件は import 文や import() で読んだときだけに当てはまり、require() では当てはまりません(条件付きの exports の説明)。そのため、require() から見ると入口が1つもない状態になります。同じパッケージを import { hello } from 'esm-only-lib'; で読んだ cond.mjs は、hello from esm-only-lib と表示しました。

使う側で直すなら、自分のファイルを ES モジュールにして import で読みます。パッケージ側を直せるなら、どの読み方にも当てはまる default の条件を足します。

json
{
  "name": "esm-only-lib",
  "version": "1.0.0",
  "exports": {
    ".": {
      "import": "./index.mjs",
      "default": "./index.mjs"
    }
  }
}

この状態で node cond.js を実行すると、hello from esm-only-lib と表示しました。公式ドキュメントでは、default はいつも最後に書くものとされています。なお、ここで default が指しているのは ES モジュールの .mjs です。Node.js 22.23.4 は require() で ES モジュールを読めるため通りましたが、require() で ES モジュールを読む機能が既定で有効になったのは Node.js 22.12.0 と 20.19.0 からです。この機能は、公式ドキュメントでは今も安定版になる前の段階(Stability 1.2、Release candidate)とされています。

ポイント

メッセージの Package subpath '…' に出たパスが、in の後ろにある package.json の exports に書かれているかを見ます。npm のパッケージならパッケージが用意した入口から読み直し、自分のパッケージなら exports に書き足すと、エラーは消えます。

​Posted by 86