Apollo iOS Guide

Apollo iOS is a strongly-typed GraphQL client for Apple platforms. It generates Swift types from your GraphQL operations and schema, and ships an async/await client, a normalized cache (in-memory or SQLite-backed), a pluggable interceptor-based HTTP transport that handles queries, mutations, and multipart subscriptions, and an optional WebSocket transport (

graphql-transport-ws

) that can carry any operation type.

Process

Follow this process when adding or working with Apollo iOS:

Confirm target platforms, GraphQL endpoint(s), and how the schema is sourced.
Add Apollo iOS via Swift Package Manager and install the
```
apollo-ios-cli
```
.
Link each target to the correct product (
```
Apollo
```
for targets using
```
ApolloClient
```
,
```
ApolloAPI
```
for targets that only read generated models).
Write
```
apollo-codegen-config.json
```
using the canonical default (
```
moduleType: swiftPackage
```
,
```
operations: relative
```
); deviate only when the project has a specific constraint.
Run codegen and wire it into the build.
Create a single shared
```
ApolloClient
```
and inject it via SwiftUI
```
Environment
```
.
Implement operations (queries, mutations, subscriptions) from
```
@Observable
```
view models.
Add interceptors for auth and logging.
When the first test that needs
```
Mock<Type>
```
is written, flip
```
output.testMocks
```
in
```
apollo-codegen-config.json
```
from
```
none
```
to
```
swiftPackage
```
(or
```
absolute
```
), regenerate, and link the mocks target to the test target.

Reference Files

Setup — Install the SDK and CLI, link the right product (
```
Apollo
```
/
```
ApolloAPI
```
/
```
ApolloSQLite
```
/
```
ApolloWebSocket
```
/
```
ApolloTestSupport
```
) to each target, generate the canonical
```
apollo-codegen-config.json
```
, download the schema, run initial codegen, initialize
```
ApolloClient
```
, wire it into SwiftUI.
Codegen — Full
```
apollo-codegen-config.json
```
reference:
```
schemaTypes.moduleType
```
(
```
swiftPackage
```
/
```
embeddedInTarget
```
/
```
other
```
) and
```
operations
```
(
```
relative
```
/
```
inSchemaModule
```
/
```
absolute
```
) with tradeoffs and fragment-sharing patterns, renaming generated types, test mocks, Swift 6 / MainActor flags, and why you should not auto-run codegen from an Xcode build phase.
Custom Scalars — Default behavior (generated as
```
typealias <Scalar> = String
```
), when to replace the default, conforming to
```
CustomScalarType
```
, and canonical patterns for
```
Date
```
,
```
URL
```
, and
```
Decimal
```
.
Operations — Queries, mutations, watchers, cache policies, error handling, and SwiftUI
```
@Observable
```
view-model patterns with async/await.
Caching — Choosing between in-memory and SQLite cache, declaring cache keys with the
```
@typePolicy
```
directive, programmatic cache keys as advanced fallback, watching the cache, manual reads/writes.
Interceptors — The four interceptor protocols, building a custom
```
InterceptorProvider
```
, auth token interceptor, logging, retry, APQ.
Subscriptions — Choosing between HTTP multipart and WebSocket transports,
```
SplitNetworkTransport
```
wiring,
```
connection_init
```
auth, pause/resume on scene phase, consuming subscriptions from SwiftUI.
Testing —
```
ApolloTestSupport
```
, generated
```
Mock<Type>
```
fixtures, the protocol-wrapper pattern for testable view models, integration testing with a fake
```
NetworkTransport
```
, testing watchers.

Scripts

list-apollo-ios-versions.sh — List published Apollo iOS tags. Use this to find the latest version before writing version-pinned SPM dependencies.

Key Rules

Use Apollo iOS v2+. v1.x and v0.x are legacy — do not target them for new work.
Install via Swift Package Manager. CocoaPods and Carthage are not the recommended distribution mechanism for apollo-ios.
Default the codegen config to
```
moduleType: swiftPackage
```
and
```
operations: relative
```
(see Setup). This shape works for single-target and multi-module apps alike. Deviate only when the project cannot use SPM or has specific fragment-sharing needs (see Codegen).
Name the generated schema module after the project, using the
```
<ProjectName>API
```
convention (e.g.
```
RocketReserverAPI
```
for a project called
```
RocketReserver
```
). Derive the project name from
```
Package.swift
```
/ the
```
.xcodeproj
```
/ the app product name — never ship the
```
MyAPI
```
placeholder. If the project name is not obvious, ask the user with
```
AskUserQuestion
```
.
Target linking is a per-target decision made as modules grow — there is no upfront decision to make. Link
```
Apollo
```
to targets using
```
ApolloClient
```
; link
```
ApolloAPI
```
to targets that only consume generated response models.
Keep
```
schema.graphqls
```
,
```
.graphql
```
operation files, and
```
apollo-codegen-config.json
```
in source control so builds are reproducible.
Regenerate code after every schema or
```
.graphql
```
operation change. Never hand-edit generated files.
Commit the generated Swift files to source control. Do not wire
```
apollo-ios-cli generate
```
into an Xcode Run Script build phase — it measurably slows compile times on every build. Regenerate manually or via a dedicated script alias.
Generate test mocks lazily. The canonical codegen config ships with
```
output.testMocks: { "none": {} }
```
. Flip it on (and regenerate) only when the first test that needs
```
Mock<Type>
```
is being written — see Testing.
Create a single shared
ApolloClient
per endpoint. Inject it via SwiftUI
```
Environment
```
; never construct a new client per request.
Prefer
```
@typePolicy
```
schema directives over programmatic cache key resolution when declaring cache keys for types.
Put auth (attach token + refresh on 401 + retry) in a single
```
GraphQLInterceptor
```
. Attach via
```
request.additionalHeaders["Authorization"]
```
, detect 401 via
```
.mapErrors
```
, and trigger the retry by throwing
```
RequestChain.Retry(request:)
```
. Always pair with
```
MaxRetryInterceptor
```
as a safety-net cap. Reserve
```
HTTPInterceptor
```
for purely HTTP-scoped headers (
```
User-Agent
```
,
```
Accept-Encoding
```
). Never put auth or retry in view code.
In SwiftUI, scope fetch
```
Task
```
s to
```
.task { }
```
so they cancel automatically when the view disappears.
If Xcode MCP tools are available in the agent environment (typically exposed as
```
mcp__xcode__BuildProject
```
,
```
mcp__xcode__RunSomeTests
```
,
```
mcp__xcode__XcodeListNavigatorIssues
```
, etc.), prefer them over raw
```
xcodebuild
```
for building, running tests, and inspecting build issues after regenerating code.

apollo-ios

NPX Install

Tags

SKILL.md Content

Apollo iOS Guide

Process

Reference Files

Scripts

Key Rules