GraphQLSP

This is a TypeScript LSP Plugin that will recognise documents in your TypeScript code and help you out with hover-information, diagnostics and auto-complete.

Features

• Hover information showing the decriptions of fields
• Diagnostics for adding fields that don't exist, are deprecated, missmatched argument types, ...
• Quick fixes for misspelled fields ("Did you mean"), deprecated fields with a known replacement, and unused fields
• Auto-complete inside your editor for fields
• Find references and rename for GraphQL fragments, across your project's files
• Will warn you when you are importing from a file that is exporting fragments that you're not using
• An "Extract to fragment" refactor that moves selected fields into a new co-located fragment (in graphql() call-expression mode)
• The VS Code extension adds GraphQL operations and fragments to the Outline view and symbol navigation

Note that this plugin does not do syntax highlighting, for that you still need something like the VSCode/... plugin

Installation

npm install -D @0no-co/graphqlsp

Usage

Go to your tsconfig.json and add

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "@0no-co/graphqlsp",
        "schema": "./schema.graphql"
      }
    ]
  }
}

now restart your TS-server and you should be good to go, ensure you are using the workspace version of TypeScript. In VSCode you can do so by clicking the bottom right when on a TypeScript file or adding a file like this.

If you are using VSCode ensure that your editor is using the Workspace Version of TypeScript this can be done by manually selecting it or adding a .vscode/config.json with the contents of

{
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true
}

Configuration

Required

• schema allows you to specify a url, .json or .graphql file as your schema. If you need to specify headers for your introspection you can opt into the object notation i.e. { "schema": { "url": "x", "headers": { "Authorization": "y" } }}

Optional

• template add an additional template to the defaults gql and graphql
• templateIsCallExpression this tells our client that you are using graphql('doc') (default: true) when using false it will look for tagged template literals
• shouldCheckForColocatedFragments when turned on, this will scan your imports to find unused fragments and provide a message notifying you about them (only works with call-expressions, default: true)
• trackFieldUsage this only works with the client-preset, when turned on it will warn you about unused fields within the same file. (only works with call-expressions, default: true)
• tadaOutputLocation when using gql.tada this can be convenient as it automatically generates an introspection.ts file for you, just give it the directory to output to and you're done
• tadaDisablePreprocessing this setting disables the optimisation of tadaOutput to a pre-processed TypeScript type, this is off by default.
• clientDirectives this setting allows you to specify additional clientDirectives which won't be seen as a missing schema-directive.

Tracking unused fields

Currently the tracking unused fields feature has a few caveats with regards to tracking, first and foremost it will only track the result and the accessed properties in the same file to encourage fragment co-location.

Secondly, we don't track mutations/subscriptions as some folks will add additional fields to properly support normalised cache updates.

Fragment masking

When we use a useQuery that supports TypedDocumentNode it will automatically pick up the typings from the query you provide it. However for fragments this could become a bit more troublesome, the minimal way of providing typings for a fragment would be the following:

import { TypedDocumentNode } from '@graphql-typed-document-node/core';

export const PokemonFields = gql`
  fragment pokemonFields on Pokemon {
    id
    name
  }
` as typeof import('./Pokemon.generated').PokemonFieldsFragmentDoc;

export const Pokemon = props => {
  const pokemon = useFragment(props.pokemon, PokemonFields);
};

export function useFragment<Type>(
  data: any,
  _fragment: TypedDocumentNode<Type>
): Type {
  return data;
}

This is mainly needed in cases where this isn't supported out of the box and mainly serves as a way for you to case your types.

💙 Sponsors

Local development

Run pnpm i at the root. Open packages/example by running code packages/example or if you want to leverage breakpoints do it with the TSS_DEBUG_BRK=9559 prefix. When you make changes in packages/graphqlsp all you need to do is run pnpm i in your other editor and restart the TypeScript server for the changes to apply.

Ensure that both instances of your editor are using the Workspace Version of TypeScript

Debugging with breakpoints

To set breakpoints in the TypeScript sources of packages/graphqlsp you need a development build of the plugin, which emits sourcemaps that point back at the files in packages/graphqlsp/src:

1. Build the plugin with pnpm --filter @0no-co/graphqlsp dev (this watches for changes; a one-off NODE_ENV=development pnpm --filter @0no-co/graphqlsp build works too)
2. Open the example project with TSS_DEBUG_BRK=9559 code packages/example and run pnpm i in it, so it picks up the freshly built plugin
3. In the VS Code window that has the repository root open, set your breakpoints in packages/graphqlsp/src and start the "Attach to VS Code TS Server via Port" launch configuration from the "Run and Debug" panel
4. Trigger the plugin from the example window (e.g. by typing inside a graphql() document) and your breakpoints will be hit

After making changes in packages/graphqlsp, restart the example window's TypeScript server ("TypeScript: Restart TS Server" in the command palette) and reattach the debugger for the changes to apply.

Production builds (pnpm build without NODE_ENV=development) also emit sourcemaps, but their sources are relative paths that don't resolve from the location pnpm installs the package to, so breakpoints won't bind with them.