graphqlsp

The trackFieldUsage feature encourages fragment co-location by tracking results and accessed properties within the same file.

Limitations:

• It does not track mutations or subscriptions, as these are often used for normalized cache updates where extra fields are intentionally added.

Install the GraphQLSP TypeScript LSP plugin as a development dependency using npm.

npm install -D @0no-co/graphqlsp

To debug the plugin source code in packages/graphqlsp/src, follow these steps:

1. Build the development version: Run pnpm --filter @0no-co/graphqlsp dev (or NODE_ENV=development pnpm --filter @0no-co/graphqlsp build) to ensure sourcemaps are emitted.
2. Launch the example: Open the example project with the debug port prefix: TSS_DEBUG_BRK=9559 code packages/example and run pnpm i.
3. Attach Debugger: In your main VS Code window (the repo root), set breakpoints in packages/graphqlsp/src and use the "Attach to VS Code TS Server via Port" launch configuration.
4. Trigger: Perform an action in the example window (like typing in a graphql() document) to hit the breakpoint.

Note: After making changes to the plugin, restart the TypeScript server in the example window and reattach the debugger.

To activate the plugin, add it to the plugins array in your tsconfig.json. You must provide a schema pointing to your .graphql or .json schema file or a schema URL.

Note: Ensure your editor (like VSCode) is using the Workspace Version of TypeScript. In VSCode, you can configure this by creating a .vscode/config.json file in your project root:

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

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

If your environment doesn't support fragment typing out of the box, you can manually cast types using TypedDocumentNode. This is useful for ensuring useFragment receives the correct type.

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;
}

GraphQLSP can search for GraphQL documents in two modes: as tagged template literals (e.g., gql```) or as function call expressions (e.g., gql(...)`).

If you are seeing a MODE_MISMATCH_CODE warning, you need to adjust the templateIsCallExpression setting in your tsconfig.json:

• Set "templateIsCallExpression": false to search for tagged templates.
• Set "templateIsCallExpression": true (default) to search for call expressions.

GraphQLSP can automatically detect and warn you about GraphQL fields that are requested in a document but never actually accessed in your TypeScript code. This is controlled via the plugin configuration.

To disable this feature, set trackFieldUsage to false. You can also specify reservedKeys to prevent certain fields from being flagged as unused (e.g., internal metadata or specific IDs).

By default, trackFieldUsage is true, and the following keys are always reserved:

• id
• _id
• __typename

{
  "trackFieldUsage": true,
  "reservedKeys": ["myCustomKey"]
}

When using persisted queries, GraphQLSP validates the relationship between the hash and the document. Common diagnostic issues include:

• MISSING_PERSISTED_TYPE_ARG: The generic pointing to the GraphQL document is missing or is not a typeQueryNode (e.g., it should be graphql.persisted<typeof document>).
• MISSING_PERSISTED_DOCUMENT: The plugin cannot find a reference to the document being persisted.
• MISSING_PERSISTED_CODE_ARG: The call expression is missing the hash argument required for the persisted call.
• MISSMATCH_HASH_TO_DOCUMENT: The provided hash (e.g., sha256:...) does not match the hash generated from the actual document content.