Getting started
いつもの Astro を、
そのままつなぐ。
Cocoro CMS のために、SDK を入れたり、独自の書き方に直したりする必要はありません。必要なのは、GitHub にある Astro のリポジトリと、npm の lockfile だけ。ここでは、つなぐ手順と、担当の方が気持ちよく編集できるサイトにするコツを説明します。
Steps
6 つの手順。
- 1
申し込む
フリープランなら、メールアドレスと組織の名前だけで始められます。管理画面のアドレスは「組織 ID.cocoro.appz.jp」。最初の管理者は 2 段階の確認（認証アプリかパスキー）を設定します。
- 2
リポジトリをつなぐ
「サイトを追加」から GitHub App を入れ、使うリポジトリだけを選びます。求める権限は contents・pull_requests・metadata の 3 つで、ワークフローの権限は求めません。
- 3
読み取りを確かめる
Cocoro CMS がリポジトリを読み、ページ・コンテンツ・部品の木を作ります。「サイトの構成」で、編集できる箇所の数と、画面に出る名前を確かめ、必要なら付け直します。
- 4
公開の形を決める
GitHub Actions なら、Cocoro CMS が作るワークフロー（.github/workflows/cocoro-deploy.yml）を受け取ってリポジトリに置き、Secrets を登録します。レンタルサーバーへは、FTPS・SFTP のひな型を選びます（Cocoro CMS がビルドして送る形は準備中）。
- 5
役割を決める
管理者・開発者・承認者・編集者・閲覧者。編集者が書けるのは src/content/・src/forms/・public/images/ の中だけ。設定ファイルや依存に触れる変更は、開発者か管理者しか承認できません。
- 6
書いて、出す
担当の方が直して「確認を頼む」。承認する人が差分を見て「承認して公開する」。マージのあと、選んだ形でビルドと公開が進みます。
1kokoro-photo/2├─ astro.config.mjs3├─ package.json4├─ package-lock.json ← npm の lockfile（ビルドとプレビューに使う）5├─ public/6│ └─ images/ ← 担当の方が画像を置ける7└─ src/8 ├─ content.config.ts ← コレクションと zod のスキーマ9 ├─ content/ ← 担当の方が記事を書ける10 │ ├─ news/11 │ └─ plans/12 ├─ components/ ← Props の型が編集の欄になる13 ├─ layouts/14 └─ pages/ ← .astro の文字・リンク・画像を押して直せる読むファイル
src/content.config.{ts,mjs,js}（旧来の src/content/config.ts も）。ローダーは glob・file に対応。独自のローダーのコレクションは、読み取りだけで編集はできません。
Design for editing
編集しやすいサイトの、
作り方。
Cocoro CMS は、コードの書き方で「どこを担当の方に開くか」を決めます。特別な印は要りません。ふつうの Astro のよい書き方が、そのまま編集しやすさになります。
1---2// 一覧はコレクションから。担当の方は記事を足すだけで、一覧に並ぶ3import { getCollection } from 'astro:content';4import Hero from '../components/Hero.astro';5const news = (await getCollection('news', ({ data }) => !data.draft))6 .sort((a, b) => b.data.date.valueOf() - a.data.date.valueOf());7---8<Hero title="家族の今日を、一枚に。" buttonText="撮影を予約する" buttonHref="/contact" />9<ul>10 {news.map((n) => <li><a href={`/news/${n.id}/`}>{n.data.title}</a></li>)}11</ul>文字は props か、コレクションに
一覧やカードの中身を .astro の中の配列に直書きして map すると、その部分はロックされます（データの出どころは示されます）。担当の方に直してほしいものは、props で渡すか、コンテンツコレクションに置いてください。
Props に型と JSDoc を
interface Props の型から欄の種類が決まります。文字列リテラルの union は選択肢に。JSDoc の一言は、欄の説明として担当の方に見えます。
名前で伝わる props に
coverImage・photo のように image・photo・cover などで終わる名前は画像の欄、buttonHref・link のように href・url・link で終わる名前はリンクの欄になります。
入れ子の object は避ける
スキーマの z.object の入れ子は、表示だけで編集できません。担当の方が直す項目は、平らに並べるのがおすすめです。
lockfile を置く
プレビューは、package-lock.json（npm）で依存を入れます。pnpm・yarn の lockfile だけでは動きません。
postinstall に頼らない
依存は --ignore-scripts で入れます。インストールの時のスクリプトで何かを生成している場合は、ビルドの中に移してください。
Cocoro CMS
伝えたいことを、
伝えたいときに。
Astro のサイトを、だれでも安全に更新できるように。フリープランは 1 サイト・2 人まで、ずっと無料です。