RivetKit SwiftUI客户端：快速连接Rivet Actors构建iOS/macOS应用

rivetkit-client-swiftui by rivet-dev/skills

1,900 周安装量

8 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/rivet-dev/skills --skill rivetkit-client-swiftui

开发云服务

🇨🇳中文介绍

RivetKit SwiftUI 客户端

在构建使用 RivetKitSwiftUI 连接 Rivet Actors 的 SwiftUI 应用时使用此技能。

版本

RivetKit 版本：2.1.6

错误处理策略

默认倾向于快速失败行为。
除非绝对需要，否则避免使用宽泛的 do/catch。
如果使用了 catch 块，请显式处理错误，至少应记录该错误。

安装

添加 Swift 包依赖并导入 RivetKitSwiftUI：

// Package.swift
dependencies: [
    .package(url: "https://github.com/rivet-dev/rivetkit-swift", from: "2.0.0")
]

targets: [
    .target(
        name: "MyApp",
        dependencies: [
            .product(name: "RivetKitSwiftUI", package: "rivetkit-swift")
        ]
    )
]

RivetKitSwiftUI 重新导出了 RivetKitClient 和，因此单个导入即可覆盖两者。

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

最小客户端示例

import RivetKitSwiftUI
import SwiftUI

@main
struct HelloWorldApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .rivetKit(endpoint: "https://my-namespace:pk_...@api.rivet.dev")
        }
    }
}

import RivetKitSwiftUI
import SwiftUI

struct ContentView: View {
    @Actor("counter", key: ["my-counter"]) private var counter
    @State private var count = 0

    var body: some View {
        VStack(spacing: 16) {
            Text("\(count)")
                .font(.system(size: 64, weight: .bold, design: .rounded))

            Button("Increment") {
                counter.send("increment", 1)
            }
            .disabled(!counter.isConnected)
        }
        .task {
            count = (try? await counter.action("getCount")) ?? 0
        }
        .onActorEvent(counter, "newCount") { (newCount: Int) in
            count = newCount
        }
    }
}

@Actor 属性包装器始终使用获取或创建语义，并接受以下参数：

name （必需）
key 作为 String 或 [String] （必需）
params （可选连接参数）
createWithInput （可选创建输入）
createInRegion （可选创建提示）
enabled （切换连接生命周期）

import RivetKitSwiftUI
import SwiftUI

struct ConnParams: Encodable {
    let authToken: String
}

struct ChatView: View {
    @Actor(
        "chatRoom",
        key: ["general"],
        params: ConnParams(authToken: "jwt-token"),
        enabled: true
    ) private var chat

    var body: some View {
        Text("Chat: \(chat.connStatus.rawValue)")
    }
}

import RivetKitSwiftUI
import SwiftUI

struct CounterView: View {
    @Actor("counter", key: ["my-counter"]) private var counter
    @State private var count = 0
    @State private var name = ""

    var body: some View {
        VStack {
            Text("Count: \(count)")
            Text("Name: \(name)")

            Button("Fetch") {
                Task {
                    count = try await counter.action("getCount")
                    name = try await counter.action("rename", "new-name")
                }
            }

            Button("Increment") {
                counter.send("increment", 1)
            }
        }
    }
}

import RivetKitSwiftUI
import SwiftUI

struct GameView: View {
    @Actor("game", key: ["game-1"]) private var game
    @State private var count = 0
    @State private var isGameOver = false

    var body: some View {
        VStack {
            Text("Count: \(count)")
            if isGameOver {
                Text("Game Over!")
            }
        }
        .onActorEvent(game, "newCount") { (newCount: Int) in
            count = newCount
        }
        .onActorEvent(game, "gameOver") {
            isGameOver = true
        }
    }
}

import RivetKitSwiftUI
import SwiftUI

struct ChatView: View {
    @Actor("chatRoom", key: ["general"]) private var chat
    @State private var messages: [String] = []

    var body: some View {
        List(messages, id: \.self) { message in
            Text(message)
        }
        .task {
            for await message in chat.events("message", as: String.self) {
                messages.append(message)
            }
        }
    }
}

import RivetKitSwiftUI
import SwiftUI

struct StatusView: View {
    @Actor("counter", key: ["my-counter"]) private var counter
    @State private var count = 0

    var body: some View {
        VStack {
            Text("Status: \(counter.connStatus.rawValue)")

            if counter.connStatus == .connected {
                Text("Connected!")
                    .foregroundStyle(.green)
            }

            Button("Fetch via Handle") {
                Task {
                    if let handle = counter.handle {
                        count = try await handle.action("getCount", as: Int.self)
                    }
                }
            }
            .disabled(!counter.isConnected)
        }
    }
}

import RivetKitSwiftUI
import SwiftUI

struct UserView: View {
    @Actor("user", key: ["user-123"]) private var user
    @State private var errorMessage: String?
    @State private var username = ""

    var body: some View {
        VStack {
            TextField("Username", text: $username)

            Button("Update Username") {
                Task {
                    do {
                        let _: String = try await user.action("updateUsername", username)
                    } catch let error as ActorError {
                        errorMessage = "\(error.code): \(String(describing: error.metadata))"
                    }
                }
            }

            if let errorMessage {
                Text(errorMessage)
                    .foregroundStyle(.red)
            }
        }
        .onActorError(user) { error in
            errorMessage = "\(error.group).\(error.code): \(error.message)"
        }
    }
}

键唯一标识 Actor 实例。使用复合键（数组）进行分层寻址：

import RivetKitSwiftUI
import SwiftUI

struct OrgChatView: View {
    @Actor("chatRoom", key: ["org-acme", "general"]) private var room

    var body: some View {
        Text("Room: \(room.connStatus.rawValue)")
    }
}

当 userId 包含用户数据时，不要使用字符串插值（如 "org:\(userId)"）构建键。应改用数组以防止键注入攻击。

在视图树的根部调用一次 .rivetKit(endpoint:) 或 .rivetKit(client:)：

// 使用端点字符串（推荐用于大多数应用）
@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .rivetKit(endpoint: "https://my-namespace:pk_...@api.rivet.dev")
        }
    }
}

// 使用自定义客户端（用于高级配置）
@main
struct MyApp: App {
    private let client = RivetKitClient(
        config: try! ClientConfig(endpoint: "https://api.rivet.dev", token: "pk_...")
    )

    var body: some Scene {
        WindowGroup {
            ContentView()
                .rivetKit(client: client)
        }
    }
}

使用 .rivetKit(endpoint:) 时，客户端会按端点创建一次并缓存。使用 .rivetKit(client:) 时，请将客户端存储为 App 上的属性（而不是在 body 内部），因为 SwiftUI 可能会多次调用 body。

ClientConfig 从环境变量中读取可选值：

RIVET_NAMESPACE - 命名空间（也可以在端点 URL 中）
RIVET_TOKEN - 身份验证令牌（也可以在端点 URL 中）
RIVET_RUNNER - 运行器名称（默认为 "default"）

端点始终是必需的。没有默认端点。

端点支持 URL 身份验证语法：

https://namespace:token@api.rivet.dev

你也可以传递不带身份验证信息的端点，并单独提供 RIVET_NAMESPACE 和 RIVET_TOKEN。对于无服务器部署，将端点设置为应用的 /api/rivet URL。详情请参阅端点。

@Actor(name, key:, params:, createWithInput:, createInRegion:, enabled:) - 用于 Actor 连接的 SwiftUI 属性包装器

.rivetKit(endpoint:) - 使用端点 URL 配置客户端（创建缓存的客户端）
.rivetKit(client:) - 使用自定义实例配置客户端
.onActorEvent(actor, event) { ... } - 订阅 Actor 事件（支持 0–5 个类型化参数）
.onActorError(actor) { error in ... } - 处理 Actor 错误

actor.action(name, args..., as:) - 异步操作调用
actor.send(name, args...) - 发送后不管的操作
actor.events(name, as:) - 类型化事件的 AsyncStream
actor.connStatus - 当前连接状态
actor.isConnected - 是否已连接
actor.handle - 底层的 ActorHandle （可选）
actor.connection - 底层的 ActorConnection （可选）
actor.error - 最近的错误（可选）

ActorConnStatus - 连接状态枚举（.idle, .connecting, .connected, .disconnected, .disposed）
ActorError - 类型化的 Actor 错误，包含 group, code, message, metadata

需要更多关于客户端的信息？

如果你需要更多关于 Rivet Actors、注册表或服务器端 RivetKit 的信息，请添加主技能：

npx skills add rivet-dev/skills

然后使用 rivetkit 技能获取后端指导。

🇺🇸English

RivetKit SwiftUI Client

Use this skill when building SwiftUI apps that connect to Rivet Actors with RivetKitSwiftUI.

Version

RivetKit version: 2.1.6

Error Handling Policy

Prefer fail-fast behavior by default.
Avoid broad do/catch unless absolutely needed.
If a catch block is used, handle the error explicitly, at minimum by logging it.

Install

Add the Swift package dependency and import RivetKitSwiftUI:

// Package.swift
dependencies: [
    .package(url: "https://github.com/rivet-dev/rivetkit-swift", from: "2.0.0")
]

targets: [
    .target(
        name: "MyApp",
        dependencies: [
            .product(name: "RivetKitSwiftUI", package: "rivetkit-swift")
        ]
    )
]

RivetKitSwiftUI re-exports RivetKitClient and SwiftUI, so a single import covers both.

Minimal Client

import RivetKitSwiftUI
import SwiftUI

@main
struct HelloWorldApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .rivetKit(endpoint: "https://my-namespace:pk_...@api.rivet.dev")
        }
    }
}



import RivetKitSwiftUI
import SwiftUI

struct ContentView: View {
    @Actor("counter", key: ["my-counter"]) private var counter
    @State private var count = 0

    var body: some View {
        VStack(spacing: 16) {
            Text("\(count)")
                .font(.system(size: 64, weight: .bold, design: .rounded))

            Button("Increment") {
                counter.send("increment", 1)
            }
            .disabled(!counter.isConnected)
        }
        .task {
            count = (try? await counter.action("getCount")) ?? 0
        }
        .onActorEvent(counter, "newCount") { (newCount: Int) in
            count = newCount
        }
    }
}

Actor Options

The @Actor property wrapper always uses get-or-create semantics and accepts:

name (required)
key as String or [String] (required)
params (optional connection parameters)
createWithInput (optional creation input)
createInRegion (optional creation hint)
enabled (toggle connection lifecycle)

import RivetKitSwiftUI import SwiftUI

struct ConnParams: Encodable { let authToken: String }

struct ChatView: View { @Actor( "chatRoom", key: ["general"], params: ConnParams(authToken: "jwt-token"), enabled: true ) private var chat

Actions

import RivetKitSwiftUI
import SwiftUI

struct CounterView: View {
    @Actor("counter", key: ["my-counter"]) private var counter
    @State private var count = 0
    @State private var name = ""

    var body: some View {
        VStack {
            Text("Count: \(count)")
            Text("Name: \(name)")

            Button("Fetch") {
                Task {
                    count = try await counter.action("getCount")
                    name = try await counter.action("rename", "new-name")
                }
            }

            Button("Increment") {
                counter.send("increment", 1)
            }
        }
    }
}

Subscribing to Events

import RivetKitSwiftUI
import SwiftUI

struct GameView: View {
    @Actor("game", key: ["game-1"]) private var game
    @State private var count = 0
    @State private var isGameOver = false

    var body: some View {
        VStack {
            Text("Count: \(count)")
            if isGameOver {
                Text("Game Over!")
            }
        }
        .onActorEvent(game, "newCount") { (newCount: Int) in
            count = newCount
        }
        .onActorEvent(game, "gameOver") {
            isGameOver = true
        }
    }
}

Async Event Streams

import RivetKitSwiftUI
import SwiftUI

struct ChatView: View {
    @Actor("chatRoom", key: ["general"]) private var chat
    @State private var messages: [String] = []

    var body: some View {
        List(messages, id: \.self) { message in
            Text(message)
        }
        .task {
            for await message in chat.events("message", as: String.self) {
                messages.append(message)
            }
        }
    }
}

Connection Status

import RivetKitSwiftUI
import SwiftUI

struct StatusView: View {
    @Actor("counter", key: ["my-counter"]) private var counter
    @State private var count = 0

    var body: some View {
        VStack {
            Text("Status: \(counter.connStatus.rawValue)")

            if counter.connStatus == .connected {
                Text("Connected!")
                    .foregroundStyle(.green)
            }

            Button("Fetch via Handle") {
                Task {
                    if let handle = counter.handle {
                        count = try await handle.action("getCount", as: Int.self)
                    }
                }
            }
            .disabled(!counter.isConnected)
        }
    }
}

Error Handling

import RivetKitSwiftUI
import SwiftUI

struct UserView: View {
    @Actor("user", key: ["user-123"]) private var user
    @State private var errorMessage: String?
    @State private var username = ""

    var body: some View {
        VStack {
            TextField("Username", text: $username)

            Button("Update Username") {
                Task {
                    do {
                        let _: String = try await user.action("updateUsername", username)
                    } catch let error as ActorError {
                        errorMessage = "\(error.code): \(String(describing: error.metadata))"
                    }
                }
            }

            if let errorMessage {
                Text(errorMessage)
                    .foregroundStyle(.red)
            }
        }
        .onActorError(user) { error in
            errorMessage = "\(error.group).\(error.code): \(error.message)"
        }
    }
}

Concepts

Keys

Keys uniquely identify actor instances. Use compound keys (arrays) for hierarchical addressing:

import RivetKitSwiftUI
import SwiftUI

struct OrgChatView: View {
    @Actor("chatRoom", key: ["org-acme", "general"]) private var room

    var body: some View {
        Text("Room: \(room.connStatus.rawValue)")
    }
}

Don't build keys with string interpolation like "org:\(userId)" when userId contains user data. Use arrays instead to prevent key injection attacks.

Environment Configuration

Call .rivetKit(endpoint:) or .rivetKit(client:) once at the root of your view tree:

// With endpoint string (recommended for most apps)
@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .rivetKit(endpoint: "https://my-namespace:pk_...@api.rivet.dev")
        }
    }
}

// With custom client (for advanced configuration)
@main
struct MyApp: App {
    private let client = RivetKitClient(
        config: try! ClientConfig(endpoint: "https://api.rivet.dev", token: "pk_...")
    )

    var body: some Scene {
        WindowGroup {
            ContentView()
                .rivetKit(client: client)
        }
    }
}

When using .rivetKit(endpoint:), the client is created once and cached per endpoint. When using .rivetKit(client:), store the client as a property on App (not inside body) since SwiftUI can call body multiple times.

Environment Variables

ClientConfig reads optional values from environment variables:

RIVET_NAMESPACE - Namespace (can also be in endpoint URL)
RIVET_TOKEN - Authentication token (can also be in endpoint URL)
RIVET_RUNNER - Runner name (defaults to "default")

The endpoint is always required. There is no default endpoint.

Endpoint Format

Endpoints support URL auth syntax:

https://namespace:token@api.rivet.dev

You can also pass the endpoint without auth and provide RIVET_NAMESPACE and RIVET_TOKEN separately. For serverless deployments, set the endpoint to your app's /api/rivet URL. See Endpoints for details.

API Reference

Property Wrapper

@Actor(name, key:, params:, createWithInput:, createInRegion:, enabled:) - SwiftUI property wrapper for actor connections

View Modifiers

.rivetKit(endpoint:) - Configure client with an endpoint URL (creates cached client)
.rivetKit(client:) - Configure client with a custom instance
.onActorEvent(actor, event) { ... } - Subscribe to actor events (supports 0–5 typed args)
.onActorError(actor) { error in ... } - Handle actor errors

ActorObservable

actor.action(name, args..., as:) - Async action call
actor.send(name, args...) - Fire-and-forget action
actor.events(name, as:) - AsyncStream of typed events
actor.connStatus - Current connection status
actor.isConnected - Whether connected
actor.handle - Underlying ActorHandle (optional)
actor.connection - Underlying ActorConnection (optional)
actor.error - Most recent error (optional)

Types

ActorConnStatus - Connection status enum (.idle, .connecting, .connected, .disconnected, .disposed)
ActorError - Typed actor errors with group, code, message, metadata

Need More Than the Client?

If you need more about Rivet Actors, registries, or server-side RivetKit, add the main skill:

npx skills add rivet-dev/skills

Then use the rivetkit skill for backend guidance.

Weekly Installs

1.9K

Repository

rivet-dev/skills

GitHub Stars

First Seen

Jan 26, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

github-copilot1.9K

codex1.1K

gemini-cli1.1K

opencode1.1K

antigravity1.1K

claude-code1.1K

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

102,200 周安装

var body: some View {
    Text("Chat: \(chat.connStatus.rawValue)")
}

RivetKit SwiftUI客户端：快速连接Rivet Actors构建iOS/macOS应用

🇨🇳中文介绍

RivetKit SwiftUI 客户端

版本

错误处理策略

安装

相关 Skills

最小客户端示例

Actor 选项

操作

订阅事件

异步事件流

连接状态

错误处理

概念

键

环境配置

环境变量

端点格式

API 参考

属性包装器

视图修饰符

ActorObservable

类型

需要更多关于客户端的信息？

🇺🇸English

RivetKit SwiftUI Client

Version

Error Handling Policy

Install

Minimal Client

Actor Options

Actions

Subscribing to Events

Async Event Streams

Connection Status

Error Handling

Concepts

Keys

Environment Configuration

Environment Variables

Endpoint Format

API Reference

Property Wrapper

View Modifiers

ActorObservable

Types

Need More Than the Client?

最新 Skills