README.md

GraphQL for Vim

This Vim plugin provides GraphQL file detection, syntax highlighting, and indentation. It currently targets the October 2021 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 or later. Equivalent Neovim versions are also supported.

Using vim-plug

1. Add Plug 'jparise/vim-graphql' to ~/.vimrc
2. 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

JavaScript and TypeScript Support

GraphQL syntax support inside of ES2015 template literals 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.

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

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

Untagged template literals passed as the first argument to specific functions can also be recognized. g:graphql_javascript_functions defines this list of functions, which defaults to ["graphql"]. This list can also be set on a per-buffer basis using the b:graphql_javascript_functions 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.

ReScript Support

GraphQL syntax support inside of ReScript strings is available.

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

The %relay extension node is also supported.

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;

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:

• coc.nvim supports GraphQL language servers

Testing

The test suite uses Vader.vim. To run all of the tests from the command line:

make test

License

This code is released under the terms of the MIT license. See LICENSE for details.