Registry / http-networking / persistgraphql

persistgraphql

library0.3.11jsnpmunverified

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.

http-networking web-framework serialization

npm install persistgraphql

github ↗package ↗

INSTALL

IMPORT

SIG · PERSISTGRAPHQL

persistgraphql

http-networkingjavascriptv0.3.11

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

addPersistedQueries

✓ import { addPersistedQueries } from 'persistgraphql'

✗ import addPersistedQueries from 'persistgraphql'

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

default (whole module)

✓ import * as persistgraphql from 'persistgraphql'

✗ const persistgraphql = require('persistgraphql')

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

OutputMap type

✓ import type { OutputMap } from 'persistgraphql'

✗ import { OutputMap } from 'persistgraphql'

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

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(); });

persistgraphql --version

Debug

Known issues

deprecatedPackage 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.

affects: >=0.0.0

gotchaThe 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).

affects: >=0.0.0

gotchaWhen 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`

affects: >=0.0.0

gotchaThe `--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`.

affects: >=0.0.0

gotchaThe 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.

affects: >=0.0.0

Errors

Common errors & fixes

Error: Cannot find module 'graphql/language'

Missing peer dependency 'graphql'

fix

npm install graphql

Cannot read property 'definitions' of undefined

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.

TypeError: networkInterface.query is not a function

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.

persistgraphql: error: unknown option `--extension'

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

fix

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

Upgrade

Version history

0.3.11latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

5 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/Poincare/apollo-query-whitelisting ↗

packagehttps://www.npmjs.com/package/persistgraphql ↗