JetBrains GraphQL plugin: schema-aware GraphQL support inside IntelliJ Platform IDEs

The problem: an editor that does not know your schema

GraphQL is unusual among backend languages in that the type system lives somewhere other than in the code you are writing. A query file has fields, arguments and fragments that must line up with a schema that may be in another repository, behind a running server, or generated at build time. An editor that does not know the schema cannot tell you that a field does not exist, and that is the single most common class of error in a GraphQL codebase.

The GraphQL IntelliJ Plugin is the fix for JetBrains IDEs. It is an official JetBrains project, and it works across the whole IntelliJ Platform, so WebStorm, IntelliJ IDEA and the other IDEs based on that platform all get the same support. The plugin and its documentation assume you already know the GraphQL language; if you do not, the documentation sends you to the official site first, which is an honest thing for a language support plugin to say.

It works out of the box with the popular GraphQL clients, Apollo GraphQL and Relay, but you are free to choose your own client and server framework.

The feature list is broad, and the interesting parts are the ones that need a schema. There is full language support for the GraphQL specification including the Schema Definition Language, schema-aware completion, error highlighting and documentation, and the usual editing furniture: syntax highlighting, code formatting, folding, a commenter and brace matching. There is Find Usages and Go to Declaration for schema types, fields and fragments, and a structure view for navigating GraphQL files.

The audience is frontend and full stack engineers who write GraphQL every day, and the licence is MIT, so the plugin itself is free and unencumbered.

How schema discovery works, and why it is the hard part

Everything the plugin does well depends on one thing: knowing the schema. The documentation is blunt about the consequence. It is important to configure how the schema types are discovered, and if the schema types are not discovered correctly, language features such as completion and error highlighting will be based on the wrong type information.

By default the plugin assumes a single schema, and for that case it needs no configuration at all. All .graphql files in the Project files scope are processed for type definitions and added to a singleton type registry. If the IDE has JavaScript language support, injected GraphQL strings in the Project files scope are processed too, across .js, .jsx, .ts, .tsx, .html and html-based files such as .vue.

Multi-schema projects are where the work starts. A scope per schema exists to prevent types from being picked up in more than one type registry, which would likely result in validation errors, because those types would appear to have been declared more than once. The scopes also keep non-conflicting types out of each other's completions, so validation only recognises the types that belong to the current schema.

That is the real design insight here. GraphQL monorepos with several services and several schemas are common, and the failure mode of a naive plugin is a type registry where User means three different things. Scopes are the mechanism that keeps them apart, and the cost is that you have to declare them.

The plugin also supports remote schemas fetched by introspection, so you can point it at a running endpoint and get the schema without a local SDL file, and it ships built-in Relay, Federation and Apollo Kotlin type definitions, which you enable in Preferences or Settings under Languages and Frameworks and GraphQL.

Installing the plugin from the JetBrains Marketplace

The installation is the standard JetBrains plugin route. The plugin is available from the JetBrains Marketplace, and you can install it directly from your IDE through the File, then Settings or Preferences, then Plugins screen. On the Marketplace tab you search for graphql and select the GraphQL suggestion, which is the one carrying the official JetBrains project badge.

There is no server to run and no configuration to complete before the basics work. That is worth saying because the alternatives in this space often ask you to set up a separate language server process and point an editor at it over stdio before you get a single completion. Here the schema discovery, the code generation and the query execution are all inside the IDE, which is the trade the platform plugin makes: deep integration with the editor, and no portability outside it.

The second thing to know at install time is that the plugin and the documentation assume GraphQL familiarity. The guidance to visit graphql.org first if you are new to the language is not a formality, because the settings surface is dense with GraphQL concepts: schemas, scopes, registries, introspection and SDL.

If your team is on JetBrains IDEs, this is a plugin to install on day one of a GraphQL project. If your team is spread across editors, the same functionality is available in other tools, and the difference in approach is discussed further below.

The configuration file: graphql.config.yml and the New GraphQL Config action

The recommended setup is a simple configuration file in the project root, and the plugin can create it for you through a context action on the directory in the project view, using New and then GraphQL Config. The file it produces is YAML:

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

The schema key points at a local SDL file, and the documents key is a glob pattern that includes any GraphQL document files in the project. That is the whole configuration for the common case, and the documentation notes that a simple config in the project root is recommended, because otherwise you will not be able to define a remote URL for making GraphQL queries directly from the editor.

That last point is the one to internalise. A project without a root config can still get completion from discovered local files, but you lose the ability to run queries against a live endpoint, which is one of the plugin's most useful features for a developer working against a staging environment.

The configuration file format is not the plugin's own invention. Schema discovery is configured using graphql-config files, and the documentation links to the graphql-config documentation for the details, describing it as the mechanism that also covers multi-schema projects. So the plugin piggybacks on a tool that the wider GraphQL ecosystem already uses, which means a team that already has a graphql-config file for its linting and CI setup gets schema discovery for free.

Beyond the YAML file, the documentation covers remote schemas fetched by introspection, local introspection schemas, per-project and single configurations for multiple projects, and configuration in YAML, JavaScript and TypeScript form.

The JavaScript integration: tagged templates and language injections

The feature that separates this plugin from a generic GraphQL text plugin is how it finds GraphQL inside JavaScript and TypeScript.

Built-in support for Relay and Apollo projects is included, and in those projects the graphql and gql tagged template literals in JavaScript and TypeScript are automatically recognised as GraphQL. You are not asked to mark up your files or rename your functions. The template literal is the signal.

Underneath that sits the language injection machinery, which is visible in the repository layout with a langInjection/ directory and a javascript/ directory, alongside a gen/ directory that holds generated code, resources/ for the plugin resources and src/ for the implementation. The top-level entries also include build.gradle.kts and settings.gradle.kts for the Gradle build, a BUILD.bazel file, the Gradle wrapper, an intellij.graphql.iml module file, and separate directories for tests, website, yaml, docs and libraries.

The practical consequence for a developer is that a GraphQL operation written inside a React component is treated as a first class GraphQL document. Completion offers fields from your schema, an unknown field is highlighted as an error, and Go to Declaration takes you to the type definition in your SDL file rather than to a string in a component.

That is also where the scope configuration pays off. If an injected query in a JavaScript file belongs to a different service than the one you are editing, a scope keeps the two type registries apart, so the same field name in two services does not produce a wall of false errors.

Running queries from the editor, and where variables come from

The plugin can execute queries using variables against configurable endpoints, with support for custom headers and environment variables. That is a short list of features with a lot of behaviour behind it.

Variables can be loaded from your shell, from .env files, or set up manually per configuration file, and the documentation has a whole section on the environment variable handling, including manual configuration and system level settings. The reason this matters is that a GraphQL endpoint almost always needs a bearer token, and a token that lives in a file checked into the repository is a token that leaks.

There is also a toolbar, a tool window, and a scratch files feature for queries you do not want to keep, plus a rerun latest introspection action for when the schema on the server has moved on. The scratch file workflow is the one to understand: it lets you run an ad hoc query without creating a file in the repository, which is how you check a production incident without leaving a mess behind.

Combined with the built-in Relay, Federation and Apollo Kotlin type definitions, the plugin covers the case where your schema is not in your repository at all but is generated by another team's server, and the case where you need to talk to it directly to see what it actually returns rather than what you think it returns.

Maintenance, licence and the limit of a platform plugin

The licence is MIT, and the repository carries the LICENSE file. The project is an official JetBrains project, which is the strongest signal about the long term availability of the feature, and the homepage is a documentation site rather than a company page.

The maintenance picture has a wrinkle worth checking before you pin anything. The repository is not archived and the last push was on 2026-10-20, so the work is happening. The tagged releases in the repository, though, are 4.0.1 from 2023-05-12, 4.0.0 from 2023-04-18 and 3.4.0 from 2023-02-07. The plugin you install from the Marketplace is released through JetBrains' own channel, so the tag history in the repository is not the version history of what users actually run. If your team pins a plugin version for reproducibility, check the Marketplace listing rather than the repository tags, and expect to update the plugin on the IDE's own schedule.

The structural limit is the same one that applies to every IntelliJ Platform plugin. The schema knowledge, the code generation, the injections and the query runner are all implemented as platform extensions, which is what gives the tight integration with the editor, and it is also what makes the plugin useless outside the IntelliJ Platform. The alternative approach is an editor-agnostic GraphQL language server, where a separate process holds the schema and editors talk to it over a standard protocol. The difference in approach is exactly where the schema lives: inside your IDE, or in a process that any editor can talk to.

That choice follows your team. If everyone is on WebStorm or IntelliJ IDEA, the plugin gives you better integration than a language server would. If the team is split across editors, or you want the same schema knowledge in a CI check and in an editor, the language server route is the one that scales, and the graphql-config file that this plugin reads is the same configuration that route would use.

Editorial conclusion

Adopt the JetBrains GraphQL plugin if you develop GraphQL in WebStorm or IntelliJ IDEA and want completion and validation driven by the schema you actually ship, including multi-schema projects configured with graphql-config files. Do not adopt it if your team is spread across editors that do not run the IntelliJ Platform, since the schema knowledge lives in the IDE rather than in a shared language server. Before you enable it on a large codebase, set up the schema scopes properly, because a type registered in two schemas produces validation errors that look like mistakes in your code, and check which build of the plugin your IDE is running against, given that the tagged releases in the repository stop at 4.0.1 from 2023.

Frequently asked questions

Official sources

1. JetBrains/js-graphql-intellij-plugin on GitHub
2. License: MIT
3. Project website
4. README
5. Releases