{"id":15631,"library":"graphql-ruby-client","title":"GraphQL Ruby Client for JavaScript","description":"The `graphql-ruby-client` is a JavaScript client library specifically designed to integrate with `graphql-ruby` servers. It facilitates frontend interactions by generating JavaScript modules from `.graphql` query, mutation, and subscription files, which are then consumed by popular client-side GraphQL libraries such as Apollo Client, Relay, or urql. Currently at version 1.14.9, the package demonstrates an active, incremental release cadence focused on bug fixes and feature enhancements, with the latest update being a couple of months ago. Its key differentiator lies in its tight integration with `graphql-ruby`, offering specialized runtime utilities like fetchers for various subscription backends (e.g., Ably, Pusher) and tooling for persisted queries, which are optimized for the Ruby GraphQL ecosystem. This makes it a primary choice for JavaScript frontends interfacing with Ruby-based GraphQL APIs, particularly within Rails applications.","status":"active","version":"1.14.9","language":"javascript","source_language":"en","source_url":"https://github.com/rmosolgo/graphql-ruby","tags":["javascript","typescript"],"install":[{"cmd":"npm install graphql-ruby-client","lang":"bash","label":"npm"},{"cmd":"yarn add graphql-ruby-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add graphql-ruby-client","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides core GraphQL client functionalities like caching, state management, and network operations, used in conjunction with this library's fetchers.","package":"@apollo/client","optional":false},{"reason":"Required for GraphQL schema parsing, validation, and standard GraphQL operations within the client environment.","package":"graphql","optional":false}],"imports":[{"note":"Primary utility for creating an Apollo Link compatible fetcher. The CommonJS `require` syntax is incorrect for modern ESM usage.","wrong":"const createFetcher = require('graphql-ruby-client').createFetcher;","symbol":"createFetcher","correct":"import { createFetcher } from 'graphql-ruby-client';"},{"note":"Represents a GraphQL operation, often used with generated query/mutation code. It is a named export, not a default export from a subpath.","wrong":"import Operation from 'graphql-ruby-client/Operation';","symbol":"Operation","correct":"import { Operation } from 'graphql-ruby-client';"},{"note":"A specific utility for integrating with Ably for GraphQL subscriptions. This is a default export from a subpath.","wrong":"import { createAblyFetcher } from 'graphql-ruby-client';","symbol":"createAblyFetcher","correct":"import createAblyFetcher from 'graphql-ruby-client/subscriptions/createAblyFetcher';"}],"quickstart":{"code":"import { ApolloClient, InMemoryCache, ApolloProvider, HttpLink } from '@apollo/client';\nimport { createFetcher } from 'graphql-ruby-client';\n\n// Assuming 'QueryName' and 'QueryName_variables' are generated from your .graphql files\n// In a real application, these would be imported from your generated code.\nconst GENERATED_QUERY = {\n  id: 'some-unique-query-id',\n  document: `query SomeQuery($id: ID!) {\n    user(id: $id) {\n      id\n      name\n      email\n    }\n  }`,\n  ast: { /* full GraphQL AST would be here */ },\n  variables: (id) => ({ id }),\n  operationName: 'SomeQuery'\n};\n\n// Configure the HTTP endpoint for your GraphQL Ruby server\nconst httpLink = new HttpLink({ uri: 'http://localhost:3000/graphql' });\n\n// Create a fetcher compatible with Apollo Link, using graphql-ruby-client's utility\n// This will handle the specific serialization/deserialization for graphql-ruby\nconst clientFetcher = createFetcher({ \n  link: httpLink,\n  // In a production setup, you'd likely pass a more robust link chain\n});\n\nconst client = new ApolloClient({\n  link: clientFetcher,\n  cache: new InMemoryCache(),\n});\n\n// Example of executing a generated query\nasync function fetchUser(userId: string) {\n  try {\n    const { data } = await client.query({\n      query: GENERATED_QUERY.document,\n      variables: GENERATED_QUERY.variables(userId),\n      operationName: GENERATED_QUERY.operationName,\n    });\n    console.log('Fetched User:', data.user);\n    return data.user;\n  } catch (error) {\n    console.error('Error fetching user:', error);\n    throw error;\n  }\n}\n\n// Example usage:\nfetchUser('123').then(user => {\n  if (user) {\n    console.log(`User name: ${user.name}`);\n  }\n});","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=1.11.6"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Run `npm install graphql-ruby-client` or `yarn add graphql-ruby-client` to install the package. Verify the import path is correct.","cause":"The package `graphql-ruby-client` is not installed or incorrectly referenced in your project's dependencies.","error":"Module not found: Error: Can't resolve 'graphql-ruby-client'"},{"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.","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.","error":"TypeError: createFetcher is not a function"},{"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.","cause":"This Apollo Client error indicates that the `ApolloProvider` is missing or improperly configured, preventing components from accessing the Apollo Client instance.","error":"Invariant Violation: Could not find 'client' in the context or pass it as a prop"}],"ecosystem":"npm"}