ツイートはてブ LINE Pocket

GraphQL

WebStorm では、GraphQL 言語(英語)をサポートする GraphQL プラグインを使用できます。次の機能が利用可能です。

スキーマ定義言語 (SDL)(英語) を含む GraphQL 仕様の完全な言語サポート。
スキーマ対応の補完、エラーのハイライト、ドキュメント化。
構文のハイライト、コードのフォーマット、折りたたみ、コメント、中括弧の一致。
その場でローカルスキーマの検出(英語)。リモートスキーマは、イントロスペクションを使用して簡単に取得できます。GraphQL エンドポイントをイントロスペクトし、GraphQL タイプシステム定義言語を使用してスキーマ宣言ファイルを生成できます。
構成可能なプロジェクトスコープまたは graphql-config ファイルを使用したマルチスキーマプロジェクト(英語)のサポート。スキーマ検出は、graphql-config ファイルを使用して構成されます。これには、マルチスキーマプロジェクトのサポートが含まれます。
アポログラフ QL(英語) およびリレー(英語)プロジェクトの組み込みサポート: JavaScript および TypeScript の graphql および gql タグ付きテンプレートリテラルは、自動的に GraphQL として認識されます。
カスタムヘッダーと環境変数のサポートを含む、構成可能なエンドポイントに対して変数を使用したクエリの実行。
スキーマタイプ、フィールド、フラグメントの場合は使用箇所の検索および宣言に移動。
構造ビューは、GraphQL ファイルを移動します。
変数をシェル、.env ファイルからロードするか、構成ファイルごとに手動で設定します。
組み込み Relay、Federation、Apollo Kotlin 型定義 ( 設定 | 言語 & フレームワーク | GraphQL で有効にする必要があります)。

GraphQL は、JetBrains マーケットプレイス(英語)から入手できる専用の GraphQL(英語) プラグインを通じてサポートされます。

GraphQL プラグインをインストールする

Ctrl+Alt+S を押して設定を開き、設定 | プラグインを選択します。
マーケットプレースタブで、検索フィールドに「graph 」と入力し、リストから GraphQL を選択して、インストールをクリックします。

GraphQL を使用するようにアプリケーションを構成する

スキーマタイプを検出する方法を構成することが重要です。スキーマタイプ WebStorm の情報に基づいて、コード補完やエラーのハイライトなどのコーディング支援を提供します。

スキーマとその型は、GraphQL スキーマ定義言語 (英語) (SDL と略されることも多い) としても広く知られている GraphQL タイプシステム定義言語を使用して宣言されます。SDL でスキーマを作成している場合、プラグインは次の機能を提供します。

フィールド、引数、実装されたインターフェースなどを定義するときの型の補完。
不明な型、型の間違った使用、インターフェースの実装時のフィールドの欠落などのスキーマエラーをエラーでハイライトします。
SDL での使用箇所を検索し、名前変更などのリファクタリングを行うと、関連するクエリやミューテーションなどが更新されます。

単一スキーマのプロジェクトの場合、スキーマタイプはユーザー側で追加の構成を行わなくても自動的に検出されます。WebStorm は、プロジェクトファイルのスコープ内のすべての .graphql ファイルを処理して型定義を取得し、検出された型定義をシングルトンタイプレジストリに追加します。プロジェクトファイルスコープに挿入された GraphQL 文字列は、すべての JavaScript ファイルタイプ (.vue などの .js、.jsx、.ts、.tsx、.html、html ベースのファイル) に対して処理されます。

複数のスキーマを持つプロジェクトの場合は、各スキーマのスコープを構成する必要があります。スキーマ固有のスコープにより、各型が 1 回だけ宣言され、1 つの GraphQL 型レジストリのみで選択されることが保証されるため、検証エラーが防止されます。さらに、スコープにより、競合しない型が補完に表示されるのを防ぎ、検証で現在のスキーマに属する型のみが認識されるようになります。

GraphQL 構成の概要(英語)の詳細を参照してください。

基本構成

プロジェクトツールウィンドウで、単純な構成ファイルを作成するフォルダーにカーソルを置き、新規 | GraphQL 構成を選択します。

WebStorm はファイル graphql.config.yml を作成し、エディターで開きます。

                        schema: schema.graphql
                        documents: '**/*.graphql'
                    

この構成ファイルには、スキーマ定義を schema .graphql ファイルに配置する必要があることが記載されています。documents キーは、現在のディレクトリまたはネストされたディレクトリ内の GraphQL 操作を含むグロブパターンを使用して定義されます。操作という用語は、GraphQL クエリとフラグメントのみを指し、型定義は指しません。

絶対パスとして明示的に定義されていない限り、パスは config ディレクトリに対して相対的に指定されることに注意してください。./ という接頭辞を付ける必要はありません。schema.graphql だけで十分です。同じことがグロブパターンにも当てはまります。

node_modules の設定

node_modules フォルダーのスキーマを使用するには、GraphQL 構成ファイル (例: graphql.config.yml) を作成し、次のようにスキーマへの正確なパスを指定します。

schema: node_modules/@octokit/graphql-schema/schema.graphql

複合スキーマ

GraphQL Config は、次のようにスキーマファイルのリストを指定することで、複数のモジュール化されたスキーマを 1 つの GraphQL スキーマオブジェクトに組み立てることもできます。

                schema:
                  - ./foo.graphql
                  - ./bar.graphql
                  - ./baz.graphql
            

あるいは、グロブパターンを使用してスキーマの一部を検索して含めることもできます。

                schema: ./*.graphql # includes every GraphQL file in current directory
                # OR
                schema: ./**/*.graphql # includes GraphQL files recursively
            

GraphQL Config は、指定されたファイルを検索し、これらのファイルを読み取り、マージして GraphQL スキーマオブジェクトを生成します。

リモートスキーマ

GraphQL エンドポイントがあり、ローカルスキーマファイルがまだない場合は、1 つ以上のエンドポイントを定義してイントロスペクションクエリを作成できます。これにより、サーバーからスキーマがロードされ、それが GraphQL ファイルに変換され、IDE のキャッシュディレクトリに保存されます。

エンドポイントに追加の構成が必要かどうかに応じて、文字列として指定することも、ヘッダーなどのデータを含む補助キーを含むオブジェクトとして指定することもできます。

schema: https://my.api.com/graphql

                  schema:
                    - https://my.api.com/one/graphql
                    - https://my.api.com/two/graphql
            

                  schema:
                    - https://my.api.com/one/graphql:
                        headers:
                          Authorization: Bearer ${TOKEN}
            

ローカルイントロスペクションスキーマ

イントロスペクション結果をローカルに保存するには、従来の構成形式で行われたようにエンドポイントを構成します。エンドポイント拡張機能で 1 つまたは複数のエンドポイントを定義し、イントロスペクションクエリを作成します。ファイルは、対応するスキーマセクションの最初のパスに保存されます。たとえば、次の例の local.graphql ファイルです。

                schema: local.graphql
                extensions:
                  endpoints:
                    One:
                      url: https://my.api.com/one/graphql
                      headers:
                        Authorization: bearer ${TOKEN}
                    Two:
                      url: https://my.api.com/two/graphql
            

詳細な構成

どのファイルをスキーマに含めるかをより詳細に制御するには、オプションの include キーと exclude キーを使用します。まず、候補ファイルが除外対象かどうかチェックされます。ファイルが除外されない場合、ファイルパスは include パターンと照合されます。

以下の例では、schema.graphql と、__tests__ ディレクトリ内のファイルを除く src ディレクトリ内のすべてのファイルがそのプロジェクトに含まれます。

                schema: schema.graphql
                exclude: 'src/**/__tests__/**'
                include: src/**
            

複数のプロジェクト

プロジェクトごとの構成

config ファイルは、package .json または同様のファイルと同様に、GraphQL "module" ルートを定義します。config ファイルが空の場合でも、そのディレクトリおよびネストされたディレクトリ内のすべてのファイルは、その構成に関連付けられたスキーマを使用します。

異なるスキーマを分離する最も簡単な方法は、スキーマが完全に独立している場合 (通常はモノリポジトリの場合)、各サブディレクトリ内に構成ファイルを作成することです。このアプローチでは、各 config ファイルの場所によってサブツリーごとに個別のスコープが作成されます。

単一構成

単一の構成ファイルを使用したい場合は、同じファイル内で複数のプロジェクトを指定できます。

                        - project root/
                            - .graphql.config.yml <-----
                            - frontend (schema one)/
                                - schema files and graphql aware components
                            - backend (schema two)/
                                - schema files and graphql aware components
                            - queries/
                    

このような場合の構成は次のようにする必要があります。

                        projects:
                          frontend:
                            schema: https://my.api.com/graphql
                            documents: frontend/**/*.{graphql,js,ts}
                          backend:
                            schema: backend/schema.graphql
                            documents: backend/**/*.graphql
                    

ファイルは、プロジェクトが定義されている順序でプロジェクトと照合されます。ファイルが複数のプロジェクトに一致する場合は、最初のプロジェクトが選択されます。

特定のプロジェクトに include キーまたは exclude キーが定義されていない場合、GraphQL 操作は非厳密に一致します。これは、クエリまたはフラグメントがどのプロジェクトにも明示的に一致しない場合、ファイルは include キーまたは exclude キーを持たない最初のプロジェクトに関連付けられることを意味します。上の例では、backend と frontend に加えて、queries という追加のルートディレクトリがあります。queries に、提供されたパターンのいずれにも一致しない GraphQL ドキュメントが含まれている場合、最初のプロジェクト frontend がそれらのクエリに関連付けられます。

これを実現するには、exclude パターンを frontend プロジェクト構成に追加します。これにより、queries フォルダー内のファイルが backend プロジェクトに関連付けられます。

                        projects:
                          frontend:
                            schema: https://my.api.com/graphql
                            documents: frontend/**/*.{graphql,js,ts}
                            exclude: queries/**  # <--- will enable strict matching for that project
                          backend:
                            schema: backend/schema.graphql
                            documents: backend/**/*.graphql
                    

前述したように、これは型定義には適用されません。WebStorm は、schema キーまたは include キーと厳密に一致するファイルの型定義のみを使用します。

構成ファイル

WebStorm は、次の形式の構成ファイルを認識します。

graphql.config.json
graphql.config.js
graphql.config.cjs
graphql.config.mjs
graphql.config.ts
graphql.config.mts
graphql.config.cts
graphql.config.yaml
graphql.config.yml
.graphqlrc (YAML と JSON)
.graphqlrc.json
.graphqlrc.yaml
.graphqlrc.yml
.graphqlrc.js
.graphqlrc.mjs
.graphqlrc.ts
.graphqlrc.mts
.graphqlrc.cts

YAML

プラグインのインストールの説明に従って、設定 | プラグインページのインストール済みタブで YAML バンドルプラグインが有効になっていることを確認します。

JavaScript

コンピューターに Node.js(英語) があることを確認してください。Node.js は、JavaScript 構成ファイルをダウンロードするために使用されます。
WebStorm は構成ファイルをトランスパイルしないため、Node.js モジュールシステムに適切なファイルを使用して記述されていることを確認してください。以下の例では、export default の代わりに module.exports 構文が使用されています。
module.exports = { schema: 'https://localhost:8000' }
構成で ESM(英語) を使用するには、"type": "module" を package.json ファイルに追加します。

TypeScript

コンピューターに Node.js(英語) があることを確認してください。Node.js は、TypeScript 構成ファイルのダウンロードに使用されます。
TypeScript 構成をロードするには、組み込みのターミナルツールウィンドウ Alt+F12 で次のコマンドのいずれかを入力して、ts-node パッケージをダウンロードしてインストールします。
- npm install --save-dev ts-node を使用して、プロジェクトにパッケージをインストールします。
- npm install --g ts-node を使用してパッケージをグローバルにインストールします。コンピューター
Typestrong ts ノード(英語)の詳細を参照してください。
プロジェクトで ESM モジュールを使用するには:
- package .json ファイルで ESM モジュールを "type": "module" として構成します。
- 以下を tsconfig.json ファイルに追加して、ts-node 用の ESM ローダーをセットアップします。
  { "compilerOptions": { // or ES2015, ES2020 "module": "ESNext" }, "ts-node": { "esm": true } }
ネイティブ ECMAScript モジュール(英語)の詳細を参照してください。

マイグレーション

.graphqlconfig などのレガシー構成ファイルを使用している場合は、この目的に最も便利な YAML など、選択した最新の形式に変換することを強くお勧めします。WebStorm には自動変換ツールが組み込まれており、レガシーファイルを開くとすぐにエディターの上部に通知パネルが表示されます。通知パネルでマイグレーションをクリックするだけで、構成キーと環境変数の構文が自動的に更新されます。

以前に複合スキーマを構成するために使用されていた既存の includes パターンを新しい schema キーに移行することをお勧めします。環境変数の構文が異なることに注意してください。たとえば、デフォルト値の指定がサポートされています。

レガシー構成

それでも従来の構成形式を使用したい場合は、includes プロパティでスキーマファイルへのパスを明示的に指定してください。それ以外の場合は、schemaPath の型のみがスキーマの構築に使用されます。

                {
                      "schemaPath": "schema.graphql",
                      "includes": [
                          "Types1.graphql",
                          "types/**/*.graphql",
                          "src/files/*.{graphql,js,ts}",
                          "everything/inside/**"
                      ],
                      "excludes": [
                          "types/excluded/**"
                      ]
                  }
            

環境変数

構成ファイルで環境変数を使用して、スキーマパス、URL、ヘッダー値を指定できます。構成ファイルで環境変数を使用するための構文は次のとおりです。

                ${VARIABLE_NAME}
                ${VARIABLE_WITH_DEFAULT:./some/default/file.graphql}
                ${VARIABLE_QUOTED:"http://localhost:4000/graphql"}
            

フォールバック値の有無にかかわらず、環境変数から定義をロードできます。

schema: ${SCHEMA_FILE:./schema.json}

フォールバックエンドポイントを定義する場合は、値を引用符で囲む必要がある可能性があります。

schema: ${SCHEMA_ENDPOINT:"http://localhost:4000/graphql"}

.env ファイル

環境変数を指定するにはいくつかの方法があります。最も推奨される方法は、変数値を含む専用のファイルを作成することです。資格情報の公開を避けるため、このファイルをコミットしないでください。

次のファイル名が上から下の優先順位でサポートされています。

.env.local
.env.development.local
.env.development
.env.dev.local
.env.dev
.env

WebStorm は、対応する構成ファイルを含むディレクトリからプロジェクトのルートまで、指定されたファイルを検索します。

このようなファイルでは、環境変数は、= 記号で区切られた単純なキーと値のペアとして表されます。オプションで値を引用符で囲むことができます。

                    S3_BUCKET="YOURS3BUCKET"
                    SECRET_KEY=YOURSECRETKEYGOESHERE # comment
                    SECRET_HASH="something-with-a-#-hash"
                

手動構成

.env ファイルを使用するには、次のいずれかの手順を実行して、構成ファイルごとに環境変数を手動で指定します。

構成ファイル内の GraphQL 環境変数を編集するには、エディターでファイルを開き、任意の場所を右クリックしてコンテキストメニューを開き、GraphQL 環境変数を編集するを選択します。これによりモーダルダイアログが開き、ファイル内の各環境変数の値を指定できます。
任意の GraphQL ファイルを開き、ツールバーをクリックします。ダイアログは、一致する構成ファイルを自動的に検索します。
それ以外の場合は、最初のイントロスペクションクエリまたは GraphQL リクエストで欠落変数のみがリクエストされます。

システム

.env ファイル内に変数が見つからない場合、または手動で設定された変数がない場合、WebStorm はシステム環境から変数を取得しようとします。

フレームワーク

ギャツビー

次の内容を含む graphql.config.js をプロジェクトのルートに作成します。

module.exports = require("./.cache/typegen/graphql.config.json")

イントロスペクション

解決、完了、検証を行うために、WebStorm にはスキーマが必要です。これは、事前に構成する必要があるイントロスペクションクエリを実行することで実現できます。

イントロスペクションクエリを実行する

YAML または JSON 設定ファイルを開き、ガターのをクリックします。これにより、イントロスペクションクエリが実行され、設定に応じて IDE のキャッシュまたはプロジェクトソースにファイルがローカルに保存されます。
スキーマファイルを開き、ツールバーからイントロスペクションクエリの実行を選択します。
GraphQL ツールウィンドウで、エンドポイントを右クリックし、コンテキストメニューからエンドポイントから GraphQL スキーマを取得するを選択します。
エディターでイントロスペクションファイルのスキーマ構造をインスペクションするには、ツールバーのオープンイントロスペクションスキーマアクションを使用します。これにより、選択したエンドポイントのファイルが開きます。
各クエリの後にイントロスペクション結果ファイルを開かない場合は、Ctrl+Alt+S を押して設定を開き、言語 & フレームワーク | GraphQL を選択して、イントロスペクション結果を含むエディターを開くチェックボックスをオフにします。

サーバー機能の検出

サーバーの機能は、__Type、__Field、__Directive、__InputValue フィールドの構造を返すイントロスペクションクエリに基づいて動的に決定されます。

query IntrospectionCapabilitiesQuery {
  __schema {
    types {
      name
      fields {
        name
        args {
          name
        }
      }
    }
  }
}
            

上記のクエリは、次のいずれかのスキーマを返します。

    type Query {
        id: ID
        name(arg: String @deprecated(reason: "Deprecated")): String
        email(filter: FilterArgs @deprecated): String
    }

    input SomeParams {
        id: ID = "<new>" @deprecated(reason: "SomeParams_id")
        name: String = "User123" @deprecated
    }

    directive @customDirective(arg: String @deprecated(reason: "directive_arg")) repeatable on QUERY

    type Query {
        id: ID
        name(arg: String): String
        email(filter: FilterArgs): String
    }

    input SomeParams {
        id: ID
        name: String
    }

    directive @customDirective(arg: String) on QUERY

Ctrl+Alt+S を押して設定を開き、詳細設定を選択します。
スキーマ機能検出モードリストから、次のいずれかを選択します。
- アダプティブ - このモードでは、WebStorm は追加の予備クエリを実行し、GraphQL サーバーから実際に利用可能な機能のセットを要求します。
  デフォルトでは適応型モードが選択されます。
- 最新 - 予備クエリを実行して実際に利用可能な機能を検出せずに、最新の GraphQL サーバーのすべてのデフォルト機能を有効にするには、このモードを選択します。
- レガシー - 予備クエリを実行して実際に利用可能な機能を検出せずに、古い GraphQL 実装のすべてのデフォルト機能を無効にするには、このモードを選択します。
非準拠エンドポイントとの互換性を向上させるには、イントロスペクションクエリのデフォルト値をスキップするチェックボックスをオンにしてください。副作用として、デフォルト値の情報がスキーマから削除されます。
デフォルトでは、チェックボックスはオフになっています。
デフォルトでは、空の型はイントロスペクション結果に含まれます。空の型をスキップするには、イントロスペクション結果に空の型を含めるチェックボックスをオフにしてください。

クエリ

エディターからクエリを直接実行するには、クエリ定義にキャレットを置き、ツールバーの GraphQL を実行するをクリックするか、Ctrl+Enter を押します。クエリはツールバーで選択したエンドポイントに送信されます。
クエリに変数が含まれる場合は、ツールバーのをクリックして専用の変数エディターを開き、変数を JSON 形式で指定します。
あるいは、GraphQL スクラッチファイルを作成し、それをクエリ送信用の playground として使用します。GraphQL ツールウィンドウで、エンドポイントノードをダブルクリックし、新しい GraphQL スクラッチファイルを選択します。

スクラッチファイル

GraphQL スクラッチファイルの先頭のコメントに # config=<path>[!<optionalProjectName>] パターンに従う文字列が含まれている場合、指定された構成とプロジェクトが解決と型検証に使用されます。このパターンに従うコメントは有効とみなされます。

                # config=/user/local/project/.graphqlrc.yml
                # config=/user/local/project/.graphqlrc.yml!backend
            

ツールバー

各 GraphQL ファイルには、最も一般的に使用されるアクションを含むツールバーがあります。

	構成ファイルを開く	対応する構成ファイルを開くか、存在しない場合は新しい構成ファイルを作成します。
環境変数の編集		これによりダイアログが開き、関連する構成ファイルで定義されている環境変数の値を指定できます。
	変数エディターの切り替え	これにより、JSON 形式でクエリ変数を指定できるエディターウィンドウが開きます。
エンドポイントのリスト		既知の URL のリストは構成ファイルで定義されており、これを使用して、GraphQL クエリの送信先となる URL、またはイントロスペクションのフェッチ元となる URL を選択できます。
	GraphQL を実行する	以下のエディターから選択した GraphQL クエリを実行します。
	イントロスペクションクエリの実行	このアクションは、選択したエンドポイントからイントロスペクトされたスキーマをリフレッシュします。
	オープンイントロスペクションスキーマ	このコマンドは、選択したエンドポイントに対応するローカルファイルを開きます。

ツールウィンドウ

GraphQL ツールウィンドウには、GraphQL プロジェクトの概要が表示されます。検証エラーの表示、イントロスペクションクエリの実行、スクラッチの作成などを行うことができます。

スキーマとプロジェクト構造タブには、検出された構成ファイルの概要と、それぞれの構成ファイルに関連付けられた GraphQL スキーマが表示されます。このツリービューでは、複数のノードに対して次の便利なアクションを使用できます。

スキーマ検出の概要 - 各プロジェクトで検出されたタイプを検索するには、対応するノードをダブルクリックします。これによりダイアログウィンドウが開き、すべてのタイプを検索して、それらが定義されている場所に移動できるようになります。
スキーマエラー - エラーノードをクリックして、エラーの原因に移動します。
エンドポイント - エンドポイントを右クリックして、イントロスペクションクエリを作成するか、選択した構成ファイルとプロジェクトに関連付けられたスクラッチファイルを作成します。

ツールウィンドウのツールバー

GraphQL ツールウィンドウの左側にあるツールバーには、次の便利なアクションが用意されています。

	スキーマ構成の追加	選択したディレクトリに構成ファイルを作成します。あるいは、上記の基本構成で説明したように、プロジェクトツールウィンドウから構成ファイルを作成することもできます。
	選択したスキーマ構成を編集する	選択したノードの構成ファイルをツールウィンドウで開きます。
	スキーマ検出を再開する	このアクションにより、ロードされたすべてのスキーマがクリアされ、検出プロセスが最初から開始されます。これは、キャッシュされたデータが問題を引き起こしている場合に役立ちます。

注入

タグ付きテンプレートリテラル

WebStorm は graphql、gql、Relay.QL、Apollo.gql タグをサポートします。

const QUERY = gql``;

IntelliJ デフォルトのコメントベースのインジェクション

                // language=GraphQL
                const QUERY = `query { field }`;
            

C スタイルのコメント

const QUERY = /* GraphQL */ `query { field }`;

GraphQL のコメント

                const QUERY = `
                    #graphql

                    query { field }
            `;
            

2025 年 10 月 20 日

WebStorm 2025.3 ヘルプ