graphql-add-id-document-transform

GraphQL document transform that ensures cache normalization by automatically querying for id fields when available.

Why

Apollo Client doesn't have intrinsic knowledge of your schema, so it can't automatically determine if an id field should be queried for proper cache normalization. Fortunately, GraphQL Code Generator is aware of your schema and knows whether there are necessary id fields to add to your queries, ensuring optimal cache normalization.

[!NOTE] This is not a silver bullet for cache normalization issues, but rather a safety net when other approaches have failed.

It's still valuable to understand cache normalization concepts thoroughly. Consider using type-aware linters like the require-selections rule from @graphql-eslint/eslint-plugin (previously known as require-id-when-available).

If you're experiencing normalization issues that prevent you from fully utilizing your GraphQL cache, this document transform provides a practical solution.

Installation

npm install --dev graphql-add-id-document-transform

Usage

[!IMPORTANT] This is meant to be used with GraphQL Code Generator, but could probably be reused in others as well.

Simply pass the addIdDocumentTransform function to the documentTransforms field of your GraphQL Code Generator configuration (codegen.ts).

import type { CodegenConfig } from '@graphql-codegen/cli';
+import { addIdDocumentTransform } from 'graphql-add-id-document-transform';

const config: CodegenConfig = {
  schema: 'https://localhost:4000/graphql',
  documents: ['src/**/*.tsx'],
  generates: {
    './src/gql/': {
      preset: 'client',
+     documentTransforms: [addIdDocumentTransform],
    },
  },
};

export default config;

📚 Documentation > Advanced Usage > Document Transform

License

graphql-add-id-document-transform is MIT licensed.