{"id":15524,"library":"awesome-graphql-client","title":"Awesome GraphQL Client","description":"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`.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/lynxtaa/awesome-graphql-client","tags":["javascript","graphql","request","graphql-client","apollo","typescript"],"install":[{"cmd":"npm install awesome-graphql-client","lang":"bash","label":"npm"},{"cmd":"yarn add awesome-graphql-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add awesome-graphql-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const AwesomeGraphQLClient = require('awesome-graphql-client');","symbol":"AwesomeGraphQLClient","correct":"import { AwesomeGraphQLClient } from 'awesome-graphql-client';"},{"note":"Used for type checking and catching specific errors returned by the GraphQL server, including error extensions. ESM-only since v3.0.0.","wrong":"const { GraphQLRequestError } = require('awesome-graphql-client');","symbol":"GraphQLRequestError","correct":"import { GraphQLRequestError } from 'awesome-graphql-client';"},{"note":"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.","wrong":"import gql from 'graphql-tag';","symbol":"gql","correct":"import { gql } from 'awesome-graphql-client';"},{"note":"A utility function to check if a value is a file upload. Useful for customizing file handling logic. ESM-only since v3.0.0.","wrong":"const isFileUpload = require('awesome-graphql-client').isFileUpload;","symbol":"isFileUpload","correct":"import { isFileUpload } from 'awesome-graphql-client';"}],"quickstart":{"code":"import { openAsBlob } from 'node:fs';\nimport { AwesomeGraphQLClient, GraphQLRequestError } from 'awesome-graphql-client';\nimport { File } from 'node:buffer'; // For Node.js versions < 20, where global File isn't available\nimport fs from 'node:fs/promises';\n\nconst dummyFilePath = './temp_avatar.png';\n\nasync function run() {\n  // Create a dummy 1x1 transparent PNG file for the example\n  await fs.writeFile(dummyFilePath, Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=', 'base64'));\n\n  const client = new AwesomeGraphQLClient({\n    endpoint: 'http://localhost:8080/graphql', // IMPORTANT: Replace with your actual GraphQL endpoint\n    onError: (error: GraphQLRequestError | Error) => {\n      if (error instanceof GraphQLRequestError) {\n        console.error('GraphQL API Error:', error.message, 'Details:', error.errors, 'Extensions:', error.extensions);\n      } else {\n        console.error('Network or client-side Error:', error.message);\n      }\n    }\n  });\n\n  const UploadUserAvatar = `\n    mutation uploadUserAvatar($userId: Int!, $file: Upload!) {\n      updateUser(id: $userId, input: { avatar: $file }) {\n        id\n        avatarUrl\n      }\n    }\n  `;\n\n  try {\n    const blob = await openAsBlob(dummyFilePath);\n    // Node.js v20+ provides a global `File` constructor. For older versions, import from 'node:buffer'.\n    const file = new File([blob], 'avatar.png', { type: 'image/png' });\n\n    console.log('Attempting to upload avatar for userId 10...');\n    const data = await client.request(UploadUserAvatar, { file: file, userId: 10 });\n    console.log('Successfully updated user:', data.updateUser.id, 'with new avatar URL:', data.updateUser.avatarUrl);\n  } catch (error) {\n    console.error('An unhandled error occurred during request:', error);\n  } finally {\n    // Clean up the dummy file\n    await fs.unlink(dummyFilePath);\n  }\n}\n\nrun();","lang":"typescript","description":"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."},"warnings":[{"fix":"Migrate your codebase to use ES module `import` syntax. Ensure your project is configured for ESM (e.g., `\"type\": \"module\"` in `package.json`).","message":"Version 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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"Version 2.0.0 introduced a breaking change requiring Node.js version 18.18.0 or newer. Older Node.js versions are not supported.","severity":"breaking","affected_versions":">=2.0.0 <3.0.0"},{"fix":"Upgrade your Node.js runtime to version 14 or higher. For current versions, refer to the `engines` field in `package.json`.","message":"Version 0.13.0 dropped support for Node.js 12. Using this version or newer with Node.js 12 will result in compatibility issues.","severity":"breaking","affected_versions":">=0.13.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=0.14.0"},{"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.","message":"Node.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.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"Attempting to `require()` an ES module (ESM) package in a CommonJS (CJS) context.","error":"ERR_REQUIRE_ESM"},{"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.","cause":"CommonJS `require()` is being used, which returns the module object, not a direct constructor in an ESM package, or an incorrect named import.","error":"TypeError: AwesomeGraphQLClient is not a constructor"},{"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.","cause":"Your Node.js runtime environment does not meet the minimum version requirements specified by the package.","error":"The package 'awesome-graphql-client' requires Node.js version ^20.19.0 || ^22.12.0 || >=23. Your current Node.js version is X."},{"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).","cause":"The environment where `awesome-graphql-client` is running (e.g., an older Node.js version) does not provide a global `fetch` API.","error":"TypeError: fetch is not a function"}],"ecosystem":"npm"}