GraphQL IntelliJ Plugin

GraphQL language support for WebStorm, IntelliJ IDEA and all other IDEs. The plugin works with all IDEs in the IntelliJ Platform.

Table of Contents

• Prerequisites
• Installation
• Features
• How to use
• Configuration
  • Basic configuration
  • Composite schema
  • Remote schemas
  • Local introspection schemas
  • Advanced configuration
  • Multiple projects
    • Config per project
    • Single config
  • Configuration files
    • Yaml
    • JavaScript
    • TypeScript
  • Migration
  • Legacy configuration
  • Environment variables
    • .env files
    • Manual configuration
    • System
• Introspection
  • Rerun latest introspection
• Queries
  • Scratch files
• Toolbar
• Tool window
• Injections
• Acknowledgements
• License

Prerequisites

The plugin and this documentation assume you are already familiar with the GraphQL language. If you're not, please visit the official graphql.org website first. The plugin works out of the box with popular GraphQL clients such as Apollo GraphQL and Relay, but you're free to choose your client and server framework.

Installation

The plugin is available from JetBrains Marketplace. You can install it directly from your IDE via the File | Settings/Preferences | Plugins screen. On the Marketplace tab simply search for graphql and select the GraphQL suggestion:

Features

The main features of this plugin include:

• Full language support for GraphQL Specification including the Schema Definition Language (SDL).
• Schema-aware completion, error highlighting, and documentation.
• Syntax highlighting, code-formatting, folding, commenter, and brace-matching.
• The plugin discovers your local schema on the fly. Remote schemas are easily fetched using introspection. You can introspect GraphQL endpoints to generate schema declaration files using the GraphQL Type System Definition Language.
• Support for multi-schema projects using configurable project scopes or graphql-config files. Schema discovery is configured using graphql-config files, which includes support for multi-schema projects.
• Built-in support for Relay and Apollo projects: graphql and gql tagged template literals in JavaScript and TypeScript are automatically recognized as GraphQL.
• Execute queries using variables against configurable endpoints, including support for custom headers and environment variables.
• Find Usages and Go to Declaration for schema types, fields, and fragments.
• Structure view to navigate GraphQL files.
• Load variables from shell, .env files or setup them manually per configuration file.
• Built-in Relay, Federation, and Apollo Kotlin type definitions (You need to enable it in Preferences / Settings | Languages & Frameworks | GraphQL).

How to use

This developer guide covers how to set up your project to get the most out of the GraphQL language tooling in this plugin.

It is important to configure how the schema types are discovered. If the schema types are not discovered correctly, language features such as completion and error highlighting will be based on the wrong type information.

Schemas and their types are declared using GraphQL Type System Definition Language, which is also widely known as GraphQL Schema Definition Language (often abbreviated as SDL). If you're authoring your schemas in SDL, the plugin provides the following features:

• Completion for types when defining fields, arguments, implemented interfaces, and so on.
• Error highlighting of schema errors such as unknown types, wrong use of types, and missing fields when implementing interfaces.
• Find usages in SDL and refactoring such as rename, which will update the relevant queries, mutations, and so on.

Configuration

GraphQL Config docs could be found here.

By default, the plugin assumes that your project contains a single schema. If this is the case, you don't need to perform any actions in terms of schema discovery. For a single-schema project, schema types are discovered as follows: All .graphql files in the Project files scope are processed for type definitions, which are added to a singleton type registry. If the IDE has JavaScript language support, injected GraphQL strings in the Project files scope are processed for all JavaScript file types. File extensions include .js, .jsx, .ts,.tsx, .html and html-based files like .vue.

For projects with multiple schemas, developers have to configure a scope for each schema. The purpose of a schema-specific scope is to prevent types from being picked up in more than one GraphQL type registry, which would likely result in validation errors. This is because these types will appear to have been declared more than once. In addition, the scopes prevent non-conflicting types from showing up in completions and ensure that validation only recognizes the types that belong to the current schema.

However, it’s recommended to have a simple config in the project root. Otherwise, you will not be able to define a remote URL for making GraphQL queries directly from the editor.

A documentation describing GraphQL Config itself could be found here. In the following sections, we will discuss how to use it in the context of this plugin.

Basic configuration

A simple configuration file graphql.config.yml can be created using a context action on the directory in the project view via New > GraphQL Config:

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

Here, we expect a schema to be defined in a local file schema.graphql. The documents key is defined using a glob pattern that will include any GraphQL operation in the current or nested directory. By operation, we mean only GraphQL queries and fragments, but not type definitions.

Please note that paths are relative to the config directory, unless they are explicitly defined as absolute. Therefore, you do not need to prefix them with ./. Just schema.graphql is sufficient. The same applies to glob patterns.

Composite schema

GraphQL Config can also assemble multiple modularized schemas into a single GraphQL schema object.

You can specify a list of files:

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

Alternatively, you can use a glob pattern to find and include pieces of schema:

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

GraphQL Config looks for those files, reads the files and merges them to produce a GraphQL schema object.

Remote schemas

If you have a GraphQL endpoint and do not have the local schema file yet, you can define one or more endpoints and make an introspection query. This will load a schema from the server, convert it to a GraphQL file, and save it in the IDE's cache directory.

Depending on whether you need additional configuration for an endpoint, you can specify it as a string or an object with supplementary keys containing data such as headers.

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}

Pay special attention to the last example; it should have correct indentation.

Now it is required to run an introspection query manually to load a schema from the provided endpoint. You can do this in multiple ways.

You probably need to authenticate with your remote service to run queries, and apparently you'll do this using HTTP headers and some kind of token inside them. The best way to provide a token without hardcoding it in the config file is through environment variables. An example of this is a TOKEN variable in the code snippet above.

Local introspection schemas

If you want to store an introspection result locally, you can configure an endpoint as it was done in the legacy configuration format. Define one or multiple endpoints in the endpoints extension, and then make an introspection query. A file will be saved at the first path in the corresponding schema section, for example, a local.graphql file in the example below.

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

Advanced configuration

If you need more fine-grained control over which files should be included in the schema, you can use the optional include and exclude keys. First, it checks a candidate file for exclusion. If it's not excluded, the file path is matched against the include pattern.

In that example, schema.graphql and every file inside the src directory except files in __tests__ will be included in that project.

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

Remember that all files specified in schema or documents are included by default.

Multiple projects

Config per project

A config file defines a GraphQL "module" root, similar to how package.json or similar files do. Even if this file is empty, all files in that directory and in the nested ones will use a schema associated with that configuration. Therefore, the simplest way to separate different schemas is to create a configuration file inside each subdirectory, if they are completely independent, as is usually the case with monorepos. With this approach, the location of the config files creates separate scopes for each subtree.

- project root/
    - product a (schema one)/
        - .graphql.config.yml <-----
        - schema files and graphql aware components
    - product b (schema two)/
        - .graphql.config.yml <-----
        - schema files and graphql aware components

Single config

If you prefer to have a single configuration file, you can specify multiple projects in the same file.

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

The configuration for that case should appear as follows:

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

Files are matched against projects in the order in which the projects are defined. Therefore, if a file matches several projects, the first one will be chosen.

GraphQL operations are matched non-strictly when no include or exclude keys are defined for a specific project. This means that if a query or fragment does not match any project explicitly, the file will be associated with the first project that does not have include or exclude keys. In the example above, there is an additional root directory called queries, in addition to backend and frontend. If queries contains some GraphQL documents that do not match any of the provided patterns, the first project, frontend, will be associated with those queries.

To achieve this, you can add an exclude pattern to the frontend project configuration. This will associate the files in the queries folder with the backend project.

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

This does not apply to type definitions, as mentioned previously. The plugin only uses type definitions from files that strictly match the schema or include keys.

NOTE: Values on the root level are defaults for projects. Therefore, if a project does not define a property such as schema, include, or even extensions, it will take a value from the root if it exists.

Configuration files

The plugin supports multiple configuration file formats. Here is a list of all the possible options:

• graphql.config.json
• graphql.config.js
• graphql.config.cjs
• graphql.config.ts
• graphql.config.yaml
• graphql.config.yml
• .graphqlrc (YAML and JSON)
• .graphqlrc.json
• .graphqlrc.yaml
• .graphqlrc.yml
• .graphqlrc.js
• .graphqlrc.ts

Yaml

The official JetBrains YAML plugin should be installed. However, it should be bundled into every IntelliJ IDE by default, so it usually doesn't require any action.

JavaScript

Internally, we use Node.js to load a JavaScript or TypeScript config file. Therefore, Node.js should be install