natemoo-re / ts-graphql-plugin

TypeScript Language Service Plugin for GraphQL developers

ts-graphql-plugin

TypeScript Language Service Plugin to help GraphQL client development(e.g. Apollo). This plugin parses and analyzes template strings in .ts and provides functions like GraphiQL to your editor or IDE.

Features

This plugin extends TypeScript Language Service and provides the following features:

• Completion suggestion
• Get GraphQL diagnostics

Usage

First, confirm that your project has typescript(v2.3.x or later) and graphql.

To install this plugin, execute the following:

npx ts-plugin install graphql

Then configure the plugins section of your tsconfig.json, for example:

{
  "compilerOptions": {
    "module": "commonjs",
    "target": "es5",
    "plugins": [
      {
        "name": "ts-graphql-plugin",
        "schema": "path-or-url-to-your-schema.json",
        "tag": "gql" 
      }
    ]
  }
}

It's ready to go. Launch your TypeScript IDE.

Plugin options

schema

It's a required parameter and should point a file or URL which contains your GraphQL schema data such as :

{
  "data": {
    "__schema": {
      "queryType": {
        "name": "Query"
      },
      "types": [
        {
          "kind": "OBJECT",
          "name": "Query",
          "description": null,
          "fields": [
            {
              "name": "viewer",
              :

You can generate a schema data .json file using introspectionQuery. If you want detail, see https://facebook.github.io/relay/docs/guides-babel-plugin.html#schema-json .

You can pass URL and custom HTTP headers. It's useful to use an existing GraphQL server like GitHub v4 API. For example:

  "schema": {
    "http": {
      "url": "https://api.github.com/graphql",
      "headers": {
        "Authorization": "Bearer YOUR_GITHUB_API_TOKEN"
      }
    }
  },

The schema option accepts the following type:

type SchemaConfig = string |
{
  file: {
    path: string;
  }
} |
{
  http: {
    url: string;
    headers?: { [key: string]: string };
  }
};

tag

It's optional. When it's set, this plugin works only if the target template string is tagged by a function whose name is equal to this parameter.

If not set, this plugin treats all template strings in your .ts as GraphQL query.

For example:

import gql from 'graphql-tag';

// when tag paramter is 'gql'
const str1 = gql`query { }`;     // work
const str2 = `<div></div>`;       // don't work
const str3 = otherTagFn`foooo`;  // don't work

It's useful to write multiple kinds template strings(e.g. one is Angular Component template, another is Apollo GraphQL query).

Available editors

I've checked the operation with the following editors:

• Visual Studio Code
• Vim (with tsuquyomi)

And the following editor have TypeScript plugin with LanguageService so they're compatible with this plugin:

• Emacs
• Sublime text
• Eclipse

How it works

This plugin relies on graphql-language-service and adapts it for TypeScript Language Service.

License

This software is released under the MIT License, see LICENSE.txt.