If you have ever hand-written networking code to talk to a backend, you know the pain. You read some documentation, design your request and response types, write the URL handling and JSON decoding, and eventually get something that seems to work. Then the API changes, the docs fall behind, a field gets renamed, and suddenly your app is silently failing in production.

gRPC removes most of that friction. Instead of treating server communication as a pile of HTTP endpoints and hand-rolled models, gRPC lets you define your API once, in a single contract, and generate the client and server code from it. With the release of gRPC Swift 2, this workflow has become genuinely idiomatic on Apple platforms and Linux, built around async/await and Swift 6 concurrency.

This article walks through what gRPC is, why it fits real-time apps so well, and how to use it in a Swift project from start to finish.

What is gRPC?

gRPC is a framework for making remote procedure calls.

The key mental shift is this: with a typical REST API, you think in terms of HTTP, like URLs, verbs such as GET and POST, status codes, and request bodies. With gRPC, you think in terms of functions with inputs and outputs. Calling the server feels like calling a local function, except the work happens on a remote machine.

A remote procedure call works like this:

1. The client builds a request message.
2. It sends that message to the server.
3. The server runs the function and produces a response message.
4. The response travels back to the client.

For example, a function to fetch a race schedule might be called listRaces. The client calls it with the number of races it wants, and the server returns the list. From the caller's perspective, it looks almost identical to invoking any other Swift method.

gRPC is not a niche tool. It runs deep inside large-scale infrastructure, including Apple's own services such as Private Cloud Compute, iCloud Keychain, Photos, and SharePlay file sharing, as well as inter-process communication in Apple's open source Containerization framework. The same library you would use in an iOS app is production-grade for backend systems.

The contract: Protocol Buffers

Most gRPC services describe their API using Protocol Buffers, usually shortened to Protobuf. This is the source of truth for the service. Because it is a neutral, cross-platform format, the same .proto file can generate a Swift client, a Go server, a Kotlin client, and so on. Everyone agrees on the same contract.

You define your service and its messages in a .proto file. Here is a small example for a racing app:

syntax = "proto3";

import "google/protobuf/timestamp.proto";

service SwiftKart {
  rpc ListRaces(ListRacesRequest) returns (ListRacesResponse);
}

message ListRacesRequest {
  int32 limit = 1;
}

message ListRacesResponse {
  repeated Race races = 1;
}

message Race {
  string name = 1;
  string location = 2;
  string championship = 3;
  int32 laps = 4;
  google.protobuf.Timestamp start_time = 5;
}

A few things worth noticing:

• The service block declares one or more RPCs. Here, ListRaces takes a ListRacesRequest and returns a ListRacesResponse.
• Every field has a unique field number (the = 1, = 2, and so on). These numbers, not the names, are what gets sent on the wire.
• repeated means a list, so repeated Race races is the equivalent of an array of races.
• Timestamp is one of Protobuf's "Well-Known Types," which is why it needs an import.

Why the field numbers matter

When gRPC sends a message, it serializes it to a compact binary representation and uses the field number rather than the field name to identify each value. The practical result is that a Protobuf message is roughly half the size of the equivalent JSON payload.

For a mobile app, smaller messages mean less data transferred and faster network calls, which matters most when the connection is poor. The same efficiency pays off in service-to-service communication on the backend.

Setting up gRPC Swift in your project

gRPC Swift 2 is distributed as a set of packages so you can pull in only what you need. The three you will most commonly use are:

• grpc-swift-2 provides the core runtime types and abstractions (GRPCCore).
• grpc-swift-nio-transport provides high-performance HTTP/2 networking built on SwiftNIO.
• grpc-swift-protobuf provides the build plugin that generates Swift code from your .proto files, and integrates with SwiftProtobuf.

In a Swift package, your dependencies look like this:

// swift-tools-version: 6.0
import PackageDescription

let package = Package(
    name: "SwiftKart",
    platforms: [.macOS("15.0"), .iOS("18.0")],
    dependencies: [
        .package(url: "https://github.com/grpc/grpc-swift-2.git", from: "2.0.0"),
        .package(url: "https://github.com/grpc/grpc-swift-nio-transport.git", from: "2.0.0"),
        .package(url: "https://github.com/grpc/grpc-swift-protobuf.git", from: "2.0.0"),
    ],
    targets: [
        .executableTarget(
            name: "SwiftKart",
            dependencies: [
                .product(name: "GRPCCore", package: "grpc-swift-2"),
                .product(name: "GRPCNIOTransportHTTP2", package: "grpc-swift-nio-transport"),
                .product(name: "GRPCProtobuf", package: "grpc-swift-protobuf"),
            ],
            plugins: [
                .plugin(name: "GRPCProtobufGenerator", package: "grpc-swift-protobuf")
            ]
        )
    ]
)

Note: gRPC Swift 2 requires Swift 6 and recent deployment targets (macOS 15+, iOS 18+, tvOS 18+, watchOS 11+, visionOS 2+).

Generating the code in Xcode

If you are working in an Xcode app project rather than a pure Swift package, the flow is:

1. Open the Project Editor, go to the Package Dependencies tab, and add grpc-swift-nio-transport and grpc-swift-protobuf.
2. Select your app target, open Build Phases, and expand Run Build Tool Plug-ins.
3. Add the GRPCProtobufGenerator plugin.
4. Drop your .proto file and a small JSON config file into the target.

The plugin scans the target for .proto files and generates the Swift code when you build. The JSON config controls what gets generated. For an app, you typically only need the messages and the client, not the server code:

{
  "generate": {
    "clients": true,
    "messages": true,
    "servers": false
  }
}

The first time you build, Xcode will ask you to trust the plugin. After that, your generated client and message types are available to import.

Making your first call

With the code generated, calling the service from a SwiftUI view looks like ordinary async Swift. Here is the shape of it:

import GRPCCore
import GRPCNIOTransportHTTP2
import SwiftProtobuf

// Inside a view, using a .task modifier:
.task {
    do {
        try await withGRPCClient(
            transport: .http2NIOPosix(
                target: .dns(host: "localhost", port: 8080),
                transportSecurity: .plaintext
            )
        ) { client in
            let kart = SwiftKart.Client(wrapping: client)
            let response = try await kart.listRaces(.with { $0.limit = 50 })
            self.races = response.races.map(Race.init)
        }
    } catch {
        print("Request failed: \(error)")
    }
}

What is happening here:

• withGRPCClient creates a client configured with a transport. The transport decides how the bytes move, in this case HTTP/2 over SwiftNIO, connecting to a local server.
• The raw client only knows about the server, not your specific service. Wrapping it in the generated SwiftKart.Client gives you the typed listRaces method.
• .with { $0.limit = 50 } is the SwiftProtobuf way of building a message and setting its fields.
• The response is mapped into the app's own model types.

And that is a complete round trip: a typed request out, a typed response back, with no manual URL building or JSON decoding anywhere.

Reuse the client, do not recreate it

One important detail: do not create a new gRPC client every time a view appears. Each client establishes its own connection, which adds latency. Instead, create a single client and share it, for example through the SwiftUI environment, so connections can be reused across views.

It is also good practice to disconnect the client when the app moves to the background to free up resources. A small "client manager" object that connects lazily and tears down on scenePhase changes handles this cleanly.

The real power: streaming

So far we have looked at a unary RPC, which is a single request and a single response, just like a normal function call. This is where gRPC's standout feature comes in: every RPC can also stream messages. That opens up three more call types beyond unary.

Think about a live kart race:

• Server streaming is a live text commentary feed. The client asks once, the server keeps pushing updates.
• Client streaming is each kart pushing its telemetry to the server continuously.
• Bidirectional streaming is the richest case. The client tells the server which events it cares about and can change that subscription at any time, while the server streams back the matching events.

Defining a streaming RPC

You mark a streaming parameter with the stream keyword in the .proto file:

service SwiftKart {
  rpc ListRaces(ListRacesRequest) returns (ListRacesResponse);

  rpc FollowRace(stream FollowRaceRequest) returns (stream FollowRaceResponse);
}

message FollowRaceRequest {
  string race_name = 1;
  repeated EventType events = 2;
}

enum EventType {
  EVENT_TYPE_UNSPECIFIED = 0;
  EVENT_TYPE_KART_LOCATIONS = 1;
  EVENT_TYPE_STANDINGS = 2;
}

message FollowRaceResponse {
  oneof payload {
    KartLocations locations = 1;
    Standings standings = 2;
  }
}

That oneof is worth calling out: it maps neatly onto a Swift enum with associated values. A FollowRaceResponse holds either kart locations or standings, and you switch over it on the client just like any Swift enum.

Consuming a bidirectional stream on the client

A bidirectional RPC gives you two closures: one for writing requests to the server, and one for reading responses. Here is the shape of consuming the live race feed in SwiftUI:

.task {
    do {
        try await manager.withClient { client in
            let kart = SwiftKart.Client(wrapping: client)

            try await kart.followRace { writer in
                // Send a request whenever the user's interests change.
                for await showLeaderboard in leaderboardStream {
                    var request = FollowRaceRequest.with {
                        $0.raceName = "Finite Loops"
                        $0.events = [.kartLocations]
                    }
                    if showLeaderboard {
                        request.events.append(.standings)
                    }
                    try await writer.write(request)
                }
            } onResponse: { responses in
                // Handle each event the server pushes back.
                for try await response in responses.messages {
                    handle(response)
                }
            }
        }
    } catch {
        print("Stream failed: \(error)")
    }
}

The two halves run concurrently. As the user toggles the leaderboard on and off, the client writes new request messages updating its subscription, and the server adjusts what it streams back in real time. The handle(response) helper switches over the oneof payload and updates the view, drawing kart positions on a map or refreshing the standings.

This is the core of a real-time experience: a single long-lived connection carrying a live, two-way conversation, with strongly typed messages on both ends.

Implementing the server side

The same .proto contract generates the server code too. Implementing a service means conforming to a generated protocol, with one method per RPC. For a unary RPC, that is just an async function:

import GRPCCore
import GRPCNIOTransportHTTP2

struct SwiftKartService: SwiftKart.SimpleServiceProtocol {
    func listRaces(
        request: ListRacesRequest,
        context: ServerContext
    ) async throws -> ListRacesResponse {
        let races = try await database.races(limit: Int(request.limit))
        return ListRacesResponse.with { $0.races = races }
    }
}

Starting the server is a matter of creating one with a transport and the services it should offer, then calling serve():

let server = GRPCServer(
    transport: .http2NIOPosix(
        address: .ipv4(host: "0.0.0.0", port: 8080),
        transportSecurity: .plaintext
    ),
    services: [SwiftKartService()]
)
try await server.serve()

Streaming RPCs on the server look a little different. The request parameter becomes an async sequence of incoming messages, and the response becomes a writer you push messages into. Handling two streams at once is a natural fit for a Swift task group: one task reads the client's evolving subscription, another follows the live race data and writes matching events back. When the request stream ends, you treat that as the signal to cancel the work and stop sending.

Deploying to the cloud

Because gRPC Swift runs on Linux, deploying a service is the standard container workflow. Most cloud providers (Google Cloud Run, AWS, Fly.io, and others) follow a similar pattern even if the exact commands differ.

The typical steps:

1. Write a Containerfile that builds the server in release mode. Use a multi-stage build: compile with the full swift:latest image, then copy just the resulting binary into a smaller swift:slim runtime image. This keeps the final image from carrying the entire Swift toolchain.
2. Publish the image to your provider's container registry.
3. Create a deployment. Make sure to enable HTTP/2, since gRPC depends on it.
4. Update the app to point at the deployed service's DNS name, and switch the transport security from plaintext to TLS.

That last change on the client is small but essential:

.http2NIOPosix(
    target: .dns(host: "your-service.example.run.app", port: 443),
    transportSecurity: .tls   // was .plaintext for local development
)

With TLS enabled and the host pointed at the cloud, the same app that talked to your Mac now talks to a service available to everyone.

Where to go next

gRPC Swift has plenty built in to take an app from prototype to production:

• Integration with other Swift server packages like Swift OTel (for distributed tracing via OpenTelemetry) and Swift Service Lifecycle.
• Advanced connection management, including custom transports, name resolvers, and client-side load balancing.
• A reflection service, health checks, and interceptors via the grpc-swift-extras package.

The fastest way to get comfortable is to prototype one slice of your app-to-server communication with gRPC and feel how the generated code removes the boilerplate. From there:

• Browse the tutorials and examples in the grpc-swift-2 repository.

• Since the project is open source, you can ask questions, improve docs, or propose features.