graphql-request
Minimal GraphQL client for Node.js and browsers. Sends GraphQL queries/mutations over HTTP without the full complexity of Apollo Client or URQL. Single request function: gql`query { ... }` → typed response. No caching, no reactive state — just a thin wrapper over fetch with proper GraphQL serialization and error handling.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
Minimal dependency footprint reduces supply chain risk. No credential storage — headers passed per-request. HTTPS enforced by underlying fetch.
⚡ Reliability
Best When
You need a simple, minimal GraphQL client for server-side use, scripting, or simple frontend data fetching without full client complexity.
Avoid When
You need normalized caching, optimistic updates, subscriptions, or reactive state management — use Apollo Client or URQL.
Use Cases
- • Make one-off GraphQL queries from server-side scripts and agent tools without Apollo Client overhead
- • Call GraphQL APIs from Node.js agent backends where caching and reactive state management aren't needed
- • Lightweight GraphQL client for CLI tools, build scripts, and Lambda functions that need simple query execution
- • Type-safe GraphQL requests in TypeScript projects using gql-tada or codegen for response types
- • Proxy or aggregate multiple GraphQL API responses in agent pipelines where full client lifecycle management is unnecessary
Not For
- • Frontend applications needing normalized cache, reactive updates, or optimistic UI — use Apollo Client or URQL
- • Complex GraphQL operations with subscriptions — graphql-request doesn't support WebSocket subscriptions
- • Teams needing request deduplication and background refetching — SWR or React Query combined with graphql-request for that pattern
Interface
Authentication
Auth headers passed via requestConfig.headers or per-request headers. Supports all standard HTTP auth patterns via header injection. No built-in OAuth — pass tokens manually.
Pricing
MIT-licensed. ~5KB minzipped.
Agent Metadata
Known Gotchas
- ⚠ graphql-request v6 changed to ESM-only — CommonJS require() no longer works; agents in CommonJS environments must use dynamic import() or stay on v5
- ⚠ Variables must be serializable — passing class instances or functions in variables object causes silent serialization failures
- ⚠ GraphQL errors and HTTP errors are different exception types — always catch both ClientError (GraphQL errors) and network errors separately
- ⚠ No automatic retry logic — agents must implement their own retry for network failures; library provides no built-in resilience
- ⚠ No request batching — each gql call is a separate HTTP request; batch manually or use Apollo Client for request batching
- ⚠ TypeScript generics require explicit type annotation: request<MyType>(query) — without generics, response is typed as 'any'
Alternatives
Full Evaluation Report
Comprehensive deep-dive: security analysis, reliability audit, agent experience review, cost modeling, competitive positioning, and improvement roadmap for graphql-request.
AI-powered analysis · PDF + markdown · Delivered within 30 minutes
Package Brief
Quick verdict, integration guide, cost projections, gotchas with workarounds, and alternatives comparison.
Delivered within 10 minutes
Score Monitoring
Get alerted when this package's AF, security, or reliability scores change significantly. Stay ahead of regressions.
Continuous monitoring
Scores are editorial opinions as of 2026-03-07.