Apollo Client Mux

0.0.3 · active · verified Wed Apr 22

apollo-client-mux is an early-stage library, currently at version 0.0.3, designed for advanced GraphQL client configurations. It enables a single Apollo Client instance to manage interactions with multiple distinct GraphQL endpoints. The library achieves this by allowing developers to define separate ApolloCache and ApolloLink instances for each endpoint, which are then integrated into a 'muxed' cache and link. This approach is particularly useful in microservice architectures or when integrating with multiple third-party GraphQL APIs, where different data models and network configurations necessitate isolated caching and request routing. It integrates with `@graphql-codegen` via a transformation utility to automatically apply an `@endpoint` directive to operation documents, ensuring queries and mutations are routed to the correct endpoint. Its current low version suggests active development and potential for API changes.

Common errors

```
TypeError: (0 , _apollo_client_mux_transform__WEBPACK_IMPORTED_MODULE_2__.addEndpointDirectiveForCodegen) is not a function
```
cause Incorrect import path or CommonJS `require()` syntax used in an ESM context for `addEndpointDirectiveForCodegen`.

fix Ensure you are using `import { addEndpointDirectiveForCodegen } from 'apollo-client-mux/transform';` and that your module resolution is configured for ESM.
```
Error: Apollo Client Mux: Endpoint 'yourEndpointName' not found in muxed links/caches.
```
cause The endpoint name specified in an operation's `@endpoint` directive (or implicitly via codegen) does not have a corresponding entry in the `links` or `caches` object passed to `createApolloLinkMux` or `withCacheMux`.

fix Double-check that the `endpointName` option in `addEndpointDirectiveForCodegen` matches the keys provided in the `links` and `caches` configuration for the multiplexers.
```
Invariant Violation: 'cache' must be an instance of ApolloCache or a function that returns one.
```
cause Often occurs if `withCacheMux` is not correctly used to instantiate the cache, or if an incorrect `ApolloCache` instance is passed to the `ApolloClient`.

fix Ensure `withCacheMux(InMemoryCache)` is called and then `new InMemoryCacheMux(...)` is used to create the actual cache instance. Verify that the resulting object is what's passed to `ApolloClient`'s `cache` option.

Warnings

breaking As a very early-stage library (v0.0.3), the API surface is highly subject to breaking changes. Developers should expect frequent updates and potential refactors in minor and patch versions.
Fix: Monitor GitHub repository for release notes and changelogs. Pin specific patch versions or implement robust integration tests.
gotcha Endpoint names used in `addEndpointDirectiveForCodegen` (via `endpointName` option) must exactly match the keys in the `mux.caches` and `mux.links` objects when initializing `InMemoryCacheMux` and `createApolloLinkMux`.
Fix: Ensure consistent string literals for endpoint names across your `graphql-codegen` configuration and Apollo Client setup. Use TypeScript enums or constants to avoid typos.
gotcha This library critically depends on `@graphql-codegen` for applying the `@endpoint` directive. Without proper codegen setup, the multiplexing functionality will not route operations correctly, defaulting all to the `defaultLink` and `defaultCache`.
Fix: Follow the documentation for `graphql-codegen` and the library's `addEndpointDirectiveForCodegen` utility. Verify that the generated operation documents include the `@endpoint` directive correctly for your target endpoints.

Install

npm install apollo-client-mux npm
yarn add apollo-client-mux yarn
pnpm add apollo-client-mux pnpm

Imports

addEndpointDirectiveForCodegen

wrong:

import { addEndpointDirectiveForCodegen } from 'apollo-client-mux';

correct:

import { addEndpointDirectiveForCodegen } from 'apollo-client-mux/transform';

This utility is imported from a specific subpath, not the main package entry.

withCacheMux
wrong:
```
import ApolloCacheMux from 'apollo-client-mux';
```
correct:
```
import { withCacheMux } from 'apollo-client-mux';
```
withCacheMux is a named export function used to create a muxed cache class, not a direct class export.
createApolloLinkMux
wrong:
```
import ApolloLinkMux from 'apollo-client-mux';
```
correct:
```
import { createApolloLinkMux } from 'apollo-client-mux';
```
createApolloLinkMux is a named export function that constructs the multiplexing ApolloLink.

Quickstart

Demonstrates configuring graphql-codegen to add an `@endpoint` directive and then setting up an Apollo Client instance with a multiplexed cache and link for multiple GraphQL endpoints.

import { ApolloClient, HttpLink, InMemoryCache } from '@apollo/client';
import { ApolloCacheMux, withCacheMux, createApolloLinkMux } from 'apollo-client-mux';
import type { CodegenConfig } from '@graphql-codegen/cli';
import { addEndpointDirectiveForCodegen } from 'apollo-client-mux/transform';

// --- GraphQL Codegen Configuration (for your endpoint) ---
// This config snippet assumes you have graphql-codegen setup
// and want to route operations for 'yourEndpoint' through the mux.
const codegenConfig: CodegenConfig = {
  schema: 'http://localhost:4000/graphql', // Your endpoint's schema
  generates: {
    'src/gql/yourEndpoint/': {
      preset: 'client',
      documentTransforms: [
        {
          transform: addEndpointDirectiveForCodegen({
            endpointName: 'yourEndpoint' // Must match the name used in client setup
          })
        }
      ]
    }
  }
};

// --- Apollo Client Mux Setup ---

// 1. Create muxed cache
const InMemoryCacheMux = withCacheMux(InMemoryCache);
const yourEndpointCache = new InMemoryCache();
const defaultCache = new InMemoryCache();

const cache = new InMemoryCacheMux({
  mux: {
    caches: {
      yourEndpoint: yourEndpointCache // Cache specifically for 'yourEndpoint'
    }
  },
  // Options for the default cache (used when no @endpoint directive is present)
  ...defaultCache.extract()
});

// 2. Create muxed link
const yourEndpointHttpLink = new HttpLink({ uri: 'http://localhost:4001/graphql' });
const defaultHttpLink = new HttpLink({ uri: 'http://localhost:4000/graphql' });

const link = createApolloLinkMux({
  links: {
    yourEndpoint: yourEndpointHttpLink // Link specifically for 'yourEndpoint'
  },
  defaultLink: defaultHttpLink // Link for operations without @endpoint
});

// 3. Create Apollo Client instance with muxed cache and link
const client = new ApolloClient({
  cache,
  link
});

console.log('Apollo Client with Muxed Endpoints initialized:', client);

// Example: Execute a query (assuming your codegen generated this)
// client.query({ query: YourEndpointQueryDocument });

view raw JSON →