Installation

Apollo iOS requires the latest Xcode, which can be installed from the Mac App Store.

Follow along with these steps (described in detail below) to use Apollo iOS in your app:

1. Install the Apollo framework into your project and link it to your application target
2. Add a schema file to your target directory
3. (optional) Install the Xcode add-ons to get syntax highlighting for your .graphql files
4. Create .graphql files with your queries or mutations and add them to your target
5. Add a code generation build step to your target
6. Build your target
7. Add the generated API file to your target

Installing the Apollo framework

You can install Apollo.framework into your project using any of the three major Cocoa ecosystem package managers: Swift Package Manager, CocoaPods, or Carthage.

1. Swift Package Manager Installation
2. CocoaPods Installation
3. Carthage Installation

Adding a schema file to your target directory

You'll have to copy or download a schema to your target's 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 introspection query. Conventionally this file is called schema.json.

Note that you need to add this in the folder where most of your code is, NOT in the same folder where the .xcodeproj and/or .xcworkspace are located. Here is a rough ASCII representation of what this should look like:

| - your_project_folder
    | your_project.xcodeproj
    | - your_target_folder
        | schema.json
        | AppDelegate.swift
        | ViewController.swift
        | etc...
    | - another_target_folder
        | etc...

NOTE: You can add this file someplace else, but if you do, you will need to update the relative paths in the scripts in the steps below.

Creating .graphql files with your queries or mutations

Apollo iOS will generate 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 .graphql next to .swift.

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.

NOTE: If you don't have pre-existing .graphql files in your file tree, create a very simple query and add it to a .graphql file in your file tree so that when you run the code generation build step, it actually finds something. If you don't, you'll get the error No operations or fragments found to generate code for.

Adding a code generation build step

Code generation uses your .graphql files to generate API code that will help you send queries, subscriptions, and mutations, as well as parse and cache responses. To run code generation as part of the Xcode build process, you need to create a build step that runs before "Compile Sources" to invoke a wrapper script.

The wrapper will call through to the included binaries and files that constitute the apollo command-line interface. This ensures that you can use our tooling without having to worry about NPM Version Hell?, and that the version of the framework you're using is compatible with the version of the codegen you're using.

The location of this wrapper script is slightly different based on how you've integrated Apollo into your project, but the first steps are the same everywhere:

1. On your application target's Build Phases settings tab, click the + icon and choose New Run Script Phase.
2. In the created Run Script, change its name to Generate Apollo GraphQL API
3. Drag this new run script just above Compile Sources in your list of Build Phases so that it executes before your code is compiled.
4. Add the contents of the appropriate run script for the package manager you're using:

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 script created above, and run the codegen.

Adding the generated API file to your target

Drag the generated API.swift file to your target.

Note that because Apollo iOS generates query-specific result types, API.swift will be mostly empty at this point unless you've already added some .graphql files with queries or mutations to your target directory.

Make sure to uncheck the "Copy Files If Needed" checkbox, since it should already be within your project's folder system. Then, make sure you've checked all the Targets the API file needs to be included in.

Previous: Fetching queries
Next: Introduction