Swift SDK

Give an iPhone, iPad or Mac app a working copy of an instance that reads offline, queues its writes and keeps itself current.

The Swift SDK is the marfa-swift package. An app built on it is a device: it keeps a working copy of part of an instance on the machine, reads it with or without a connection, and sends its writes when it reaches the server.

Use it for an app that must keep working offline. A script or a server needs no working copy: use the TypeScript SDK or the HTTP API. Build an app with Swift builds a SwiftUI app on the SDK, step by step.

Install

The SDK supports iOS 27 and macOS 27 and builds with Xcode 27 on a Mac with Apple silicon. In Xcode, choose File > Add Package Dependencies, enter https://github.com/withmarfa/marfa-swift, set Dependency Rule to Exact Version, and enter the version of the latest release. In a Package.swift:

Package.swift
.package(url: "https://github.com/withmarfa/marfa-swift", exact: "<latest release>"),
// in your target's dependencies:
.product(name: "Marfa", package: "marfa-swift"),
  • Update deliberately. Every release adds 0.0.1, whatever it changes, and until 0.1 any release can rename a call or add an enum case. Read the release notes, then change the version.
  • The SDK's enums are exhaustive. Switch over them without @unknown default, so a case a later release adds stops the build where it must be handled.
  • Each release carries the core of one Marfa release, already built, so the app needs no Rust toolchain. Update the SDK when you upgrade the instance.
  • The core is built for Apple silicon only. In the app target's build settings, set Excluded Architectures for Any iOS Simulator SDK to x86_64, or some simulator builds fail to link.

A first run

This signs the app in with the owner's approval, opens a working copy and fills it with the person's files. On a later launch the sign-in comes from the keychain and the copy opens with what it holds:

import Marfa

let serverURL = URL(string: "https://marfa.example.com")!
let auth = try Authorization(
    server: serverURL,
    client: .init(
        name: "Shoebox",
        redirect: URL(string: "com.example.shoebox:/signed-in"),
        scopes: ["core.file:read", "core.file:write"]),
    service: "com.example.shoebox")

let credential: Credential
if let kept = try auth.credential() {
    credential = kept
} else {
    credential = try await auth.signIn(presentingFrom: window)
}

let server = try Server(url: serverURL, credential: credential)
let store = URL.applicationSupportDirectory.appending(path: "marfa.sqlite")
let copy = try await WorkingCopy.open(store: store, server: server)
if try await copy.status().hydration == .never {
    _ = try await copy.hydrate(types: ["core.file"], tier: .library)
}

Sign-in and server calls covers Authorization, and Working copy opening and filling the copy.

Products

ProductHolds
MarfaThe SDK: the working copy, sign-in, server calls and folders. Add it to the app target.
MarfaAPIClient, for the operations the working copy doesn't make, such as registering a type. It includes MarfaTypes.
MarfaTypesThe server's wire types, generated from the API description, and marfaContractVersion.
MarfaTestingA fake working copy and a keychain and key store in memory. It compiles empty in a release build, so wrap its uses in #if DEBUG.
MarfaIconsTypeIcon, which draws a type's icon.
MarfaBrandIconsThe brand marks a type's icon can name. An app that doesn't add it ships none of the artwork.

What the SDK decides

  • Marfa decides what things mean: an item's name and preview, what a link points to, whether an edge is allowed, what a filter matches. The SDK passes on the answers of Marfa's core, so every app agrees.
  • The SDK does what every Swift app needs: keeping the copy in step, retrying with back-off, sorting errors into kinds, keeping keys, reading dates and drawing icons.
  • The app decides the rest: its screens, its words, and choices such as what to call an item with no name.

The rules behind the SDK are in the contract's device, queue and verdicts, stores and folder sync chapters. The source is in the marfa-swift repository.

On this page