Registry / http-networking / awesome-graphql-client

awesome-graphql-client

JSON →
library3.0.0jsnpmunverified

Awesome GraphQL Client is a lightweight, zero-dependency GraphQL client library designed for both NodeJS and browser environments. It currently ships as v3.0.0 and is ESM-only. The library's core feature set includes robust GraphQL File Upload support as per the `graphql-multipart-request-spec`, full TypeScript integration, and compatibility with GraphQL queries generated by `graphql-tag`. While it does not specify a strict release cadence, the project shows consistent maintenance with regular updates addressing features, bug fixes, and Node.js version compatibility. Key differentiators include its minimal footprint (around 2KB gzipped), built-in file upload capabilities, and suitability for modern React applications when paired with libraries like `react-query`.

npm install awesome-graphql-client
INSTALL
IMPORT
SIG · AWESOME-GRAPHQL-CL
A
awesome-graphql-client
http-networkingjavascriptv3.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

AwesomeGraphQLClient
import { AwesomeGraphQLClient } from 'awesome-graphql-client';
const AwesomeGraphQLClient = require('awesome-graphql-client');
Since v3.0.0, the package is ESM-only. CommonJS `require` statements will fail. This is the primary class for interacting with your GraphQL endpoint.
GraphQLRequestError
import { GraphQLRequestError } from 'awesome-graphql-client';
const { GraphQLRequestError } = require('awesome-graphql-client');
Used for type checking and catching specific errors returned by the GraphQL server, including error extensions. ESM-only since v3.0.0.
gql
import { gql } from 'awesome-graphql-client';
import gql from 'graphql-tag';
This `gql` utility is an internal helper provided by `awesome-graphql-client` for query formatting, not the separate `graphql-tag` package. It helps in cases where you want to avoid runtime parsing of template literal tags if your server only accepts string queries. ESM-only since v3.0.0.
isFileUpload
import { isFileUpload } from 'awesome-graphql-client';
const isFileUpload = require('awesome-graphql-client').isFileUpload;
A utility function to check if a value is a file upload. Useful for customizing file handling logic. ESM-only since v3.0.0.

This quickstart demonstrates how to instantiate `AwesomeGraphQLClient` in a NodeJS environment, perform a GraphQL mutation with file upload support using `node:fs` and the global `File` API (available in Node.js v20+), and includes basic error handling. It creates a temporary image file for the upload example.

import { openAsBlob } from 'node:fs'; import { AwesomeGraphQLClient, GraphQLRequestError } from 'awesome-graphql-client'; import { File } from 'node:buffer'; // For Node.js versions < 20, where global File isn't available import fs from 'node:fs/promises'; const dummyFilePath = './temp_avatar.png'; async function run() { // Create a dummy 1x1 transparent PNG file for the example await fs.writeFile(dummyFilePath, Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=', 'base64')); const client = new AwesomeGraphQLClient({ endpoint: 'http://localhost:8080/graphql', // IMPORTANT: Replace with your actual GraphQL endpoint onError: (error: GraphQLRequestError | Error) => { if (error instanceof GraphQLRequestError) { console.error('GraphQL API Error:', error.message, 'Details:', error.errors, 'Extensions:', error.extensions); } else { console.error('Network or client-side Error:', error.message); } } }); const UploadUserAvatar = ` mutation uploadUserAvatar($userId: Int!, $file: Upload!) { updateUser(id: $userId, input: { avatar: $file }) { id avatarUrl } } `; try { const blob = await openAsBlob(dummyFilePath); // Node.js v20+ provides a global `File` constructor. For older versions, import from 'node:buffer'. const file = new File([blob], 'avatar.png', { type: 'image/png' }); console.log('Attempting to upload avatar for userId 10...'); const data = await client.request(UploadUserAvatar, { file: file, userId: 10 }); console.log('Successfully updated user:', data.updateUser.id, 'with new avatar URL:', data.updateUser.avatarUrl); } catch (error) { console.error('An unhandled error occurred during request:', error); } finally { // Clean up the dummy file await fs.unlink(dummyFilePath); } } run();
Debug
Known issues
breakingVersion 3.0.0 of `awesome-graphql-client` is now ESM-only. This means CommonJS `require()` statements are no longer supported and will result in runtime errors.
fix
Migrate your codebase to use ES module `import` syntax. Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).
affects: >=3.0.0
breakingVersion 2.0.0 introduced a breaking change requiring Node.js version 18.18.0 or newer. Older Node.js versions are not supported.
fix
Upgrade your Node.js runtime to version 18.18.0 or higher. For version 3.0.0, Node.js 20.19.0 || ^22.12.0 || >=23 is required.
affects: >=2.0.0 <3.0.0
breakingVersion 0.13.0 dropped support for Node.js 12. Using this version or newer with Node.js 12 will result in compatibility issues.
fix
Upgrade your Node.js runtime to version 14 or higher. For current versions, refer to the `engines` field in `package.json`.
affects: >=0.13.0
gotchaThe `gql` export from `awesome-graphql-client` is an internal utility for query formatting, not an alias for the `graphql-tag` package. While it serves a similar purpose, do not confuse it with the external `graphql-tag` library.
fix
If you intend to use `graphql-tag` for parsing template literals, install and import it separately. Use `awesome-graphql-client`'s `gql` only if you specifically need its internal formatting capabilities as documented.
affects: >=0.14.0
gotchaNode.js environment setup for file uploads requires either a global `File` constructor (available in Node.js v20+) or importing `File` from `node:buffer` for older Node.js versions (v16.17.0+). Additionally, `openAsBlob` from `node:fs` is crucial for handling local files.
fix
Ensure your Node.js version meets the requirements (v20+ recommended for `File`), or explicitly import `File` from `node:buffer`. Use `openAsBlob` for creating `Blob` objects from local file paths.
affects: >=2.0.0
Errors
Common errors & fixes
ERR_REQUIRE_ESM
Attempting to `require()` an ES module (ESM) package in a CommonJS (CJS) context.
fix
Update your import statements from `const Client = require('awesome-graphql-client');` to `import { AwesomeGraphQLClient } from 'awesome-graphql-client';`. Ensure your `package.json` contains `"type": "module"` or files use `.mjs` extension.
TypeError: AwesomeGraphQLClient is not a constructor
CommonJS `require()` is being used, which returns the module object, not a direct constructor in an ESM package, or an incorrect named import.
fix
Refactor your import to `import { AwesomeGraphQLClient } from 'awesome-graphql-client';` for ESM, or if still in a CJS environment (which is not supported since v3), you might attempt `const { AwesomeGraphQLClient } = await import('awesome-graphql-client');` but full CJS compatibility is removed in v3.
The package 'awesome-graphql-client' requires Node.js version ^20.19.0 || ^22.12.0 || >=23. Your current Node.js version is X.
Your Node.js runtime environment does not meet the minimum version requirements specified by the package.
fix
Upgrade your Node.js installation to a supported version (20.19.0, 22.12.0, or newer). Use a tool like `nvm` (Node Version Manager) for easy version switching.
TypeError: fetch is not a function
The environment where `awesome-graphql-client` is running (e.g., an older Node.js version) does not provide a global `fetch` API.
fix
Provide a `fetch` polyfill to the client configuration: `new AwesomeGraphQLClient({ endpoint: '/graphql', fetch: require('node-fetch') })` (for Node.js versions without native `fetch`) or ensure your Node.js version is recent enough (v18+ for global fetch).
Upgrade
Version history
3.0.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
19 hits · last 30 days
node
14
Amazon
1
OpenAI (training)
1
Resources
awesome-graphql-client — npm install awesome-graphql-client · libregistry