mcpField
C
caffeine-app

caffeine-app

github.com/dfinity開発39117 回インストール今日更新
リポジトリ

caffeine-app について

caffeine-app は、Caffeine のフルスタックアプリをゼロから構築するためのエージェントスキルです。Motoko バックエンドと React/Vite フロントエンドを使うプロジェクト向けに、構成やマニフェスト、CLI のビルド手順を案内し、言語の詳細は `writing-motoko` に委ねます。

主な機能

  1. 01Caffeine プロジェクト構成の作成
  2. 02ワークスペースと canister マニフェストの設定
  3. 03Motoko バックエンドとフロントエンド連携の説明
  4. 04caffeine CLI のビルドループ案内
  5. 05安定状態チェックとマイグレーション設定

活用シーン

  1. 01Caffeine アプリの新規作成
  2. 02`caffeine.toml` や `mops.toml` の修正
  3. 03`caffeine` のチェックとプレビュー構築

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/dfinity/icskills --skill caffeine-app

インストール後、Claude Code で/caffeine-appを入力して読み込まれたか確認します。

同梱ファイルreferences/frontend-template.md

詳細

Caffeine アプリ（ゼロから構築）

Caffeine（caffeine.ai）は、Internet Computer 上でフルスタックアプリを構築してホストします。単一の Motoko バックエンド canister と、アセット canister として配信される React/Vite フロントエンドで構成されます。このスキルでは、ゼロからビルド可能な Caffeine アプリを作成できるよう、正確な プロジェクト構成とCLI のビルドループを説明します。

このスキルが扱うのは、プロジェクト構成とビルドワークフローです。Motoko 言語そのものは扱いません。 バックエンドコードを書く、または編集する前に、writing-motoko スキルを取得し、その指示に従ってください：https://skills.internetcomputer.org/skills/writing-motoko/SKILL.md。このスキルは、アクター構文、安定状態、`mo:core`、コンパイラーエラーについての規範となるものです。このスキルでは、最小限の空のアクターと、その配置場所だけを説明します。

このスキルを使う場面

  • 新しい Caffeine アプリまたは caffeine.ai プロジェクトをゼロから作成・スキャフォールドする場合。
  • caffeine.toml（ワークスペースまたは canister マニフェスト）や mops.toml を作成・修正する場合。
  • caffeine CLI の一連の操作を実行する場合：auth login、doctor、install、check、preview。

Motoko 言語の詳細には使用しないでください（writing-motoko を使用してください）。また、IC／dfx／icp による直接デプロイにも使用しないでください（icp-cli を使用してください）。Caffeine アプリの構築とデプロイには caffeine CLI と caffeine.ai のウェブアプリを使用し、dfx は使用しません。

重要な事実

  • caffeine init／caffeine new はありません。 「ゼロから」とは、このスキルに記載されているファイルを手作業で作成し、その後ビルドループを実行することです。（caffeine projects clone <id> は既存のクラウドプロジェクトをダウンロードするだけで、新規プロジェクトを作成するものではありません。）
  • バックエンド canister は必ず 1 つだけで、名前は backend にする必要があります。 mops.toml では単一の [canisters.backend] を宣言します。
  • フロントエンドとバックエンドのバインディングファイルは自動生成され、手書きしません。 src/frontend/src/backend.ts と src/frontend/src/declarations/ は、ビルド中に caffeine-bindgen によって生成されます。編集しても意味はなく、上書きされます。
  • ライブ URL へのデプロイは CLI ではなく、caffeine.ai のウェブアプリで行います。 CLI でできるのは、ビルド済みのドラフトを作成するところまでです（caffeine preview --build。クラウドの project.id が必要です。ビルドループを参照してください）。caffeine deploy／publish コマンドはありません。

前提条件（一度だけ実行）

# Install the CLI (public npm package). The binary is `caffeine`.
npm install -g @caffeineai/cli

# Authenticate against caffeine.ai (opens a browser; use --device on headless hosts).
caffeine auth login
caffeine auth status

# Check the environment: Node, pnpm, mops, caffeine-bindgen, that you are logged in,
# and that the Caffeine API is reachable (installs/repairs what it can).
caffeine doctor --fix

グローバルインストールが望ましくない場合や、インストールに失敗した場合は、すべての caffeine コマンドの前に npx -y @caffeineai/cli@latest を付けて実行してください。例：npx -y @caffeineai/cli@latest auth status。

caffeine doctor --fix は Node.js、pnpm、mops、caffeine-bindgen を確認し、ログイン状態と Caffeine API への接続を検証して、可能なものをインストールまたは修復します。ただし、Motoko コンパイラー（moc）やリンター（lintoko）はインストールしません。mops は、最初の mops install またはビルド時に、mops.toml の [toolchain] のバージョン指定に従ってこれらを自動取得します。dfx は Caffeine のビルドには含まれません。

プロジェクト構成

Caffeine アプリは、ルートマニフェストと 2 つの canister を含む pnpm ワークスペースです。次の構成をそのまま作成してください（ファイルの内容は以下を参照）：

my-app/
├── .old/src/backend/dist/
│   └── backend.most           # stable-signature baseline — seed with an empty actor (see below)
├── caffeine.toml              # root workspace manifest — MUST contain [workspace]
├── mops.toml                  # Motoko build config — ONE per project, at the root
├── package.json               # pnpm workspace root + the `bindgen` script
├── pnpm-workspace.yaml         # declares src/**/* as workspace packages
├── tsconfig.json               # root TS config
└── src/
    ├── backend/                # the single Motoko canister, named "backend"
    │   ├── caffeine.toml        #   canister manifest: type = "motoko"
    │   ├── main.mo              #   actor entry point (write with the `writing-motoko` skill)
    │   └── migrations/          #   enhanced-migration chain (see the `mops.toml` notes)
    │       └── 00000000.mo      #   the no-op first migration
    └── frontend/               # the assets canister (React + Vite)
        ├── caffeine.toml        #   canister manifest: type = "assets"
        ├── package.json         #   frontend deps + scripts (see references/frontend-template.md)
        ├── vite.config.js       #   (see references/frontend-template.md)
        ├── tsconfig.json        #   (see references/frontend-template.md)
        ├── biome.json           #   (see references/frontend-template.md)
        ├── tailwind.config.js   #   (see references/frontend-template.md)
        ├── postcss.config.js    #   (see references/frontend-template.md)
        ├── index.html
        ├── env.json             #   runtime config — copied into dist/ on build
        └── src/
            ├── main.tsx          #   React entry (providers)
            ├── App.tsx
            ├── index.css
            ├── backend.ts        #   GENERATED by caffeine-bindgen — do NOT edit
            └── declarations/     #   GENERATED by caffeine-bindgen — do NOT edit

以下にインラインで示すのは、ルートマニフェスト、2 つの canister マニフェスト、mops.toml、main.mo、および小規模なルート設定ファイルのみです。フロントエンドの定型ファイル一式（package.json、vite.config.js、Tailwind／PostCSS／Biome の設定、index.html、env.json、main.tsx、ひな形の App.tsx）は references/frontend-template.md にあります。フロントエンドを作成する際に参照してください。

マニフェスト

ルートの caffeine.toml — ワークスペース

ルートマニフェストには、[workspace] セクションを必ず含めてください。このセクションによってワークスペースのルートとして認識されます。これがない場合、CLI はこのファイルを通常の canister マニフェストとして扱い、検出に失敗します。

manifest_version = "0.1.0"

[project]
name = "My App"
# id is assigned by the cloud after your first `caffeine preview`/create — omit it for
# a brand-new local project; the CLI fills it in.

[workspace]
include = [ "src/**" ]

# Build the backend before the frontend, because the frontend imports generated
# bindings produced from the backend's Candid interface.
[canisters.frontend]
depends_on = [ "backend" ]

[workspace].include は、CLI がネストされた canister マニフェストを検索するグロブのリストです。src/** によって、src/backend/caffeine.toml と src/frontend/caffeine.toml が見つかります。

src/backend/caffeine.toml — Motoko キャニスター
manifest_version = "0.1.0"

[project]
name = "backend"
type = "motoko"
main = "main.mo"

[build]
commands = ["mops build", "pnpm bindgen"]
out = "dist"

[check]
commands = ["mops check"]

[check.fix]
commands = ["mops check --fix"]

[build].commands は順番に実行されます。mops build が main.mo を Wasm と Candid にコンパイルし、続いて（ルートの package.json で定義されている）pnpm bindgen がその Candid からフロントエンドの TypeScript クライアントを生成します。caffeine check --fix は [check.fix].commands を実行します。

src/frontend/caffeine.toml — アセットキャニスター
manifest_version = "0.1.0"

[project]
name = "frontend"
type = "assets"

[build]
commands = ["pnpm build"]
out = "dist"

[check]
commands = ["pnpm typecheck", "pnpm check"]

[check.fix]
commands = ["pnpm typecheck", "pnpm fix"]
mops.toml — Motoko のビルド設定（プロジェクトごとに 1 つ、ルートに配置）

[canisters.backend] は必ず 1 つだけです。caffeine preview が確認するのは、変わることのない構造上の要素だけです。具体的には、単一の [canisters.backend]、パスが示され、skipIfMissing がない [canisters.backend.check-stable]、および [build] outputDir = "src/backend/dist" です。それ以外のすべて、つまりツールチェーンのバージョン、[moc] のフラグと -E／-W／-A 診断コード、依存関係の一覧は、Caffeine テンプレートが随時更新する現在のスナップショットです。詳しくは、下記の「バージョンと依存関係の変遷」を参照してください。

[package]
name = "backend"
version = "0.1.0"

[build]
outputDir = "src/backend/dist"
args = ["--release"]
check-wasm = true

[canisters.backend]
main = "src/backend/main.mo"

[canisters.backend.check-stable]
path = ".old/src/backend/dist/backend.most"

[toolchain]
moc = "2.0.0"
lintoko = "0.12.0"

[lint]
extends = true

[moc]
args = [
  "--implicit-package=core",
  "-no-check-ir",
  "-E=M0254",
  "-W=M0235,M0223,M0236,M0237",
  "-A=M0241"
]

[dependencies]
core = "2.6.1"
ic = "4.2.0"
caffeineai-lints = "0.1.0"
caffeineai-oql = "0.8.0"

[canisters.backend.migrations]
chain = "src/backend/migrations"
check-limit = 1

注意事項：

  • 新規プロジェクトでは moc 2 を使用します。 moc 2 では、修飾子のない actor は永続的であり、persistent キーワードは警告 M0217 を発生させるだけです。古いガイドでは [moc] args に --default-persistent-actors や --generate-view-queries を追加していますが、これらは moc 1.x のフラグで、moc 2.0 では削除されており、指定するとコンパイルのたびに unknown option で失敗します。切り替え前にクローンしたプロジェクトでは、moc 1.x に固定されたまま --default-persistent-actors を使用している場合があります。そのようなプロジェクトは、固定されたバージョンのままにしてください。

  • check-stable は .old/src/backend/dist/backend.most を指します。これは、最後にデプロイしたバックエンドの安定シグネチャのスナップショットです。caffeine check は安定状態をこれと比較し、caffeine projects clone はクラウドからこれを復元します。.old/ は削除しないでください。一から作成するプロジェクトでは、Caffeine テンプレートと同様に、空のアクターを使ってこのファイルを用意する必要があります。用意しないと、caffeine check は次のエラーで失敗します。

    // Version: 1.0.0
actor {};

    代わりに skipIfMissing = true を設定しないでください。mops では非推奨となっており、スキップされたチェックはデプロイ時になって初めて失敗するため、caffeine preview で拒否されます。

  • [canisters.backend.migrations] は拡張マイグレーションを有効にします。src/backend/migrations/ 内の各 .mo ファイルは、名前順に、直前の安定状態を次の状態に変換する 1 つのステップとして実行されます。新規プロジェクトには、writing-motoko スキルが作成する YYYYMMDD_HHMMSS.mo ファイルより先に並ぶ、何もしない 00000000.mo が用意されています。

    module {
  public type OldActor = {};
  public type NewActor = {};

  public func migration(_ : OldActor) : NewActor {
    {};
  };
};

    デプロイ後のマイグレーションは、編集も削除もしないでください。

  • core は mo:core 標準ライブラリです。非推奨の mo:base ではなく、必ず mo:core を使用してください。詳しくは writing-motoko スキルを参照してください。caffeineai-oql は、初期状態の main.mo に含まれている Expose ミックスインを提供します（下記参照）。

  • ic は IC 管理キャニスターの型と呼び出し（mo:ic/Types、mo:ic/Call）を提供します。import ... "ic:aaaaa-aa" の代わりに使用してください。この形式は .did ファイルを含む --actor-idl ディレクトリがないと解決できませんが、Caffeine プロジェクトには現在そのようなディレクトリはありません。

バージョンと依存関係の変遷。 [toolchain] のバージョン、[moc] の -E／-W／-A コード、フロントエンドの依存関係セットはテンプレートによって管理され、時間とともに変わります（例：@dfinity/* から @icp-sdk/* への移行、moc／core の更新）。ここに記載されている値はスナップショットとして扱ってください。最新の値を確認するには、最近のプロジェクトを caffeine projects clone でクローンし、その mops.toml と src/frontend/package.json をコピーしてください。バージョンを問わず変わらないのは、ファイル構成、単一の backend キャニスター、シード済みのベースラインを使う check-stable、[build] outputDir、mo:core、および useActor(createActor) です。

package.json（ルート）— pnpm ワークスペースと bindgen スクリプト

bindgen スクリプトは、バックエンドの Candid からフロントエンドの TS クライアントを生成する橋渡しをします。バックエンドキャニスターの [build] ステップ（pnpm bindgen）から呼び出されます。

{
  "name": "@caffeine/template-app",
  "type": "module",
  "engines": {
    "node": ">=18.17.0",
    "pnpm": ">=7.0.0",
    "npm": "please use pnpm"
  },
  "scripts": {
    "build": "pnpm -r --if-present run build",
    "typecheck": "pnpm -r --if-present run typecheck",
    "check": "pnpm -r --if-present run check",
    "fix": "pnpm -r --if-present run fix",
    "bindgen": "caffeine-bindgen --did-file ./src/backend/dist/backend.did --out-dir ./src/frontend/src --actor-interface-file --force"
  },
  "devDependencies": {
    "sharp": "^0.34.4"
  }
}
pnpm-workspace.yaml
packages:
  - src/**/*
onlyBuiltDependencies:
  - esbuild
tsconfig.json（ルート）
{
  "compilerOptions": {
    "strict": true,
    "target": "ES2020",
    "experimentalDecorators": true,
    "strictPropertyInitialization": false,
    "moduleResolution": "node",
    "allowJs": true,
    "outDir": "HACK_BECAUSE_OF_ALLOW_JS"
  }
}
src/backend/main.mo — 初期バックエンド

標準テンプレートの初期状態の main.mo には、バックエンドのクエリインターフェースを公開する caffeineai-oql の Expose ミックスインが含まれています。アクターにはまだ安定状態がないため、最初のマイグレーションでは {} から {} へのマッピングが行われます。writing-motoko スキルに従って、アクター内に独自の関数を追加してください。

import Expose "mo:caffeineai-oql/Expose";

actor {
  include Expose({ entities = [] });
};

writing-motoko スキルを読み込まずに、これ以上 Motoko を記述しないでください。このスキルでは、永続アクター、安定型、mo:core、およびエージェントが誤って生成しがちなコンパイラーエラーの落とし穴を扱っています。

フロントエンド

このスキルに付属するリファレンスファイル — references/frontend-template.md。このファイルは SKILL.md と同じ場所（つまり …/skills/caffeine-app/references/frontend-template.md）にあります。これを取得し、そこからフロントエンドのファイルを作成してください。検証済みの package.json、Vite／Tailwind／Biome の設定、main.tsx、およびバックエンド呼び出しの useActor(createActor) の実例が記載されています。要点は次のとおりです。

  • エントリーポイント src/frontend/src/main.tsx では、アプリを InternetIdentityProvider（@caffeineai/core-infrastructure 提供）と TanStack の QueryClientProvider でラップします。
  • フロントエンドは、生成されたモジュール src/frontend/src/backend.ts（および src/frontend/src/declarations/）を介してバックエンドと通信します。このモジュールは、バックエンドの Candid に基づいて型付けされた createActor(...) ファクトリーをエクスポートします。これらを自分で記述する必要はありません。最初のビルド後に生成されます。@caffeineai/core-infrastructure の useActor(createActor) に createActor を渡してバックエンドを呼び出してください（同じパッケージには main.tsx で使う認証プロバイダーも含まれています）。アクター／設定／ストレージをつなぐコードを手書きする必要はありません。実例は references/frontend-template.md を参照してください。
  • env.json には実行時設定のプレースホルダー（backend_host、backend_canister_id、project_id、ii_derivation_origin、storage_gateway_url）が含まれており、ローカルではすべて "undefined" です。フロントエンドの build スクリプトはこれを dist/ にコピーします（cp env.json dist/）。Caffeine はアプリを配信する際に実際の値を注入します。env.json と copy:env の手順は残してください。

ビルドループ

プロジェクトのルートから実行します。順序が重要です。

# 1. Install dependencies. On a brand-new project, generate the pnpm lockfile FIRST
#    (first run only — see Common Pitfalls), then install the rest (pnpm + mops).
pnpm install
caffeine install

# 2. Write your backend in src/backend/main.mo using the `writing-motoko` skill, and your
#    frontend in src/frontend/src/.

# 3. Build: compiles the backend, then `pnpm bindgen` regenerates the frontend client
#    (src/frontend/src/backend.ts + declarations/), then the frontend `pnpm build` runs.
#    Run this BEFORE check, so the frontend has the generated ./backend to typecheck
#    against. Artifacts land in src/backend/dist + src/frontend/dist (no cloud / no id).
caffeine build

# 4. Lint + typecheck + auto-fix (runs each canister's [check.fix] commands:
#    backend `mops check --fix`, frontend `pnpm typecheck` + `pnpm fix`).
caffeine check --fix

# 5. Upload a built draft (needs a cloud project id). For a brand-new app, create the
#    cloud project once to obtain an id, then preview:
caffeine projects create                 # reports a new project id
#    put that id in caffeine.toml [project] id = "...", OR pass --project-id:
caffeine preview --build --project-id <id>

CAFFEINE_VERBOSE=1 を設定すると、caffeine install、caffeine build、caffeine check のサブプロセス出力全体がストリーミングされます。各コマンドに --verbose を渡すのと同じです。--json を指定すると、引き続きストリーミング出力は抑制されます。

生成の順序。 src/frontend/src/backend.ts は、ビルドで pnpm bindgen が実行されるまで存在しません。そのため、フロントエンドから ./backend をインポートする場合、フロントエンドの型チェックを caffeine check で行うには、その前に少なくとも一度 caffeine build を実行する必要があります。新規作成したアプリで App.tsx がまだ ./backend をインポートしていなければ、最初のビルド前でも型チェックは問題なく行えます。

公開する。 caffeine preview --build は（project.id がある場合）ドラフトを作成し、その URL を返します。ドラフトを公開 URL に昇格させるには、caffeine.ai のウェブアプリを開いてください（caffeine chat open で開くか、caffeine.ai にアクセスします）。デプロイ用の CLI コマンドはありません。caffeine projects show <id> を使うと、ドラフトと公開 URL を確認できます。ドメインが割り当て済みの場合は、利用可能なカスタムドメインも表示されます。

代替案：Caffeine 独自の AI に作成させる

ローカルで CLI を実行できない（シェルやツールチェーンがない）場合は、代わりに Caffeine のホスト型 AI を利用してください。caffeine chat send "<prompt>"（または caffeine.ai のウェブチャット）で自然言語でアプリを説明します。すると Caffeine のホスト型 AI がサーバー側でスキャフォールディング、ビルド、デプロイを行います。chat send はプロンプトを送信するだけなので、CLI にデプロイ用コマンドがないこととは矛盾しません。このスキルが対象とするのは、ローカルで手作業により作成する方法です。

よくある落とし穴

  1. ルートの caffeine.toml に [workspace] がない。 これがない場合、ルートファイルは canister マニフェストとして解析され、CLI が canister を見つけられません。ルートマニフェストは、最上位にあることではなく、[workspace] が存在することで定義されます。
  2. バックエンド canister の名前を変更する。 名前は backend でなければなりません。mops.toml では [canisters.backend] が宣言され、ルートの bindgen スクリプトは ./src/backend/dist/backend.did を読み込みます。名前を変更すると、ビルドと生成されたクライアントが動作しなくなります。
  3. src/frontend/src/backend.ts や declarations/ を手書きしたり編集したりする。 これらは caffeine-bindgen によって生成され、ビルドのたびに上書きされます。バックエンドのメソッドは main.mo に追加してから再ビルドすると、クライアントが再生成されます。生成されたヘッダーには「このファイルを変更しないでください」と記載されており、Biome の対象からも除外されています。
  4. 初回のビルド前に ./backend をインポートしようとする。 バインディングモジュールは、ビルドの pnpm bindgen ステップで作成されます。import { createActor } from "./backend" を使用する前に、caffeine preview --build（または caffeine build）を一度実行してください。
  5. dfx deploy を実行したり、caffeine deploy が使えると考えたりする。 Caffeine アプリは caffeine CLI でビルドし、ウェブアプリで公開します。このワークフローでは dfx を使用せず、CLI によるデプロイ／公開コマンドもありません。
  6. 必須の mops.toml 設定を削除する。 単一の [canisters.backend]、[canisters.backend.check-stable]、[build] outputDir、および [toolchain] moc の固定設定を維持してください（これがないと mops はコンパイルできません）。
  7. .old/ や env.json を削除したり、copy:env を省略したりする。 .old/ には check-stable が比較する安定シグネチャのスナップショットが保存されています。配信されるフロントエンドが実行時設定を読み込めるように、env.json を dist/ にコピーする必要があります。
  8. writing-motoko スキルを使わずに Motoko を記述する。 最新の Caffeine Motoko では mo:core、永続アクター、特定のパターンを使用します。推測で書くとコンパイラーエラーが発生します。まず https://skills.internetcomputer.org/skills/writing-motoko/SKILL.md を読み込んでください。
  9. pnpm の代わりに npm／yarn を使う。 ワークスペースは pnpm ベースです（pnpm-workspace.yaml、pnpm -r スクリプト）。caffeine install は pnpm と mops を使用します。
  10. 新規プロジェクトで caffeine install／build が ERR_PNPM_NO_LOCKFILE により失敗する。 非対話型シェル（エージェント、CI、または TTY を使わない実行）では、これらのコマンドは pnpm install --frozen-lockfile を実行します。このコマンドには、新規プロジェクトには存在しない pnpm-lock.yaml が必要です。まず一度 pnpm install を実行してロックファイルを生成すると、その後は問題なく実行できます（対話型ターミナルでは自動的に作成されます）。
  11. 初回の caffeine check が Deployed file not found: …/backend.most で失敗する。 安定シグネチャのチェックには最後にデプロイされたスナップショットが必要ですが、未デプロイのプロジェクトにはありません。空のアクターを使って .old/src/backend/dist/backend.most を用意してください（上記の mops.toml の下に示されています）。caffeine build では作成されません。
  12. caffeine preview --build が No project.id in caffeine.toml で失敗する。 ドラフトをアップロードするにはクラウドプロジェクトが必要です。caffeine projects create を実行して ID を取得し、[project] id に設定するか、--project-id <id> を渡してからプレビューしてください。caffeine build 単独では ID は不要で、アプリがコンパイルできることの確認には十分です。

関連スキル

  • writing-motoko — 必須の併用スキルです。バックエンドの Motoko コードすべてについて、信頼できる情報源です。 https://skills.internetcomputer.org/skills/writing-motoko/SKILL.md。src/backend/main.mo を編集する前に、必ず読み込んでください。
  • icp-cli — 生の Internet Computer／dfx／icp プロジェクト向けです。Caffeine では使用しません。ユーザーが Caffeine アプリを構築していない場合にのみ使用してください。

参考資料

  • references/frontend-template.md — フロントエンドの定型コード一式（package.json、vite.config.js、Tailwind／PostCSS／Biome の設定、tsconfig.json、index.html、env.json、main.tsx、スターターの App.tsx、バックエンドアクターの配線パターン）を原文どおりに掲載しています。src/frontend/ を作成するときに参照してください。

コメント

Markdown 対応