Registry / devops / graphql-persisted

graphql-persisted

library0.0.7jsnpmunverified

An experimental, opinionated GraphQL client library focused on server-persisted queries, type safety, and minimizing GraphQL usage in client code. Current version 0.0.7 is WIP and not for production. It leverages graphql-normalize and offers React hooks for persisted queries, mutations, and subscriptions. Key differentiators: no client-side graphql dependency, fully persisted operations, and built-in type safety with TypeScript declarations. The package is pre-1.0 and APIs are subject to breaking changes.

devops

npm install graphql-persisted

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRAPHQL-PERSISTED

graphql-persisted

devopsjavascriptv0.0.7

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

GraphQLQueryCache

✓ import { GraphQLQueryCache } from 'graphql-persisted'

✗ import GraphQLQueryCache from 'graphql-persisted'

Named export, not default.

usePersistedQuery

✓ import { usePersistedQuery } from 'graphql-persisted'

✗ const { usePersistedQuery } = require('graphql-persisted')

ESM only; package does not expose CJS.

usePersistedMutation

✓ import { usePersistedMutation } from 'graphql-persisted'

Named export for mutation hook.

unwrapFragment

✓ import { unwrapFragment } from 'graphql-persisted'

✗ import { unwrapFragment } from 'graphql-persisted/fragments'

Direct from package root, no subpath.

types

✓ import type { PersistedQueryResult } from 'graphql-persisted'

✗ import { PersistedQueryResult } from 'graphql-persisted'

Use type import for TypeScript types to avoid runtime issues.

Demonstrates creating a GraphQLQueryCache instance and using the usePersistedQuery hook to fetch a named persisted query.

import { GraphQLQueryCache, usePersistedQuery } from 'graphql-persisted'; const cache = new GraphQLQueryCache({ endpoint: 'https://api.example.com/graphql', apiKey: process.env.API_KEY ?? '' }); function MyComponent() { const { data, loading, error } = usePersistedQuery('GetUser', { variables: { id: '123' } }); if (loading) return <div>Loading...</div>; if (error) return <div>Error: {error.message}</div>; return <div>User: {data.user.name}</div>; }

Debug

Known issues

breakingPackage is pre-1.0 and APIs are unstable. Expect breaking changes between minor versions.

fix

Pin to exact version and lockfile; check changelog before upgrades.

affects: <1.0

gotchaNamed exports only: all exports are named, not default. Attempting default import will yield undefined.

fix

Use named import syntax: import { ... } from 'graphql-persisted'

affects: >=0.0.0

gotchaRequires peer dependencies (graphql, immer, react) to be installed manually. Missing them will cause runtime errors.

fix

Install peer deps: npm install graphql immer react

affects: >=0.0.0

deprecatedThe GraphQLQueryCache constructor may require additional options in future versions.

fix

Stay updated with API changes; constructor args may change.

affects: >=0.0.7

Errors

Common errors & fixes

TypeError: Cannot destructure property 'data' of '(0 , _graphql_persisted.usePersistedQuery)(...)' as it is undefined.

Default import used instead of named import; usePersistedQuery is undefined.

fix

Change import to: import { usePersistedQuery } from 'graphql-persisted'

Module not found: Error: Can't resolve 'graphql' in '...'

Missing peer dependency graphql.

fix

Run: npm install graphql

Error: GraphQLQueryCache is not a constructor

Trying to instantiate after default import, which is undefined.

fix

Import named export: import { GraphQLQueryCache } from 'graphql-persisted'

Upgrade

Version history

0.0.7latest on npm

Audit

Dependencies

graphqlrequiredPeer dependency for GraphQL schema/operation handling

immerrequiredPeer dependency for immutable state updates in query cache

reactrequiredPeer dependency for React hooks (usePersistedQuery, etc.)

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/tgriesser/graphql-persisted ↗

packagegraphql-persisted ↗

homepagehttps://github.com/tgriesser/graphql-persisted#readme ↗