Apollo GRAPHQL Knowledge Patch

Apollo GraphQL Knowledge Patch

Use this skill when work involves recent Apollo Client, Apollo Server, Apollo Router, or Apollo Connectors behavior. Identify the product and installed version first, then read only the relevant topic reference.

Reference index

Apply this patch

1. Determine whether the task concerns Client, Server, Router, Connectors, or an integration between them.
2. Read the project's manifest and lockfile to identify exact product versions before applying version-gated advice.
3. For upgrades, preserve the intermediate migrations described below and in the product reference; do not jump straight to renamed configuration.
4. For Router changes, check security, traffic, and telemetry defaults together because one upgrade can affect status codes, load shedding, and dashboards.
5. For incremental delivery, align the Client handler, Server GraphQL.js alpha, and Accept protocol exactly.
6. Preserve explicit compatibility overrides unless the task authorizes their removal.

Breaking changes and required migrations

Apollo Client 4

• Add the rxjs peer dependency.
• Import React APIs from @apollo/client/react and MockedProvider from @apollo/client/testing/react.
• Use only public entry points; remove direct .js and .cjs imports.
• Run @apollo/client-codemod-migrate-3-to-4, then inspect every change rather than assuming the codemod covers custom links and local state.
• Replace constructor uri, headers, and credentials with an explicit HttpLink supplied as link.
• Move client name/version under clientAwareness, connectToDevTools under devtools.enabled, and rename disableNetworkFetches to prioritizeCacheValues.
• Replace render-prop components, HOCs, and ApolloConsumer with hooks and useApolloClient.
• Replace zen-observable operators with RxJS pipe operators. Wrap ObservableQuery in from() when an RxJS Observable is required.
• Replace ObservableQuery.setOptions() with reobserve() and result() with firstValueFrom(from(query)).
• Replace removed ApolloError and split error properties with the unified error value and class guards.
• Use operation.setContext() because getContext() is frozen; read the cache from operation.client.cache.
• Opt into @client resolution with LocalState, and implement fragmentMatches in custom caches.

Read client-migration.md before changing public imports, link composition, error handling, SSR, incremental handlers, or result types.

Apollo Server 5

• Upgrade to Node.js 20+ and graphql 16.11+; ensure consumers support ES2023.
• Install @as-integrations/express4 or @as-integrations/express5; middleware is no longer exported from @apollo/server/express4.
• Treat startStandaloneServer as a Node HTTP integration, not embedded Express.
• Account for built-in fetch in usage reporting, schema reporting, and subscription callbacks; old global-agent settings no longer proxy those calls.
• Expect invalid variable coercion to return HTTP 400 unless the temporary compatibility option disables it.
• Remove landing-page precomputedNonce.
• Add DOM libraries explicitly to integration-test TypeScript projects that rely on them.

Read server.md for the required GraphQL.js alpha/protocol pairing, legacy executor setup, coercion and validation limits, and standalone request hardening.

Apollo Router 2

• Materialize cross-major YAML upgrades with router config upgrade; Router does not apply them during major-version startup.
• Replace the removed --schema flag with router config schema.
• Update context keys to their apollo::... names in plugins, Rhai, coprocessors, and telemetry selectors.
• Convert endpoint :name parameters to {name} and use named braced wildcards.
• Prefix body selector paths used for header propagation with $.
• Replace removed remote-supergraph polling with an explicit download-to-local-file workflow when hot reload is required.
• Expect busy Router instances to reject rather than queue work; rollout monitoring must include 503/504 responses and CPU.
• Move deprecated Router metrics and exporters to OpenTelemetry equivalents before upgrading dashboards.

Read router-migration-and-security.md and router-observability.md before a major upgrade.

Apollo Client quick reference

Query and mutation lifecycle

• Prefer useSuspenseFragment when a Suspense boundary should own incomplete-fragment loading.
• Do not add new useQuery or useLazyQuery onCompleted/onError logic; those callbacks are deprecated.
• In updateQuery, use second-argument previousData only when complete is true; return undefined to skip.
• Catch errors thrown by useMutation onCompleted through the returned promise.
• Replace useMutation.ignoreResults with client.mutate() when component result state is unwanted.
• Treat multipart query deduplication as lasting through the final chunk.

Client 4 result behavior

• Branch on dataState (empty, partial, streaming, complete) instead of inferring completeness from data alone.
• Remember notifyOnNetworkStatusChange defaults to true and unobserved queries are not tracked for active/all refetches.
• Put variables and context on useLazyQuery's execute call; option changes alone do not execute.
• Network and GraphQL failures obey errorPolicy; observable query failures normally arrive through next, not the observer's error callback.
• fetchMore defaults its own error policy to none, changes variable merging when a replacement query is supplied, and rejects cache-only use.
• Subscription observables are lazy and restartable; default subscription deduplication means a late subscriber misses the connection's initial value.

Client type precision

• Declare runtime defaultOptions under ApolloClient.DeclareDefaultOptions when types must reflect them.
• Choose TypeOverrides.signatureStyle: "modern" for document-inferred, default-aware APIs; use classic only as a migration bridge.
• Keep multi-client default declarations narrow because optional declarations also admit the runtime default.
• Error-policy-aware types specialize client.query, mutations, lazy execute, refetch, and fetchMore results.

Read client-data-and-cache.md for fragments, local fields, cache write extensions, partial arrays, mocks, and RefetchEventManager.

Apollo Server quick reference

Incremental delivery

• Initial Server 5 incremental delivery is pinned to GraphQL.js alpha.2 and the 2022-08-24 defer protocol.
• Server 5.1 moves to GraphQL.js alpha.9 and protocol v0.2.
• From Server 5.2, legacy protocol support requires both @yaacovcr/transform and an explicit legacyExperimentalExecuteIncrementally function.
• Match the client handler to the server protocol: an incorrect handler may reject or merge chunks incorrectly.

Standalone hardening

• Standalone accepts only UTF-8, UTF-16 LE/BE, and UTF-32 LE/BE request bodies.
• Standalone rejects a GET request carrying a non-JSON Content-Type; a headerless request remains subject to CSRF-preflight requirements.

Apollo Router quick reference

Security and HTTP behavior

• Keep introspection depth protection enabled unless a specific valid query requires otherwise.
• Treat invalid CORS as a startup error and configure per-origin policies explicitly.
• Configure JWT issuers and audiences as lists; validate string/array claim types and use per-JWKS allow_missing_exp only deliberately.
• Apply root authorization directives to individual fields when policy must remain subgraph-local.
• Expect strict input-object variable validation and GET content-type enforcement on current releases.
• Configure recursive-selection and downstream body-size limits rather than relying on unlimited input or response sizes.
• Header masking is active by default and spans logs, telemetry, coprocessors, and trace forwarding; copied body/context secrets need separate handling.

Caching and traffic

• Use GA response_cache, not the earlier preview namespace.
• Put response-cache TTL on the subgraph entry; subgraph Cache-Control: max-age overrides configured fallback TTL.
• Treat no-store and no-cache differently: the former can serve old data but forbids storage, while the latter needs unsupported revalidation before serving.
• Plan for cache-key regeneration after schema, entity-key, or expiry algorithm changes.
• Flush a Redis namespace when re-enabling an invalidation index that must cover entries written while disabled.
• Current capacity/rate-limit rejection is HTTP 503; do not retain alerts built around the brief 429 behavior.
• Set ignore_auth_context for subscription deduplication only when streams are truly non-personalized.

Read router-caching-and-traffic.md before changing Redis topology, cache invalidation, rate limits, subscriptions, or connection settings.

Connectors and extensions

• Current default Connector resolution uses v0.3; explicitly linked v0.2 schemas remain unchanged.
• In v0.4, primitive object-property values are literals; qualify data lookups explicitly.
• Use the separate connect-migrate CLI to classify v0.4 rewrites and manual cases.
• Replace connectors.subgraphs with connectors.sources and remove the deprecated v0.4 preview flag.
• Use stage-specific coprocessor URLs and selective response bodies when only part of a payload may leave the Router.
• In Rust plugins, emit metrics through the Router OpenTelemetry meter provider and update the one-time cloned service lifecycle.

Read router-connectors-and-extensions.md for Connector content types, mapping syntax, TLS, coprocessor stages, Rhai behavior, and Rust API replacements.

Execution and demand control

• Use query-planning cancellation measure mode before enforce; memory ceilings have platform/build constraints.
• Per-subgraph demand limits null only the skipped subgraph values while other work continues.
• Current actual-cost calculation includes intermediate subgraph work unless response_shape is selected.
• Enable result-coercion errors when clients should receive schema/value mismatches, including missing merged fields.
• Preserve entity-key and __typename dependencies when reasoning about deferred plan reduction.

Read router-execution-and-delivery.md for exact planning, cost, response, and error-path behavior.

Telemetry

• Generic OTEL_EXPORTER_OTLP_*_ENDPOINT variables now prevent Router startup; remove inherited values and configure exporters in Router YAML.
• Use response_errors and its aggregate selectors instead of capturing entire response bodies where possible.
• Size histogram buckets to cover configured timeouts; defaults stop at 10 seconds.
• Set cardinality limits knowingly, monitor the overflow metric, and remember overflow collapses into an otel_metric_overflow series.
• A view without explicit aggregation preserves a counter or gauge's native aggregation.
• Exporter-specific sampling cannot exceed the common trace sampler.
• http_client attributes attach to http_request and do not support conditions or static selectors.

Read router-observability.md before editing dashboards, selectors, custom instruments, exporters, or trace sampling.