Prefire

クイックスタート · インストール · 使い方 · AI エージェント · 設定 · ドキュメント

🔥 Prefire とは？

Prefire は、すでに記述している #Preview ブロックを、追加コードなしでテスト、カタログ、画像に変換します。

📸 スナップショットテスト すべてのプレビューが、選択したデバイスでのスナップショットテストになります。ユーザーが気づく前に、見た目のリグレッションを検出できます。 仕組みを見る →

📚 Playbook 状態やレンダリング時間も確認できる、コンポーネントとユーザーストーリーのインタラクティブなカタログです。常に更新されるドキュメントとして利用できます。 Playbook を見る →

🤖 AI 対応レンダリング Claude Code、Cursor、Codex は MCP サーバーを通じて、ライトモードでもダークモードでも、あらゆる iPhone や iPad でプレビューをレンダリングできます。 設定する →

🤖 AI エージェントを使用していますか？ brew install barredewe/prefire/prefire を実行し、プロジェクトで claude mcp add prefire -- prefire mcp を実行します。エージェントは、Xcode Previews を使わずに、ライトモードでもダークモードでも、あらゆる iPhone や iPad で SwiftUI プレビューをレンダリングできます。セットアップ →

🚀 主な機能

• 🧠 スマートなプレビュー解析 — #Preview、@Previewable に対応
• 📸 スナップショットテスト — プレビューからテストを自動生成（iOS、tvOS、macOS）
• 📚 Playbook ビュー — インタラクティブなコンポーネントカタログを自動生成（iOS）
• 🏃 フロー対応 — 複数のプレビューステップからユーザーストーリーを作成
• 🤖 AI 対応 — prefire render と MCP サーバー を使って、エージェント向けにプレビューを PNG にレンダリング
• 🧩 UIKit + AppKit 対応 — UIView／UIViewController および NSView／NSViewController に対応
• ⚙️ SPM + Xcode プラグイン — CLI、Xcode のビルドフェーズ、CI で動作
• 🧠 高速キャッシュ — フィンガープリントベースの AST および本体キャッシュにより、重複作業を回避
• ✍️ Stencil テンプレート — 独自のテンプレート で出力をカスタマイズ

Prefire を選ぶ理由は？

• 🔥 時間を節約 - テストとドキュメントを自動生成
• 🔥 一貫性を維持 - プレビューとテストを常に同期
• 🔥 品質を向上 - ユーザーが気づく前に、見た目のリグレッションを検出
• 🔥 コラボレーションを促進 - 常に更新されるドキュメントをチームと共有

---

⚡ クイックスタート

📦 サンプルプロジェクトはこちら：Prefire のサンプル

1. プロジェクトに Prefire を追加する

// Package.swift
dependencies: [
    .package(url: "https://github.com/BarredEwe/Prefire.git", from: "6.3.0"),
    .package(url: "https://github.com/pointfreeco/swift-snapshot-testing", from: "1.18.0"),
],
.testTarget(
    dependencies: [
      .product(name: "Prefire", package: "Prefire"),
      .product(name: "SnapshotTesting", package: "swift-snapshot-testing"),
    ],
    plugins: [
        .plugin(name: "PrefireTestsPlugin", package: "Prefire")
    ]
)

2. #Preview を記述する

#Preview {
    Button("Submit")
}

3. テストを実行する

テストターゲットを実行するだけです 🚀 — Prefire がプレビューに基づいてスナップショットを自動生成します。

💡 テストターゲットが空でも、Prefire はビルド時にファイルとスナップショットコードを生成します。

---

📦 インストール

方法	手順
SPM プラグイン	Package.swift の PrefireTestsPlugin / PrefirePlaybookPlugin
Xcode ビルドツールプラグイン	PrefireTestsPlugin をテストターゲットのビルドフェーズに追加します
CLI	brew install barredewe/prefire/prefire
Mint（ベータ版）	mint install BarredEwe/Prefire
GitHub Actions / CI	上記のいずれかを使用します。トラブルシューティングを参照してください

手順ごとのセットアップ方法は、インストールガイドをご覧ください。

要件

• Swift 6.0 以降
• Xcode 16.0 以降
• iOS 14 以降、macOS 13 以降（macOS はスナップショットテストのみです。設定を参照してください）

---

🛠 使用方法

プレビューを選択する

Prefire はすべての #Preview を自動的に検出します。PreviewProvider の場合は、PrefireProvider プロトコルを追加します。

struct Text_Previews: PreviewProvider, PrefireProvider {
    static var previews: some View { ... }
}

.prefireIgnored() を使うと、プレビューを除外できます。

#Preview {
    Text("")
        .prefireIgnored()
}

オプトアウトではなくオプトインにするには、.prefire.yml で preview_default_enabled: false を設定し、対象のプレビューに .prefireEnabled() を指定します。

#Preview {
    Text("")
        .prefireEnabled()
}

スナップショットテスト

PrefireTestsPlugin はテストターゲットのビルド時に、DerivedData フォルダーへテストを生成します。通常どおりテストターゲットを実行してください。

単一のスナップショットのタイミングと精度を調整します。

#Preview {
    TestView()
        .snapshot(delay: 0.3, precision: 0.95, perceptualPrecision: 0.98)
}

読み込み中またはアニメーション中のプレビューでは、遅延時間を推測する代わりに待機します。

.snapshot(waitForIdle: true)                     // until nothing changes on screen
.snapshot(waitUntil: { viewModel.isLoaded })     // until a condition is true

待機の仕組み、制限事項、各修飾子の組み合わせについては、スナップショットのタイミングと精度をご覧ください。

スナップショットの比較には swift-snapshot-testing を使用します。

Playbook（デモ）ビュー

PlaybookView を使って、すべてのプレビューをインタラクティブなカタログとして表示します。

• isComponent: true はすべての View を一覧表示します
• isComponent: false は UserStory ごとにグループ化します

import Prefire 

struct ContentView: View {
    var body: some View {
        PlaybookView(isComponent: true, previewModels: PreviewModels.models)
    }
}

リリースビルドからプレビューと PreviewModels を除外する方法については、リリースビルドからプレビューを除外するをご覧ください。

フロー

.previewUserStory を使ってプレビューを 1 つの フロー に接続します。Playbook では、順番にまとめて表示されます。

static var previews: some View {
    PrefireView()
        .previewUserStory(.auth)
}

static var previews: some View {
    AuthView()
        .previewUserStory(.auth)
}

状態

プレビューに複数の View が含まれる場合は、それぞれの State を指定します。

static var previews: some View {
    TestView("Default")

    TestView("Loading")
        .previewState(.loading)
}

パラメーター化されたプレビュー

Prefire は、SwiftUI 標準のパラメーター化されたプレビューの各引数を、それぞれ独立したスナップショットと Playbook プレビューに展開します。

#Preview("TextView", traits: .sizeThatFitsLayout, arguments: ["- A", "- B", "- C"]) { suffix in
    Text("1 \(suffix)")
}

---

🧰 API

機能	修飾子
スナップショットに含める	.prefireEnabled()
スナップショットから除外する	.prefireIgnored()
フロー内でグループ化する	.previewUserStory(.auth)
UI の状態を指定する	.previewState(.error)
スナップショットをカスタマイズする	.snapshot(delay: 0.3, precision: 0.95)
プレビューが落ち着くまで待機する	.snapshot(waitForIdle: true, timeout: 2.0)
条件が満たされるまで待機する	.snapshot(waitUntil: { viewModel.isLoaded })
パラメーター化されたプレビュー	#Preview(..., arguments: values)

---

💡 CLI の使用方法

# Generate snapshot tests
prefire tests

# Generate playbook models
prefire playbook

その他のオプションについては、prefire tests --help または prefire playbook --help を実行してください。

---

🤖 AI エージェントに SwiftUI を見せる

Prefire はスナップショットテストでプレビューを新たにビルドし、選択したデバイスでレンダリングします。そのため、Xcode の外では安定して表示できない Xcode Previews と異なり、画像として AI エージェントに見せることができます。

# Render previews to PNG + JSON
prefire render "Sign in" --device "iPhone 16 Pro" --color-scheme dark

# An HTML board of the last render, grouped by user story
prefire board

.prefire.yml があるフォルダーから、エージェントに MCP サーバーを追加します。

エージェント	インストール
Claude Code	claude mcp add prefire -- prefire mcp、またはスキル付きプラグイン：/plugin marketplace add BarredEwe/Prefire、続けて/plugin install prefire@prefire
Cursor
Codex	codex mcp add prefire -- prefire mcp
VS Code	code --add-mcp '{"name":"prefire","command":"prefire","args":["mcp"]}'

エージェントは list_previews、render_previews、build_board を呼び出します。.prefire.yml の render_configuration でビルドするスキームを設定してください。AI ガイドを参照してください。Xcode 独自の RenderPreview を使わない理由は何でしょうか？Prefire は Xcode を起動する必要がなく、1 回のビルドで多数のプレビューをレンダリングでき、指定したデバイス、カラー スキーム、Dynamic Type で動作し、CI でも利用できます。

---

🗂 設定：.prefire.yml

test_configuration:
  target: MyApp

playbook_configuration:
  preview_default_enabled: true

すべてのオプションについては設定ガイドを参照してください。生成されるコードを変更するには、テンプレートを参照してください。

---

🧠 仕組み

1. 🔍 すべてのソースファイルを解析します — #Preview と PreviewProvider ブロック、および .prefireEnabled() / .prefireIgnored() モディファイアを見つけます
2. 📂 Types と PreviewBodies をキャッシュします — ファイルの変更日時と入力の SHA-256 をキーにするため、変更がなければ再解析されません
3. 🔢 スナップショットテストを生成します — Stencil テンプレートから、.prefire.yml の設定を反映して生成します
4. 📘 Playbook モデルを生成します — UserStory と State ごとにグループ化し、PreviewModels.generated.swift に出力します

---

🩺 トラブルシューティング

問題	解決方法
Playbook でプレビュー内の NavigationView が動作しない	Playbook の用途に合わせて、別のビューやレイアウトを使用してください
CI でプラグインが実行されない	defaults write com.apple.dt.Xcode IDESkipPackagePluginFingerprintValidatation -bool YES
Xcode がカスタムパスにテストを生成できない	プラグインのサンドボックスを無効にします：defaults write com.apple.dt.Xcode IDEPackageSupportDisablePluginExecutionSandbox -bool YES

---

🐱 作者によるその他の作品

Mewmori は、Mac のデスクトップに住むドット絵の猫です。 画面に表示されている内容を読み取り、それについて何かを話し、セッションをまたいであなたのことを覚えています。 2B モデルは llama.cpp を通じてマシン上で動作するため、画面のテキスト、チャット、記憶は Mac 上に保持されます。

Swift、AppKit + SwiftUI、29 MB。無料で、スキンのみ有料です。

🤝 貢献

貢献を歓迎します！開発環境のセットアップ、テスト、内部アーキテクチャについてはCONTRIBUTING.mdに記載されています。

⭐ スター履歴

Prefire で時間を節約できたら、スターを付けてください。他の iOS 開発者が見つけやすくなります。

📄 ライセンス

Prefire は Apache License 2.0 のもとで公開されています。詳細はLICENSEを参照してください。