Setting Up Your Xcode Project

Create a New Project #

1. Open Xcode and select "Create New Project" from the welcome screen
2. Under the iOS tab, select App and click Next
3. Fill in:
   • Product Name: GitHubExplorer
   • Team: Your personal team (or None)
   • Organization Identifier: com.yourname
   • Interface: SwiftUI
   • Language: Swift
4. Click Next, choose a save location, and click Create

Planned Project Structure #

As we progress through the tutorial, we will build up this structure:

GitHubExplorer/
├── GitHubExplorerApp.swift          ← App entry point
├── ContentView.swift                ← Main tab view
├── Config/
│   └── Secrets.swift                ← Token storage (gitignored!)
├── Network/
│   ├── Network.swift                ← ApolloClient singleton
│   └── AuthInterceptor.swift        ← Adds auth header to requests
├── GraphQL/
│   ├── schema.graphqls              ← Downloaded GitHub schema
│   ├── ViewerProfile.graphql        ← Query: current user profile
│   ├── SearchRepositories.graphql   ← Query: search repos
│   ├── RepositoryDetail.graphql     ← Query: single repo details
│   ├── AddStar.graphql              ← Mutation: star a repo
│   ├── RemoveStar.graphql           ← Mutation: unstar a repo
│   ├── CreateIssue.graphql          ← Mutation: create an issue
│   └── RepositoryFields.graphql     ← Fragment: reusable repo fields
├── ViewModels/
│   ├── ProfileViewModel.swift
│   ├── SearchViewModel.swift
│   └── RepositoryDetailViewModel.swift
├── Views/
│   ├── ProfileView.swift
│   ├── SearchView.swift
│   ├── RepositoryDetailView.swift
│   └── CreateIssueView.swift
└── GitHubGraphQLAPI/                ← Auto-generated by Apollo
    ├── Schema/
    └── Operations/

Do not create all these folders yet — we will add them step by step.

Create a Secrets File #

Create a new Swift file called Secrets.swift. This file will hold your GitHub token and must be added to your .gitignore.

// Secrets.swift
// ⚠️ DO NOT commit this file to Git!

enum Secrets {
    static let githubToken = "ghp_YOUR_TOKEN_HERE"
}

Add this to your .gitignore:

# Never commit secrets
Secrets.swift

---

Installing Apollo iOS via Swift Package Manager #

What is Apollo iOS? #

Apollo iOS is the industry-leading GraphQL client for Apple platforms (iOS, macOS, watchOS, tvOS, visionOS). It is open-source, written in Swift, and handles:

• Sending GraphQL queries and mutations to any spec-compliant server
• Code generation — turning .graphql files into type-safe Swift models
• Parsing JSON responses into those generated models (no manual Codable needed)
• Normalized caching — intelligently caching and deduplicating response data
• Custom request interceptors for authentication, logging, retry logic, etc.

— Add the Package #

1. In Xcode, go to File → Add Package Dependencies...
2. In the search bar, paste this URL:

   https://github.com/apollographql/apollo-ios.git
   

3. Xcode will find the apollo-ios package. For Dependency Rule, select "Up to Next Major Version" starting at 2.0.0
4. Click Add Package. Xcode will resolve the dependency.
5. On the library selection screen, check only Apollo. Make sure it targets GitHubExplorer.

⚠️ Critical: Do NOT select apollo-ios-cli. That is the code generation CLI. Linking it to your app target will cause build errors.

6. Click Add Package to finish.

Verify Installation #

Open ContentView.swift and add this import at the top:

import Apollo

Build your project (Cmd + B). If it succeeds, Apollo is installed correctly.

---

Installing the Apollo Codegen CLI #

What the CLI Does #

The Apollo Codegen CLI is a command-line tool that:

• Downloads schemas from any GraphQL endpoint via introspection
• Generates Swift code from your .graphql query/mutation/fragment files
• Validates your operations against the schema at build time

Install the CLI #

1. In Xcode's Project Navigator, right-click on your project name (the blue icon)
2. Look for the "Install CLI" plugin in the context menu. Click it.
3. A dialog asks for write access to your project directory. Click Allow.
4. Wait for Xcode to build the CLI (1–2 minutes the first time).

After completion, a file called apollo-ios-cli appears in your project root. This is a symbolic link to the compiled CLI.

Verify the CLI #

cd /path/to/GitHubExplorer
./apollo-ios-cli --version

You should see a version number like 2.x.x.

Troubleshooting: If you get "No such file or directory", clean Derived Data (Xcode → Settings → Locations → click arrow next to Derived Data → delete folder) and re-run the Install CLI plugin.

---

Downloading the GitHub GraphQL Schema #

Initialize the Codegen Configuration #

Open Terminal in your project root and run:

./apollo-ios-cli init \
  --schema-namespace GitHubGraphQLAPI \
  --module-type embeddedInTarget \
  --target-name GitHubExplorer

This creates apollo-codegen-config.json — the central configuration file.

What each flag means:

• --schema-namespace GitHubGraphQLAPI — All generated Swift types will live under this namespace
• --module-type embeddedInTarget — Generated code goes directly into your app target
• --target-name GitHubExplorer — The Xcode target name

Configure Schema Download #

Open apollo-codegen-config.json and make the following changes:

1. Update the input section to point to a graphql/ folder:

"input": {
  "operationSearchPaths": ["./graphql/**/*.graphql"],
  "schemaSearchPaths": ["./graphql/**/*.graphqls"]
},

2. Add a schemaDownload section (add this as a top-level sibling of "schemaNamespace"):

"schemaDownload": {
  "downloadMethod": {
    "introspection": {
      "endpointURL": "https://api.github.com/graphql",
      "httpMethod": {
        "POST": {}
      },
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  },
  "outputPath": "./graphql/schema.graphqls"
}

Important: Replace YOUR_TOKEN_HERE with your actual GitHub Personal Access Token. GitHub's GraphQL API requires authentication even for schema introspection.

Download the Schema #

mkdir -p graphql
./apollo-ios-cli fetch-schema

This sends an introspection query to GitHub's API and saves the entire schema to graphql/schema.graphqls.

The file will be large (the GitHub schema defines thousands of types). Open it and browse through — you will see types like Repository, User, Issue, PullRequest, and many more, each with their fields and relationships.

Tip: You do not need to understand the entire schema. Think of it as a dictionary — you look up what you need when you need it.

---