{"id":18658,"library":"persistgraphql","title":"PersistGraphQL","description":"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.","status":"deprecated","version":"0.3.11","language":"javascript","source_language":"en","source_url":"https://github.com/Poincare/apollo-query-whitelisting","tags":["javascript","typescript"],"install":[{"cmd":"npm install persistgraphql","lang":"bash","label":"npm"},{"cmd":"yarn add persistgraphql","lang":"bash","label":"yarn"},{"cmd":"pnpm add persistgraphql","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This is a named export from the package. The default export does not exist.","wrong":"import addPersistedQueries from 'persistgraphql'","symbol":"addPersistedQueries","correct":"import { addPersistedQueries } from 'persistgraphql'"},{"note":"If using CommonJS, use require(); for ESM use import * as.","wrong":"const persistgraphql = require('persistgraphql')","symbol":"default (whole module)","correct":"import * as persistgraphql from 'persistgraphql'"},{"note":"TypeScript users should use import type for the type-only export.","wrong":"import { OutputMap } from 'persistgraphql'","symbol":"OutputMap type","correct":"import type { OutputMap } from 'persistgraphql'"}],"quickstart":{"code":"// Build the query map: persists queries from .graphql files into extracted_queries.json\n// CLI: persistgraphql src/ output.json --add_typename\n\n// On the client (Apollo Client 1.x)\nimport { createNetworkInterface } from 'apollo-client';\nimport { addPersistedQueries } from 'persistgraphql';\nimport queryMap from './extracted_queries.json';\n\nconst networkInterface = createNetworkInterface({ uri: '/graphql' });\naddPersistedQueries(networkInterface, queryMap);\n\n// On the server (e.g., Express)\nimport queryMap from './extracted_queries.json';\nimport { invert } from 'lodash';\nconst invertedMap = invert(queryMap);\napp.use('/graphql', (req, res, next) => {\n  if (req.body.id) {\n    req.body.query = invertedMap[req.body.id];\n  }\n  next();\n});","lang":"typescript","description":"Shows end-to-end setup: CLI to generate query map, client-side network interface integration, and server-side middleware to resolve query IDs."},"warnings":[{"fix":"Consider using 'persisted-query-lib' or Apollo's built-in persisted queries support in Apollo Client >=2.","message":"Package is no longer maintained; last release was in 2017. Doesn't support Apollo Client v2+ or modern GraphQL tooling.","severity":"deprecated","affected_versions":">=0.0.0"},{"fix":"Ensure all queries are in dedicated .graphql files or use the gql tag in .js/.ts files (requires `--js` flag).","message":"The package only works with statically analyzable queries from .graphql files or template literals with the gql tag. Dynamically constructed queries are ignored.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Run `persistgraphql src/ --js --extension=ts`","message":"When using TypeScript, you must pass `--js --extension=ts` to extract queries from .ts files. The tool does not automatically detect TypeScript.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Include `--add_typename` if you use Apollo Client's cache or fragments that rely on `__typename`.","message":"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.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Upgrade to a modern persisted queries solution such as Apollo Link persisted queries.","message":"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.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"npm install graphql","cause":"Missing peer dependency 'graphql'","error":"Error: Cannot find module 'graphql/language'"},{"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.","cause":"The query map does not contain an entry for the query being sent (hash mismatch).","error":"Cannot read property 'definitions' of undefined"},{"fix":"Use Apollo Client 1.x or use the package only with that version.","cause":"addPersistedQueries expects a valid Apollo Client network interface from v1. Using an incompatible version.","error":"TypeError: networkInterface.query is not a function"},{"fix":"Use: persistgraphql src/ --js --extension=ts","cause":"The --js flag is required before --extension.","error":"persistgraphql: error: unknown option `--extension'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}