Apollo iOS requires Xcode 8, which you can install from the Mac App Store.
Follow along with these steps (described in detail below) to use Apollo iOS in your app:
- Install the Apollo framework into your project and link it to your application target
apollo-codegenglobally through npm
- Add a code generation build step to your target
- Add a schema file to your target directory
- Build your target
- Add the generated API file to your target
- Install the Xcode add-ons to get syntax highlighting for your
.graphqlfiles with your queries or mutations and add them to your target
Installing the Apollo framework
You can install
Apollo.framework into your project using Carthage, CocoaPods, or by manually integrating it with Xcode.
github "apollostack/apollo-ios"to your Cartfile.
Drag and drop
Carthage/Build/iOSfolder to the “Linked Frameworks and Libraries” section of your application targets’ “General” settings tab.
On your application targets’ “Build Phases” settings tab, click the “+” icon and choose “New Run Script Phase”. Create a Run Script in which you specify your shell (ex:
bin/sh), add the following contents to the script area below the shell:
and add the paths to the frameworks you want to use under “Input Files”, e.g.:
This script works around an App Store submission bug triggered by universal binaries and ensures that necessary bitcode-related files and dSYMs are copied when archiving.
Because Apollo iOS has been written using Swift 3, it requires CocoaPods 1.1.0. You can install it using:
gem install cocoapods
pod "Apollo"to your Podfile.
.xcworkspacefile generated by CocoaPods to work on your project.
You can also manually clone the
apollo-ios repository, drag
Apollo.xcodeproj into your project or workspace, add a dependency on
Apollo.framework to your target.
You will have to install the
apollo-codegen command globally through npm:
npm install -g apollo-codegen
Adding a code generation build step
In order to invoke
apollo-codegen as part of the Xcode build process, create a build step that runs before “Compile Sources”.
- On your application targets’ “Build Phases” settings tab, click the “+” icon and choose “New Run Script Phase”. Create a Run Script, change its name to “Generate Apollo GraphQL API” and drag it just above “Compile Sources”. Then add the following contents to the script area below the shell:
APOLLO_FRAMEWORK_PATH="$(eval find $FRAMEWORK_SEARCH_PATHS -name "Apollo.framework" -maxdepth 1)"
The script above will invoke
apollo-codegen through the
check-and-run-apollo-codegen.sh wrapper script, which is actually contained in the
Apollo.framework bundle. The main reason for this is to check whether the version of
apollo-codegen installed on your system is compatible with the framework version installed in your project, and to warn you if it isn’t. Without this check, you could end up generating code that is incompatible with the runtime code contained in the framework.
Adding a schema file to your target directory
You’ll have to copy or download a schema to your target directory before generating code.
Apollo iOS requires a GraphQL schema file as input to the code generation process. A schema file is a JSON file that contains the results of an an introspection query. Conventionally this file is called
Build your target
At this point, you can try building your target in Xcode. This will verify that the
schema.json file can be found by the
apollo-codegen script created above, otherwise you’ll get a build error such as:
Cannot find GraphQL schema file […]
Adding the generated API file to your target
- Drag the generated
API.swiftfile to your target.
Note that because Apollo iOS generates query-specific result types,
Api.swiftwill be mostly empty at this point unless you’ve already added some
.graphqlfiles with queries or mutations to your target directory.
Installing the Xcode add-ons to get syntax highlighting
- Clone the
xcode-apollorepository to your computer.
- Close Xcode if it is currently running.
You may need to create these folders inside of
mkdir ~/Library/Developer/Xcode/Plug-ins ~/Library/Developer/Xcode/Specifications
cp -R GraphQL.ideplugin ~/Library/Developer/Xcode/Plug-ins
cp -R GraphQL.xclangspec ~/Library/Developer/Xcode/Specifications
You may receive a warning when you first start up Xcode after installing these add-ons.
.graphql files with your queries or mutations
Apollo iOS generates code from queries and mutations contained in
.graphql files in your target.
A useful convention is to colocate queries, mutations or fragments with the Swift code that uses them by creating
<name>.graphql next to
If you have the Xcode add-ons installed, you can use the Xcode companion view to show a
.swift file and the corresponding
.graphql file side by side.