PersistGraphQL

0.3.11 verified Sat Apr 25 auth: no javascript deprecated

A build tool and Apollo Client network interface for implementing GraphQL query whitelisting and persisted queries (v0.3.11, last release ~2017, no active maintenance). Scans source code for .graphql files and static GraphQL query strings, assigns each query a hash/ID, and produces a JSON mapping. Provides an Apollo Client network interface to send only the hash/ID instead of the full query string. Primarily useful for reducing bandwidth and enforcing query allowlists. Competes with tools like `persisted-query-lib` but is specific to Apollo Client's older architecture. Limited to statically analyzable queries; no support for dynamic queries. Ships TypeScript types.

Common errors

error Error: Cannot find module 'graphql/language' ↓

cause Missing peer dependency 'graphql'

fix

npm install graphql

error Cannot read property 'definitions' of undefined ↓

cause The query map does not contain an entry for the query being sent (hash mismatch).

fix

Ensure the same extracted_queries.json is used on both client and server, and that the build step is run before using the map.

error TypeError: networkInterface.query is not a function ↓

cause addPersistedQueries expects a valid Apollo Client network interface from v1. Using an incompatible version.

fix

Use Apollo Client 1.x or use the package only with that version.

error persistgraphql: error: unknown option `--extension' ↓

cause The --js flag is required before --extension.

fix

Use: persistgraphql src/ --js --extension=ts

Warnings

deprecated Package is no longer maintained; last release was in 2017. Doesn't support Apollo Client v2+ or modern GraphQL tooling. ↓

fix Consider using 'persisted-query-lib' or Apollo's built-in persisted queries support in Apollo Client >=2.

gotcha The package only works with statically analyzable queries from .graphql files or template literals with the gql tag. Dynamically constructed queries are ignored. ↓

fix Ensure all queries are in dedicated .graphql files or use the gql tag in .js/.ts files (requires `--js` flag).

gotcha When using TypeScript, you must pass `--js --extension=ts` to extract queries from .ts files. The tool does not automatically detect TypeScript. ↓

fix Run `persistgraphql src/ --js --extension=ts`

gotcha The `--add_typename` flag must be used if your client code expects `__typename` fields. If you don't use it, queries will not have `__typename` and caching may break. ↓

fix Include `--add_typename` if you use Apollo Client's cache or fragments that rely on `__typename`.

gotcha The network interface provided is for Apollo Client 1.x only. It will not work with Apollo Client 2+ which introduced a different network interface API. ↓

fix Upgrade to a modern persisted queries solution such as Apollo Link persisted queries.

Install

npm install persistgraphql

yarn add persistgraphql

pnpm add persistgraphql

Imports

addPersistedQueries

wrong

import addPersistedQueries from 'persistgraphql'

correct

import { addPersistedQueries } from 'persistgraphql'

This is a named export from the package. The default export does not exist.

default (whole module)

wrong

const persistgraphql = require('persistgraphql')

correct

import * as persistgraphql from 'persistgraphql'

If using CommonJS, use require(); for ESM use import * as.

OutputMap type

wrong

import { OutputMap } from 'persistgraphql'

correct

import type { OutputMap } from 'persistgraphql'

TypeScript users should use import type for the type-only export.

Quickstart

Shows end-to-end setup: CLI to generate query map, client-side network interface integration, and server-side middleware to resolve query IDs.

// Build the query map: persists queries from .graphql files into extracted_queries.json
// CLI: persistgraphql src/ output.json --add_typename

// On the client (Apollo Client 1.x)
import { createNetworkInterface } from 'apollo-client';
import { addPersistedQueries } from 'persistgraphql';
import queryMap from './extracted_queries.json';

const networkInterface = createNetworkInterface({ uri: '/graphql' });
addPersistedQueries(networkInterface, queryMap);

// On the server (e.g., Express)
import queryMap from './extracted_queries.json';
import { invert } from 'lodash';
const invertedMap = invert(queryMap);
app.use('/graphql', (req, res, next) => {
  if (req.body.id) {
    req.body.query = invertedMap[req.body.id];
  }
  next();
});