# Apollo GRAPHQL Knowledge Patch > Apollo GraphQL - Skill: `nevaberry/apollo-graphql-knowledge-patch` (Agent Skill, multi-file: 10 files) - Install (CLI): `npx skillmds@latest add nevaberry/apollo-graphql-knowledge-patch` - Raw SKILL.md: https://api.skillmd.com/api/skills/nevaberry/apollo-graphql-knowledge-patch/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - License: MIT - Author: nevaberry (https://skillmd.com/u/nevaberry) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/nevaberry/apollo-graphql-knowledge-patch --- # Apollo GraphQL Knowledge Patch Use this skill when changing, upgrading, or debugging Apollo Client, Apollo Server, Apollo Router, Apollo Connectors, or their integration points. Identify the affected product and its installed version before applying guidance; these products have independent release lines. ## How to use this patch 1. Read the project manifest, lockfile, Router configuration, and supergraph schema to identify the exact Apollo products in use. 2. Start with the breaking-change and deprecation notes below. 3. Open the topic reference that matches the task. Version attributions in the references determine whether an item applies. 4. Prefer project types, schemas, configuration validation, and tests when they establish behavior more narrowly than this patch. 5. For migrations, materialize configuration changes and exercise error, streaming, cache, and telemetry paths—not only successful queries. ## Reference index | Reference | Topics | | --- | --- | | [Client and React](references/client-react.md) | Client migration, hooks, types, links, cache, SSR, mocks, refetching | | [Server runtime](references/server-runtime.md) | Server migration, runtime requirements, integrations, incremental delivery, validation limits | | [Router configuration and security](references/router-configuration-security.md) | Configuration, endpoints, JWT, CORS, HTTP limits, deployment, reloads, authorization | | [Planning, execution, and demand control](references/planning-execution-demand.md) | Planning limits, coercion, validation, demand cost, error paths, result handling | | [Caching and persisted queries](references/caching-persisted-queries.md) | Persisted queries, response and entity caches, Redis, invalidation, cache semantics | | [Connectors and extension points](references/connectors-extensions.md) | Connector mappings, traffic, Rhai, coprocessors, Rust plugins, context keys | | [Subscriptions and transport](references/subscriptions-transport.md) | Deduplication, WebSockets, multipart streaming, lifecycle limits, HTTP transport | | [Telemetry and observability](references/telemetry-observability.md) | Metrics, spans, selectors, exporters, error reporting, cardinality | ## Breaking changes and deprecations ### Router configuration migration Router major-version upgrades do not silently rewrite old configuration. Before deploying Router v2, run `router config upgrade --diff`, materialize the result, and use `router config schema` instead of the removed `--schema` flag. Expect busy routers to reject work rather than queue it. See [Router configuration and security](references/router-configuration-security.md). ### Router context and plugin migration Router v2 namespaces built-in context keys under `apollo::...`, removes legacy metric emission through specially named `tracing` fields, and changes plugin service construction to build once and clone per request. Migrate custom code, Rhai, coprocessors, and selectors together. See [Connectors and extension points](references/connectors-extensions.md). ### Router metrics and exporters Router v2 replaces or renames many Router-specific instruments with dotted OpenTelemetry names. Jaeger and later Zipkin export should use OTLP. Do not carry old dashboard names forward without checking their replacement attributes. See [Telemetry and observability](references/telemetry-observability.md). ### Apollo Client 4 imports and construction Install the `rxjs` peer dependency, import React APIs from `@apollo/client/react`, and import `MockedProvider` from `@apollo/client/testing/react`. Construct an `HttpLink` explicitly; constructor shortcuts such as `uri`, `headers`, and `credentials` are gone. Use public package entry points and run the migration codemod before manual cleanup. ```sh npm install @apollo/client@latest graphql rxjs npx @apollo/client-codemod-migrate-3-to-4 src ``` ### Apollo Client 4 errors and observables Client results expose a unified `error`; `ApolloError` and `result.errors` are gone. Classify combined errors with their `.is()` guards. Network failures obey `errorPolicy`, watched-query failures arrive through `next`, and Apollo observables use RxJS semantics. Convert a watched query with `from()` when an RxJS `Observable` is required. ### Apollo Client 4 React lifecycle Render-prop components, HOCs, and `ApolloConsumer` are removed. Query lifecycle callbacks on `useQuery` and `useLazyQuery` are deprecated. `useLazyQuery` is execute-driven, `notifyOnNetworkStatusChange` defaults to true, and only subscribed watched queries remain tracked. Review refetch and abort behavior in [Client and React](references/client-react.md). ### Apollo Client typing declarations Types are namespaced with their APIs, context is augmented through `DefaultContext`, and modern query and mutation result shapes depend on declared default options and effective `errorPolicy`. Do not force obsolete result generics onto modern signatures; use `TypeOverrides.signatureStyle` only as an explicit migration choice. ### Apollo Server 5 prerequisites Upgrade to Node.js 20 or newer and `graphql` 16.11 or newer. Import Express middleware from `@as-integrations/express4` or `express5`; the standalone server no longer embeds Express. Published JavaScript targets ES2023. See [Server runtime](references/server-runtime.md). ### Apollo Server incremental delivery Incremental delivery is tied to exact GraphQL.js prerelease protocols and the matching client handler. Apollo Server 5.1 moved from the alpha-2 format to alpha 9, and later legacy support requires an explicitly configured compatibility executor. Align server version, GraphQL.js version, `Accept` header, and Apollo Client incremental handler as one change. ### Removed or renamed configuration - Replace Router `preview_response_cache` with `response_cache` once using the GA configuration. - Replace `connectors.subgraphs` with `connectors.sources`. - Replace `persisted_queries.experimental_local_manifests` with `persisted_queries.local_manifests`. - Remove ignored `traffic_shaping.deduplicate_variables`; deduplication is always enabled. - Remove the deprecated Connector v0.4 preview flag; the schema link opts in. - Replace native Zipkin export with an OTLP endpoint and replace deprecated Router OpenTelemetry header helpers with `opentelemetry_http` types. ## High-value current patterns ### Suspense and result completeness Use `useSuspenseFragment` when a Suspense boundary owns fragment loading. Client query and hook results expose `dataState` as `empty`, `partial`, `streaming`, or `complete`; use that discriminator rather than assuming that a truthy `data` value is complete. ### Error-policy-aware imperative calls `client.query`, `client.mutate`, `useMutation`, `refetch`, `fetchMore`, and the `useLazyQuery` execute function specialize result types from their effective `errorPolicy`. Preserve literal option values and declared defaults so types can distinguish guaranteed data, optional data, and optional errors. ### Event-driven refetching Configure a `RefetchEventManager` to opt into focus, online, or custom events. Set `refetchOn` globally or per watched query, and use event handlers when the default active-query refetch is not appropriate. ### Router response caching Use the GA `response_cache` namespace. Treat subgraph `Cache-Control` as the primary TTL source, with configured TTL only as fallback. Plan for cache-key regeneration after schema or algorithm changes, and validate selective invalidation indexes before relying on them operationally. ### Router protection limits Review recursive-selection, HTTP header, response-body, planning time and memory, rate, batch, upload, validation, and demand-control limits together. Their failure status and scope differ: some reject the whole request, some skip only a subgraph, and some can run in measurement mode. ### Connector version semantics Connector parsing is selected by the schema's `connect` specification link. The default moved to v0.3; v0.4 changes selection and object-literal parsing and does not alter v0.2/v0.3 schemas. Use the migration CLI to distinguish safe rewrites from mappings that need review. ### Sensitive-data controls Router sensitive-header masking is enabled by default and applies across logs, telemetry, coprocessor communication, and trace-header forwarding, but values copied into coprocessor body or context are outside header masking. Prefer allowlists for subgraph error extensions and test every response destination. ### Telemetry cardinality and semantics Use dotted OpenTelemetry instrument names, keep duration units explicit, size histogram buckets for configured timeouts, and watch the cardinality-overflow counter. A per-view cardinality limit and aggregation can override the common settings; raising limits consumes more memory. ### Streaming lifecycle Subscription deduplication is configurable by header, authentication context, and subgraph. Cap lifetime when appropriate, preserve the distinction between GraphQL and transport errors, and monitor end-reason and rejection metrics. ## Verification checklist - Validate Router YAML with the exact deployed binary. - Exercise startup failure paths for CORS, telemetry selectors, JWT, and removed options. - Test GraphQL errors, network errors, partial data, deferred chunks, and subscription termination separately. - Test cache hits, stale entries, schema changes, Redis failure, and every enabled invalidation index. - Verify metric names, units, attributes, resource labels, sampling, and cardinality in the actual observability backend. - Compile TypeScript tests for every declared client default and each effective `errorPolicy` used by shared wrappers. - Exercise Connector mappings under the specification version linked by the schema, including invalid and missing values.