AppBase アプリの開発と公開
AppBase のアプリは 宣言(AppSpec)+ React の画面 だけでできている。サーバーコード・SQL・独自 API は書けない。 データの保存、権限、状態の変更、ログイン、ステージングと本番の分離は AppBase のクラウドが受け持つ。
| 部品 | 中身 |
|---|---|
spec/app.yaml |
アプリ ID・表示名・役割(roles) |
spec/entities/<id>.yaml |
データの型 1 つ(項目・状態・権限)。1 ファイル 1 つ |
spec/commands/<id>.yaml |
業務操作 1 つ(申請・承認など。状態を変える唯一の方法)。1 ファイル 1 つ |
ui/src/、ui/public/ |
React + TypeScript の画面。通信は @appbase/sdk だけ |
このスキルのフォルダ(この SKILL.md があるフォルダ)を <skill> と書く。コマンドはすべて次の形で呼ぶ:
node "<skill>/scripts/appbase.mjs" <コマンド> ...
公開はクラウドの公開 API(https://www.<domain>/_deploy/v1/、仕様は api.md)を通る。
このスクリプトがその呼び出し役なので、API を直接呼ぶスクリプトを新しく書く必要はない(書く場合も api.md に従う)。
0. 最初に状態を確かめる
node --version # 20 以上
node "<skill>/scripts/appbase.mjs" whoami # ログイン済みか、どの会社のどのサービスか
node "<skill>/scripts/appbase.mjs" apps # 使えるアプリ ID
| 結果 | 次にやること |
|---|---|
node がない・20 未満 |
setup.md の「道具」 |
ログインしていません / 期限切れ |
§1 ログイン。AppBase のアカウントがまだない人は setup.md |
使えるアプリ ID はありません |
運用者にアプリ ID の登録を依頼してもらう(setup.md の 3) |
アプリのフォルダ(spec/app.yaml がある)がまだない |
§2 新しく作る |
| アプリのフォルダがある | §3 作る・直す、公開を頼まれたら §4 |
1. ログイン(端末をブラウザで承認する)
トークンは利用者がブラウザで承認したときにだけ、この端末に発行される。トークン・パスワード・鍵を利用者に聞かない。会話に貼ってもらわない。
node "<skill>/scripts/appbase.mjs" login-start https://www.<domain> # 承認用のアドレスと照合コードを表示する
node "<skill>/scripts/appbase.mjs" login-wait # 承認されるまで待つ(最大 10 分)
login-startが表示したアドレスと照合コードを、そのまま利用者に伝える。 「このアドレスを開いて AppBase にログインし、照合コードが同じことを確かめて『承認する』を押してください」。- 続けて
login-waitを実行する(最大 10 分待つので、コマンドの時間制限を 11 分以上にするか、裏で実行して終わりを待つ)。 <domain>がわからなければ利用者に聞く(会社ごとに違う。例: 管理画面のアドレスがhttps://www.example.appbase.workなら、それがそのまま入る)。
- 資格情報は
~/.config/appbase/credentials.json(本人だけが読める権限)に保存される。このファイルを読んだり表示したりしない。 - ログインは 7 日で切れる。端末を手放すときは
logout。管理画面の「アカウント設定」→「端末のログイン」で一覧・取り消しができる。
2. 新しく作る
作り始める前に、利用者へ次を短く聞く(2〜3 問まで。専門用語は使わない)。
- 何をするアプリか、誰が使うか(役割は何種類か。例: 申請する人と承認する人)
- 使うアプリ ID(
appsに出ている、運用者が登録した ID から選ぶ。後から変えられない)
node "<skill>/scripts/appbase.mjs" new <作る場所>/<フォルダ名> --id <アプリID> --name "<表示名>"
- ひな形・SDK(
ui/vendor/appbase-sdk)・npm install・git の最初のコミットまで行われる。 - できたフォルダの
AGENTS.md(CLAUDE.mdから読まれる)に、アプリの中で守る規則と AppSpec の全仕様がある。以後の作業はそのフォルダで行う。 その中の「最後のメッセージ」「```question ブロック」の書式は Mac アプリの AI 向けなので、Claude Code / Codex では普段どおり会話でよい。
3. 作る・直す
必ず develop.md を読んでから spec と画面を書く。要点:
- 変更してよいのは
spec/とui/src/、ui/public/だけ。npm の依存の追加、ui/package.json・ui/build.mjs・ui/vendor/の変更はしない。 - 状態の変更(申請・承認など)は commands で宣言する。権限は spec に書き、画面でボタンを隠すことを権限の代わりにしない。
- 値の入った項目の ID を変えたり消したり型を変えたりしない(公開時に拒否される)。追加は安全。
- ユーザーのデータは React のテキストとして表示する。
innerHTML・dangerouslySetInnerHTML・外部スクリプト・外部へのfetchは使えない。 - 外部連携(
integrations)・コネクタ(connectors)はクラウドでは動かない。使わない。 - 画面の文言は平易な日本語。
仕上げに毎回:
node "<skill>/scripts/appbase.mjs" check <アプリのフォルダ> # クラウドで spec を検査 → 型チェック → ビルド(ui/dist)
エラーがなくなるまで直してから git にコミットする。
4. 公開する(ステージング → 本番 → 戻す)
deploy.md の手順で行う。要点:
node "<skill>/scripts/appbase.mjs" stage <アプリのフォルダ> --notes "<利用者向けの変更の説明>" # 検査・ビルド・アップロード・ステージングへ公開
node "<skill>/scripts/appbase.mjs" status <アプリID> # 各環境の版、止まっている操作
node "<skill>/scripts/appbase.mjs" promote <アプリID> --confirm-production # ステージングと同じビルドを本番へ(利用者に確かめてから)
node "<skill>/scripts/appbase.mjs" rollback <アプリID> --env prod --confirm-production # 本番を一つ前の版へ(データは戻らない)
- 最初に
stageした人がそのアプリのオーナーになる。以後はオーナーだけが公開できる。 --confirm-productionは、利用者が本番に出す・戻すことをこの会話で明確に頼んだときだけ付ける。 推測で付けない。- 公開の結果がわからなかった(時間切れ・通信の失敗)ときは、同じ
stageを繰り返さない。スクリプトが状態を表示するので、 止まっている操作があれば利用者に確かめてresume <操作ID> --app <アプリID>かcancel <操作ID> --app <アプリID>を選ぶ(本番の操作は--confirm-production)。
5. 困ったとき
troubleshoot.md を見る。アカウントや登録の準備は setup.md。
やってはいけないこと
- API キー・パスワード・トークンを聞き出す、会話に貼ってもらう、コード・spec・設定値に書く、資格情報のファイルを読む・表示する。
- 公開前の検査(
check)を飛ばしてステージングに出す。 - 利用者に確かめずに本番へ出す(promote)・戻す(rollback)・本番の操作を再開/取り消す。
- 失敗した公開を、状態を確かめずに同じコマンドで何度も繰り返す。
- 他人のアプリを公開しようとする、運用者の権限や AWS の認証情報を求める。
ui/vendor/appbase-sdkやスクリプトを書き換えて制限を回避する。足りない機能は「AppBase にまだない」と伝える。
利用者への最後の案内(例)
ステージングに出しました(版 3)。
ステージング: https://staging.<app-host>.<domain>/
管理画面(データ・設定値・共有): https://www.<domain>/login
確かめて問題なければ「本番に出して」と言ってください。同じものを本番に出します。
うまくいかなければ一つ前の版に戻せます(データは戻りません)。
<app-host> はアプリ ID の _ を - にしたもの。アプリを開くには、管理画面にログインしてからアプリを開く。