GraphQL Ruby Client for JavaScript

Common errors

• Module not found: Error: Can't resolve 'graphql-ruby-client'

  cause The package `graphql-ruby-client` is not installed or incorrectly referenced in your project's dependencies.
  fix Run `npm install graphql-ruby-client` or `yarn add graphql-ruby-client` to install the package. Verify the import path is correct.

• TypeError: createFetcher is not a function

  cause Attempting to use `createFetcher` (or similar utilities) with an incorrect import statement, often `require()` in an ESM context or a wrong named/default import.
  fix Ensure you are using `import { createFetcher } from 'graphql-ruby-client';` for named exports, or `import createAblyFetcher from 'graphql-ruby-client/subscriptions/createAblyFetcher';` for default exports from subpaths, and that your environment supports ESM.

• Invariant Violation: Could not find 'client' in the context or pass it as a prop

  cause This Apollo Client error indicates that the `ApolloProvider` is missing or improperly configured, preventing components from accessing the Apollo Client instance.
  fix Ensure your root React component (or equivalent in other frameworks) is wrapped with `<ApolloProvider client={yourApolloClientInstance}>` and that `yourApolloClientInstance` is correctly initialized with the `graphql-ruby-client` fetcher.

Warnings

• gotcha The `graphql-ruby-client` package is licensed under LGPLv3. For commercial use cases, particularly without open-sourcing derivative works, a special commercial license is required, typically obtained by becoming a `graphql-pro` customer. Failing to adhere to the LGPLv3 terms can have significant legal implications for proprietary applications.
  Fix: Review the LGPLv3 license terms carefully. If commercial use requires a different license, consider purchasing `graphql-pro` or exploring alternative GraphQL client solutions with more permissive licenses like MIT or Apache 2.0.
• breaking Version 1.11.6 introduced a breaking change related to `FieldExtension` where `after_resolve` callbacks now receive extended values instead of original values. While primarily a server-side change, it can affect client-side expectations or generated code if your GraphQL Ruby server utilizes custom field extensions and your client logic depends on the exact data passed through these extensions.
  Fix: If using custom `FieldExtension` on your `graphql-ruby` server, update `after_resolve` implementations to correctly handle the new parameter signature. Verify that any client-side code relying on the behavior of these extensions continues to function as expected after a server upgrade.
• gotcha This library is designed for the `graphql-ruby` server. While it integrates with generic JavaScript GraphQL clients like Apollo, its primary benefits (e.g., specific fetchers, persisted query tooling) are realized when paired with a `graphql-ruby` backend. Using it with other GraphQL server implementations might lead to less optimal performance or require custom configuration.
  Fix: Ensure your backend is `graphql-ruby` for full compatibility. If using another GraphQL server, evaluate if a more generic client (e.g., pure Apollo Client) better suits your needs or if the specialized features of `graphql-ruby-client` can still be leveraged effectively.
• gotcha The `graphql-ruby-client` package primarily provides a code generator and runtime utilities that consume *generated* JavaScript modules from `.graphql` files. Direct ad-hoc query execution without prior generation is not its main intended workflow, and developers should familiarize themselves with the generation process.
  Fix: Integrate the code generation step into your build process. Define your GraphQL operations in `.graphql` files and use the `graphql-ruby-client`'s generator to create the corresponding JavaScript/TypeScript modules before attempting to import and use them in your frontend application.

Install

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

Imports

• createFetcher
  wrong:

  const createFetcher = require('graphql-ruby-client').createFetcher;

  correct:

  import { createFetcher } from 'graphql-ruby-client';

  Primary utility for creating an Apollo Link compatible fetcher. The CommonJS `require` syntax is incorrect for modern ESM usage.
• Operation
  wrong:

  import Operation from 'graphql-ruby-client/Operation';

  correct:

  import { Operation } from 'graphql-ruby-client';

  Represents a GraphQL operation, often used with generated query/mutation code. It is a named export, not a default export from a subpath.
• createAblyFetcher
  wrong:

  import { createAblyFetcher } from 'graphql-ruby-client';

  correct:

  import createAblyFetcher from 'graphql-ruby-client/subscriptions/createAblyFetcher';

  A specific utility for integrating with Ably for GraphQL subscriptions. This is a default export from a subpath.

Quickstart

This quickstart demonstrates how to set up Apollo Client with `graphql-ruby-client`'s `createFetcher` and execute a mock generated GraphQL query against a GraphQL Ruby server. It shows basic client instantiation and a query execution pattern.

import { ApolloClient, InMemoryCache, ApolloProvider, HttpLink } from '@apollo/client';
import { createFetcher } from 'graphql-ruby-client';

// Assuming 'QueryName' and 'QueryName_variables' are generated from your .graphql files
// In a real application, these would be imported from your generated code.
const GENERATED_QUERY = {
  id: 'some-unique-query-id',
  document: `query SomeQuery($id: ID!) {
    user(id: $id) {
      id
      name
      email
    }
  }`,
  ast: { /* full GraphQL AST would be here */ },
  variables: (id) => ({ id }),
  operationName: 'SomeQuery'
};

// Configure the HTTP endpoint for your GraphQL Ruby server
const httpLink = new HttpLink({ uri: 'http://localhost:3000/graphql' });

// Create a fetcher compatible with Apollo Link, using graphql-ruby-client's utility
// This will handle the specific serialization/deserialization for graphql-ruby
const clientFetcher = createFetcher({ 
  link: httpLink,
  // In a production setup, you'd likely pass a more robust link chain
});

const client = new ApolloClient({
  link: clientFetcher,
  cache: new InMemoryCache(),
});

// Example of executing a generated query
async function fetchUser(userId: string) {
  try {
    const { data } = await client.query({
      query: GENERATED_QUERY.document,
      variables: GENERATED_QUERY.variables(userId),
      operationName: GENERATED_QUERY.operationName,
    });
    console.log('Fetched User:', data.user);
    return data.user;
  } catch (error) {
    console.error('Error fetching user:', error);
    throw error;
  }
}

// Example usage:
fetchUser('123').then(user => {
  if (user) {
    console.log(`User name: ${user.name}`);
  }
});