Apollo Docs
/

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 CocoaPods, Carthage, or by manually integrating it with Xcode.

CocoaPods

  1. Because Apollo iOS has been written using Swift 5, you need to use version 1.7.0 or higher. You can install CocoaPods using:
gem install cocoapods
  1. Add pod "Apollo" to your Podfile.
  2. If you also want to use the ApolloSQLite framework, also add pod "Apollo/SQLite"
  3. If you also want to use the ApolloWebSocket framework, also add pod "Apollo/WebSocket"
  4. Run pod install.
  5. Use the .xcworkspace file generated by CocoaPods to work on your project.

Carthage

Since Carthage does not allow choosing which schemes in a repo to build, we've moved our dependencies to a Cartfile.private file so that those dependencies are not forced on people using only the Apollo framework and not either of our optional frameworks, ApolloSQLite or ApolloWebSocket.

This makes setup a hair more complicated if you are using those, but is a big help in preventing dependency conflicts if you're not.

  1. Add github "apollographql/apollo-ios" to your Cartfile.
  2. If you also plan on using the ApolloSQLite framework, you should also add github "stephencelis/SQLite.swift". You may want to lock it to the version specified in Cartfile.private to prevent dependency conflicts.
  3. If you also plan on using the ApolloWebSocket framework, you should also add github "daltoniam/Starscream". You may want to lock it to the version specified in Cartfile.private to prevent dependency conflicts.
  4. Run carthage update --platform ios (or --platform ios,macos to build both Mac and iOS). NOTE: There's an issue with Carthage that has been causing some frustration for folks trying to build for watch and tvOS - don't build those targets if you don't need to.
  5. Drag and drop Apollo.framework from the appropriate Carthage/Build/iOS or Carthage/Build/Mac folder to the Embedded Binaries section of your application target's General settings tab. This should also cause them to appear in the Linked Frameworks And Libraries section automatically.
  6. If you also plan on using the ApolloSQLite library, also drag ApolloSQLite.framework and SQLite.framework to this area as well.
  7. If you also plan on using the ApolloWebSocket library, also drag ApolloWebSocket.framework and Starscream.framework to this area as well.
  8. On your application target's 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:
/usr/local/bin/carthage copy-frameworks

and add the paths to the frameworks you want to use under Input Files, e.g.:

$(SRCROOT)/Carthage/Build/iOS/Apollo.framework

Again, if you're adding ApolloSQLite or ApolloWebSocket, please make sure to add the other frameworks you added as Input Files.

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.

Manual integration

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.

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 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.

[Optional] Installing the Xcode add-ons to get syntax highlighting

  1. Clone the xcode-apollo repository to your computer.
  2. Close Xcode if it is currently running.
  3. You may need to create these folders inside of ~/Library/Developer/Xcode:

mkdir ~/Library/Developer/Xcode/Plug-ins ~/Library/Developer/Xcode/Specifications

  1. Copy GraphQL.ideplugin to ~/Library/Developer/Xcode/Plug-ins.

cp -R GraphQL.ideplugin ~/Library/Developer/Xcode/Plug-ins

  1. Copy GraphQL.xclangspec to ~/Library/Developer/Xcode/Specifications.

cp -R GraphQL.xclangspec ~/Library/Developer/Xcode/Specifications

You may receive a warning the first time you start up Xcode after installing these add-ons - once you agree to load the plugin, you will no longer see this warning.

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 <name>.graphql next to <name>.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

In order to invoke apollo as part of the Xcode build process, create a build step that runs before "Compile Sources" to invoke apollo through the check-and-run-apollo-cli.sh wrapper script.

The main reason for calling the wrapper is to check whether the version of apollo 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.

The location of this wrapper script is slightly different based on how you've integrated Apollo into you 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 appropriate contents to the run script from the options below.

If you ARE integrating Apollo using CocoaPods

Our CocoaPods install includes the code-generation script as a file which will not be added to the framework. Since this is always installed in a consistent place, you can use the same path to it. Add the following to the Run Script:

SCRIPT_PATH="${PODS_ROOT}/Apollo/scripts"
cd "${SRCROOT}/${TARGET_NAME}"
"${SCRIPT_PATH}"/check-and-run-apollo-cli.sh codegen:generate --target=swift --includes=./**/*.graphql --localSchemaFile="schema.json" API.swift

If you are integrating Apollo using SPM + Xcode 11 [BETA]

NOTE: These instructions are as of Xcode 11, beta 4. Please file an issue if anything has changed in newer betas or in the final release!

If you're using Xcode 11, SPM will check out the appropriate build script along with the rest of the files. Add the following to your Run Script build phase:

# Go to the build root and go back up to where SPM keeps the apollo iOS framework checked out.
cd "${BUILD_ROOT}"
cd "../../SourcePackages/checkouts/apollo-ios/scripts"

APOLLO_SCRIPT_PATH="$(pwd)"

if [ -z "${APOLLO_SCRIPT_PATH}" ]; then
    echo "error: Couldn't find the CLI script in your checked out SPM packages; make sure to add the framework to your project."
    exit 1
fi

cd "${SRCROOT}/${TARGET_NAME}"
"${APOLLO_SCRIPT_PATH}"/check-and-run-apollo-cli.sh codegen:generate --target=swift --includes=./**/*.graphql --localSchemaFile="schema.json" API.swift

NOTE: If you try to use this with command line SPM, when you regenerate your xcodeproj this build script will get wiped out. We strongly recommend using Xcode 11's built-in SPM handling rather than the command line because of this.

If you're NOT integrating Apollo using CocoaPods

In this case, the check-and-run-apollo-cli.sh file is bundled into the framework. The procedures to call it are slightly different based on whether you're using an iOS or macOS target because of the way the frameworks are compiled.

📱 For an iOS target or a Cocoa Touch Framework, add the following to your Run Script build phase:

# Do some magic so we can make sure `FRAMEWORK_SEARCH_PATHS` works correctly when there's a space in the scheme or the folder name.
QUOTED_FRAMEWORK_SEARCH_PATHS=\"$(echo $FRAMEWORK_SEARCH_PATHS | tr -d '"' | sed -e 's/ \//" "\//g')\"

# Get the first result searching for the framework
APOLLO_FRAMEWORK_PATH="$(eval find ${QUOTED_FRAMEWORK_SEARCH_PATHS} -name "Apollo.framework" -maxdepth 1 -print | head -n 1)"

if [ -z "${APOLLO_FRAMEWORK_PATH}" ]; then
    echo "error: Couldn't find Apollo.framework in FRAMEWORK_SEARCH_PATHS; make sure to add the framework to your project."
    exit 1
fi

cd "${SRCROOT}/${TARGET_NAME}"
"${APOLLO_FRAMEWORK_PATH}"/check-and-run-apollo-cli.sh codegen:generate --target=swift --includes=./**/*.graphql --localSchemaFile="schema.json" API.swift

💻 For a macOS or a Cocoa Framework target, add the following to your Run Script build phase:

# Do some magic so we can make sure `FRAMEWORK_SEARCH_PATHS` works correctly when there's a space in the scheme or the folder name.
QUOTED_FRAMEWORK_SEARCH_PATHS=\"$(echo $FRAMEWORK_SEARCH_PATHS | tr -d '"' | sed -e 's/ \//" "\//g')\"

# Get the first result searching for the framework
APOLLO_FRAMEWORK_PATH="$(eval find ${QUOTED_FRAMEWORK_SEARCH_PATHS} -name "Apollo.framework" -maxdepth 1 -print | head -n 1)"

if [ -z "${APOLLO_FRAMEWORK_PATH}" ]; then
    echo "error: Couldn't find Apollo.framework in FRAMEWORK_SEARCH_PATHS; make sure to add the framework to your project."
    exit 1
fi

cd "${SRCROOT}/${TARGET_NAME}"
"${APOLLO_FRAMEWORK_PATH}"/Versions/Current/Resources/check-and-run-apollo-cli.sh codegen:generate --target=swift --includes=./**/*.graphql --localSchemaFile="schema.json" API.swift

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.

Troubleshooting

If you've installed apollo globally with NPM and the script still seems to be having trouble finding it, add the following to the beginning of your Run Script Build Phase:

source ~/.bash_profile

If you get this error:

Cannot find GraphQL schema file [...]

The script is not able to find your schema file - double check the path you've used.

If you get this error:

No operations or fragments found to generate code for.

If you don't have any .graphql files in your build tree, and you need to create at least .graphql file with a valid query.

If you get this error:

Ensure that there is only one instance of "graphql" in the node_modules directory. If different versions of "graphql" are the dependencies of other relied on modules, use "resolutions" to ensure only one version is installed.

Delete the node_modules folder in your source root and rebuild.

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.