Awesome GraphQL Client

Common errors

• ERR_REQUIRE_ESM

  cause 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

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

  cause 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

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

Warnings

• breaking 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.
  Fix: Migrate your codebase to use ES module `import` syntax. Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).
• breaking Version 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.
• breaking Version 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`.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install awesome-graphql-client npm
• yarn add awesome-graphql-client yarn
• pnpm add awesome-graphql-client pnpm

Imports

• AwesomeGraphQLClient
  wrong:

  const AwesomeGraphQLClient = require('awesome-graphql-client');

  correct:

  import { AwesomeGraphQLClient } from '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
  wrong:

  const { GraphQLRequestError } = require('awesome-graphql-client');

  correct:

  import { GraphQLRequestError } from '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
  wrong:

  import gql from 'graphql-tag';

  correct:

  import { gql } from 'awesome-graphql-client';

  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
  wrong:

  const isFileUpload = require('awesome-graphql-client').isFileUpload;

  correct:

  import { isFileUpload } from 'awesome-graphql-client';

  A utility function to check if a value is a file upload. Useful for customizing file handling logic. ESM-only since v3.0.0.

Quickstart

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