{"id":16294,"library":"apollo-client-mux","title":"Apollo Client Mux","description":"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.","status":"active","version":"0.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/izumin5210/apollo-client-mux","tags":["javascript","graphql","apollo","apollo-client","apollo-link","typescript"],"install":[{"cmd":"npm install apollo-client-mux","lang":"bash","label":"npm"},{"cmd":"yarn add apollo-client-mux","lang":"bash","label":"yarn"},{"cmd":"pnpm add apollo-client-mux","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for Apollo Client functionality.","package":"@apollo/client","optional":false},{"reason":"Required for GraphQL AST manipulation and client operations.","package":"graphql","optional":false}],"imports":[{"note":"This utility is imported from a specific subpath, not the main package entry.","wrong":"import { addEndpointDirectiveForCodegen } from 'apollo-client-mux';","symbol":"addEndpointDirectiveForCodegen","correct":"import { addEndpointDirectiveForCodegen } from 'apollo-client-mux/transform';"},{"note":"withCacheMux is a named export function used to create a muxed cache class, not a direct class export.","wrong":"import ApolloCacheMux from 'apollo-client-mux';","symbol":"withCacheMux","correct":"import { withCacheMux } from 'apollo-client-mux';"},{"note":"createApolloLinkMux is a named export function that constructs the multiplexing ApolloLink.","wrong":"import ApolloLinkMux from 'apollo-client-mux';","symbol":"createApolloLinkMux","correct":"import { createApolloLinkMux } from 'apollo-client-mux';"}],"quickstart":{"code":"import { ApolloClient, HttpLink, InMemoryCache } from '@apollo/client';\nimport { ApolloCacheMux, withCacheMux, createApolloLinkMux } from 'apollo-client-mux';\nimport type { CodegenConfig } from '@graphql-codegen/cli';\nimport { addEndpointDirectiveForCodegen } from 'apollo-client-mux/transform';\n\n// --- GraphQL Codegen Configuration (for your endpoint) ---\n// This config snippet assumes you have graphql-codegen setup\n// and want to route operations for 'yourEndpoint' through the mux.\nconst codegenConfig: CodegenConfig = {\n  schema: 'http://localhost:4000/graphql', // Your endpoint's schema\n  generates: {\n    'src/gql/yourEndpoint/': {\n      preset: 'client',\n      documentTransforms: [\n        {\n          transform: addEndpointDirectiveForCodegen({\n            endpointName: 'yourEndpoint' // Must match the name used in client setup\n          })\n        }\n      ]\n    }\n  }\n};\n\n// --- Apollo Client Mux Setup ---\n\n// 1. Create muxed cache\nconst InMemoryCacheMux = withCacheMux(InMemoryCache);\nconst yourEndpointCache = new InMemoryCache();\nconst defaultCache = new InMemoryCache();\n\nconst cache = new InMemoryCacheMux({\n  mux: {\n    caches: {\n      yourEndpoint: yourEndpointCache // Cache specifically for 'yourEndpoint'\n    }\n  },\n  // Options for the default cache (used when no @endpoint directive is present)\n  ...defaultCache.extract()\n});\n\n// 2. Create muxed link\nconst yourEndpointHttpLink = new HttpLink({ uri: 'http://localhost:4001/graphql' });\nconst defaultHttpLink = new HttpLink({ uri: 'http://localhost:4000/graphql' });\n\nconst link = createApolloLinkMux({\n  links: {\n    yourEndpoint: yourEndpointHttpLink // Link specifically for 'yourEndpoint'\n  },\n  defaultLink: defaultHttpLink // Link for operations without @endpoint\n});\n\n// 3. Create Apollo Client instance with muxed cache and link\nconst client = new ApolloClient({\n  cache,\n  link\n});\n\nconsole.log('Apollo Client with Muxed Endpoints initialized:', client);\n\n// Example: Execute a query (assuming your codegen generated this)\n// client.query({ query: YourEndpointQueryDocument });\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Monitor GitHub repository for release notes and changelogs. Pin specific patch versions or implement robust integration tests.","message":"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.","severity":"breaking","affected_versions":">=0.0.1"},{"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.","message":"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`.","severity":"gotcha","affected_versions":">=0.0.1"},{"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.","message":"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`.","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure you are using `import { addEndpointDirectiveForCodegen } from 'apollo-client-mux/transform';` and that your module resolution is configured for ESM.","cause":"Incorrect import path or CommonJS `require()` syntax used in an ESM context for `addEndpointDirectiveForCodegen`.","error":"TypeError: (0 , _apollo_client_mux_transform__WEBPACK_IMPORTED_MODULE_2__.addEndpointDirectiveForCodegen) is not a function"},{"fix":"Double-check that the `endpointName` option in `addEndpointDirectiveForCodegen` matches the keys provided in the `links` and `caches` configuration for the multiplexers.","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`.","error":"Error: Apollo Client Mux: Endpoint 'yourEndpointName' not found in muxed links/caches."},{"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.","cause":"Often occurs if `withCacheMux` is not correctly used to instantiate the cache, or if an incorrect `ApolloCache` instance is passed to the `ApolloClient`.","error":"Invariant Violation: 'cache' must be an instance of ApolloCache or a function that returns one."}],"ecosystem":"npm"}