GraphQL for Vim

This Vim plugin provides GraphQL file detection, syntax highlighting, and indentation. It currently targets the September 2025 Edition of the GraphQL specification.

The core runtime files are also included with Vim 9.1.0955+. They provide the foundational support (ftplugin, indent, syntax) for the graphql filetype. This plugin includes the most up-to-date version of those runtime files as well as support for embedding GraphQL syntax inside of other filetype buffers (such as JavaScript).

Installation

This plugin requires Vim version 8.2 or later. Equivalent Neovim versions are also supported.

Using vim-plug

Add Plug 'jparise/vim-graphql' to ~/.vimrc
vim +PluginInstall +qall

Using Vim Packages

mkdir -p ~/.vim/pack/jparise/start
cd ~/.vim/pack/jparise/start
git clone https://github.com/jparise/vim-graphql.git graphql
vim -u NONE -c "helptags graphql/doc" -c q

Syntax Highlighting

Complete syntax highlighting is enabled for the graphql [filetype][]. This filetype is automatically selected for filenames ending in .gql, .graphql, and .graphqls.

If you would like to enable automatic syntax support for more file extensions (e.g., *.prisma), create a file named ~/.vim/after/ftdetect/graphql.vim containing autocommand lines like:

au BufNewFile,BufRead *.prisma setfiletype graphql

[filetype]: http://vimdoc.sourceforge.net/htmldoc/filetype.html

JavaScript and TypeScript Support

GraphQL syntax support inside of [ES2015 template literals][templates] is provided. It works "out of the box" with Vim 8.2+'s JavaScript and TypeScript language support. The extended JavaScript syntax provided by the [vim-javascript][] plugin is also supported.

For older versions of Vim, TypeScript support can be enabled by installing the [yats][] plugin.

[templates]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Templateliterals#Taggedtemplates [vim-javascript]: https://github.com/pangloss/vim-javascript [yats]: https://github.com/HerringtonDarkholme/yats.vim

const query = gql
  {
    user(id: ${uid}) {
      firstName
      lastName
    }
  }
;

The list of recognized tag names is defined by the g:graphqljavascripttags variable, which defaults to ["gql", "graphql", "Relay.QL"]. This can also be set on a per-buffer basis using the b:graphqljavascripttags variable.

Untagged template literals passed as the first argument to specific functions can also be recognized. g:graphqljavascriptfunctions defines this list of functions, which defaults to ["graphql"]. This list can also be set on a per-buffer basis using the b:graphqljavascriptfunctions variable.

const query = graphql(
  {
    user(id: ${uid}) {
      firstName
      lastName
    }
  }
);

You can also add a # gql or # graphql comment at the start of a template string to indicate that its contents should be considered GraphQL syntax.

const query = # gql
  {
    user(id: ${uid}) {
      firstName
      lastName
    }
  }
;

Syntax highlighting within .jsx / .tsx files is also supported. These filetypes can be "compound" (javascript.jsx and typescript.tsx) or use the "react" variants (javascriptreact and typescriptreact).

Syntax highlighting is also available within Vue templates.

ReasonML Support

GraphQL syntax support inside of ReasonML template strings using [graphql-ppx][] is available.

[%graphql {|
  query UserQuery {
    user {
      id
      name
    }
  }
|}];

The %relay extension point is also supported.

[graphql-ppx]: https://github.com/reasonml-community/graphql-ppx

ReScript Support

GraphQL syntax support inside of ReScript strings is available.

%graphql(
  query UserQuery {
    user {
      id
      name
    }
  }
)

The [%relay extension node][%relay] is also supported.

[%relay]: https://rescript-relay-documentation.vercel.app/docs/making-queries

PHP Support

GraphQL syntax inside of [heredoc][] and [nowdoc][] strings is supported. The string identifier must be named GQL (case-insensitive).

<?php
$my_query = <<<GQL
{
  user(id: ${uid}) {
    firstName
    lastName
  }
}
GQL;

[heredoc]: https://www.php.net/manual/language.types.string.php#language.types.string.syntax.heredoc [nowdoc]: https://www.php.net/manual/language.types.string.php#language.types.string.syntax.nowdoc

Language Server Protocol Support

Language Server Protocol (LSP) implementations can enable editor features like schema-aware completion. This plugin does not implement the Language Server Protocol, but here are some others that do: