GraphQL CodeGen Persisted Queries

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

Installation

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

Usage

$3

`yml


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
`

$3

`typescript
// 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

$3

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

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

With includeAlgorithmPrefix: true:

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

$3

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:

`json
{
"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:

`json
{
"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

$3

`bash


Install dependencies

pnpm install

Watch mode for development

pnpm dev
`

$3

The plugin includes a comprehensive test suite built with Vitest:

`bash


Run tests

pnpm test

Run tests in watch mode

pnpm test:watch
``

License

MIT