React + Vite + GraphQL Codegenで`Failed to resolve entry for package"@graphql-typed-document-node/core"`が出た原因と解決方法

エラーの内容

[plugin:vite:import-analysis] Failed to resolve entry for package
"@graphql-typed-document-node/core".
The package may have incorrect main/module/exports specified in its package.json.

Vite の dev server 起動時に発生し、画面を表示できなくなっていた。

結論:
GraphQL Codegen が型専用ライブラリである@graphql-typed-document-node/coreを通常の import として生成しており、Vite が実行時モジュールとして解決しようしたため失敗していた。

エラーが起きた環境

- Node.js: v23.3.0
- Vite: 7.2.4
- React: 19.2.0
- pnpm: 10.1.0
- graphql: 16.12.0
- @graphql-typed-document-node/core: 3.2.0
- @graphql-codegen/cli: 6.1.1
- preset: "client"

Node.js や React のバージョンが新しいことが原因ではなく GraphQL Codegen の生成コードと Vite の import 解決仕様による問題であった。

原因

[plugin:vite:import-analysis] Failed to resolve entry for package
"@graphql-typed-document-node/core".
The package may have incorrect main/module/exports specified in its package.json.

日本語訳
[plugin:vite:import-analysis] パッケージ
「@graphql-typed-document-node/core」 のエントリを解決できませんでした。
このパッケージの package.json で、main/module/exports が正しく指定されていない可能性があります。

このエラーは graphql-codegen によって作成した型ファイルで起こっていた。
コンソールを確認してみると以下の箇所で引っかかっていることがわかった。
import {} from "@graphql-typed-document-node/core";

GraphQL Codegen が生成した import 文は、値を使用していないように見えるが、通常の import として扱われる。そのため、 Vite は ES モジュールとして実行時に解決しようとする。

import {} from ...は値の import をせず、指定したファイルの実行のみを行う(副作用を目的とした import)。
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import

@graphql-typed-document-node/coreは型用途前提のライブラリであり browser / ESM runtime 向けに Vite が解決可能な entry を想定していない。
そのためエラー文で main/module/exports が正しく指定されていないと記述されていた。

Vite は ES モジュールとして実行時にimport を解決しようとする。しかし、 @graphql-typed-document-node/core は型専用ライブラリであり、ブラウザや ESM 実行環境向けのエントリポイント(main/module/exports)が存在しないため、 resolveに 失敗する。そのため、以下のエラーが出力される。

Failed to resolve entry for package

解決方法

Codegen config を修正
configにuseTypeImports:trueを設定する

import type { CodegenConfig } from "@graphql-codegen/cli";

const config: CodegenConfig = {
  overwrite: true,
  schema: "../backend/graph/schema.graphqls",
  documents: "src/**/*.tsx",
  generates: {
    "src/gql/": {
      preset: "client",
      plugins: [],
      config: {
        useTypeImports: true
      }
    },
  },
};

export default config;

型ファイルを再生成する

pnpm graphql-codegen

解決理由

useTypeImports:trueを設定する前のimport文
import { TypeDocumentNode as DocumentNode } from '@graphql-typed-document-node/core'
から設定後のimport文
import type { TypeDocumentNode as DocumentNode } from '@graphql-typed-document-node/core'

この設定を追加することでGraphQL Codegen が生成するコードを import type に置き換えることができる。

import typeは Typescriptコンパイル時に消え、Javascriptには一切残らないためViteはこの import を実行時依存として認識せず、 resoleve の対象から除外される。これによってエラーが解消される。

import typeがTypeScriptコンパイル時に消えることはTypeScriptの公式リファレンスに記載されています。
https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-8.html

参照

この問題が多くの学習者の間で起きている問題のようで@graphql-typed-document-node/coreの GitHub Issue でも議論が行われている。