GraphQL CodeGen Persisted Queries

A GraphQL Codegen plugin for generating persisted query manifests for server and client.

Installation

pnpm add -D @replit/graphql-codegen-persisted-queries

Usage

YAML Config

# codegen.yml
generates:
  ./generated-gql/persisted-query-manifest/client.json:
    plugins:
      - @replit/graphql-codegen-persisted-queries
    config:
      output: client
      
  ./generated-gql/persisted-query-manifest/server.json:
    plugins:
      - @replit/graphql-codegen-persisted-queries
    config:
      output: server
      includeAlgorithmPrefix: true # Enable prefixed document identifiers for compliance with GraphQL over HTTP spec

TypeScript Config

// codegen.ts
import type { CodegenConfig } from '@graphql-codegen/cli';

const config: CodegenConfig = {
  // ... other config
  generates: {
    './generated-gql/persisted-query-manifest/client.json': {
      documents: ['./client/**/*.{graphql,gql}', './pages/**/*.{graphql,gql}'],
      plugins: ['@replit/graphql-codegen-persisted-queries'],
      config: {
        output: 'client',
      },
    },
    './generated-gql/persisted-query-manifest/server.json': {
      documents: ['./client/**/*.{graphql,gql}', './pages/**/*.{graphql,gql}'],
      plugins: ['@replit/graphql-codegen-persisted-queries'],
      config: {
        output: 'server',
        includeAlgorithmPrefix: true, // Enable prefixed document identifiers for compliance with GraphQL over HTTP spec
      },
    }
  }
};

export default config;

Configuration Options

| Option | Type | Default | Description | |-------------------------|------------------------|------------|------------------------------------------------------------------------| | output | 'client' \| 'server' | (required) | Format of the generated manifest | | algorithm | string | 'sha256' | Hash algorithm to use for generating operation IDs | | includeAlgorithmPrefix| boolean | false | Whether to prefix hashes with algorithm name (e.g., sha256:abc123...) |

Output Formats

Client Format

The client format provides a simple mapping between operation names and their hashes, making it easy for clients to reference operations by name:

{
   "GetUser": "abcdef123456...",
   "UpdateUser": "fedcba654321..."
}

With includeAlgorithmPrefix: true:

{
   "GetUser": "sha256:abcdef123456...",
   "UpdateUser": "sha256:fedcba654321..."
}

Server Format

The server format is more comprehensive, mapping operation hashes to their complete details (type, name, and body). This is ideal for server-side lookup and validation:

{
   "format": "apollo-persisted-query-manifest",
   "version": 1,
   "operations": {
      "abcdef123456...": {
         "type": "query",
         "name": "GetUser",
         "body": "query GetUser { user { id name } }"
      },
      "fedcba654321...": {
         "type": "mutation",
         "name": "UpdateUser",
         "body": "mutation UpdateUser($id: ID!, $name: String!) { updateUser(id: $id, name: $name) { id name } }"
      }
   }
}

With includeAlgorithmPrefix: true:

{
   "format": "apollo-persisted-query-manifest",
   "version": 1,
   "operations": {
      "sha256:abcdef123456...": {
         "type": "query",
         "name": "GetUser",
         "body": "query GetUser { user { id name } }"
      },
      "sha256:fedcba654321...": {
         "type": "mutation",
         "name": "UpdateUser",
         "body": "mutation UpdateUser($id: ID!, $name: String!) { updateUser(id: $id, name: $name) { id name } }"
      }
   }
}

How It Works

The plugin's workflow is straightforward:

1. It collects all GraphQL operations from your codebase
2. It adds __typename to all selection sets in the operations for proper type resolution
3. It identifies all fragments used in each operation, resolving them recursively to ensure all nested fragments are included
4. It orders the documents with operation definitions first, followed by fragments to ensure hash consistency
5. It generates operation hashes using the specified algorithm (default: sha256)
6. It outputs a manifest file in your chosen format (client or server)

You can enable the "Prefixed Document Identifier" format (e.g., sha256:abc123...) for compliance with the GraphQL over HTTP specification (RFC at the time of publishing this package) by setting includeAlgorithmPrefix: true.

Development

Setup

# Install dependencies
pnpm install

# Watch mode for development
pnpm dev

Testing

The plugin includes a comprehensive test suite built with Vitest:

# Run tests
pnpm test

# Run tests in watch mode
pnpm test:watch

License

MIT