最初のテーマを作る

テーマは、site-runtime が Web サイトをレンダリングする方法を定義します。テーマが依存できるのは @zcmsorg/theme-sdk だけです。API やデータベースへ直接アクセスすることはできません。

事前準備

Node.js 22+、pnpm 10+ と zcms CLI を用意します。

npm install -g @zcmsorg/cli

ステップ 1: プロジェクトのひな型を作成する

zcms init ./corporate --kind theme --id com.acme.theme.corporate

自分が管理するドメインの reverse-DNS ID を使用してください。指定しなかった項目は init が対話形式で尋ねます。既存のファイルがあるディレクトリには書き込みません。

生成されたテーマには、ビルド、型チェック、パッケージ化、署名に必要な設定が含まれています。

corporate/
├── theme.json           # manifest
├── package.json
├── build.mjs            # esbuild -> dist/index.mjs + dist/theme.css
├── tsconfig.json
├── src/
│   ├── index.tsx        # Layout、template、block、SEO
│   ├── theme.css
│   └── locales/en.json
└── .gitignore           # *.pem を ignore 済み — 署名鍵はここに置かれます

cd corporate
pnpm install
pnpm build

このページの残りでは、生成されたファイルの内容を説明します。

ステップ 2: テーマの機能を宣言する

パッケージルートに theme.json を作成します。必須フィールドは id、name、version、author、engine、templates、menuLocations、settingsSchema です。テーマの entry は dist/index.mjs である必要があります。styles はテーマに含めるスタイルシートを指定します。

{
  "id": "com.example.theme.corporate",
  "name": "Corporate",
  "version": "0.1.0",
  "description": "Responsive corporate theme.",
  "author": {
    "name": "Example Studio",
    "url": "https://example.com"
  },
  "engine": ">=0.1.0",
  "entry": "dist/index.mjs",
  "styles": "dist/theme.css",
  "templates": ["home", "page", "post", "archive", "notFound", "error"],
  "menuLocations": [
    { "key": "primary", "name": "Primary menu" },
    { "key": "footer", "name": "Footer menu" }
  ],
  "settingsSchema": {
    "type": "object",
    "properties": {
      "primaryColor": {
        "type": "string",
        "title": "Primary colour",
        "format": "color",
        "default": ""
      }
    }
  },
  "media": {
    "screenshots": ["screenshots/home.png"]
  }
}

任意フィールドは seo、media、demo、optionalCapabilities です。更新後もサイトから参照できるよう、テンプレート名、メニューキー、設定キーはバージョン間で変更しないでください。

ステップ 3: テンプレートとブロックを実装する

@zcmsorg/theme-sdk の型を使って、ホーム、ページ、記事、一覧、エラー、フォールバックの各テンプレートを実装します。テーマ自身が Pages や Blogs を取得するのではありません。site-runtime が URL に一致する項目を content、一覧を archive、サイト共通データを ctx として渡します。

まずページとブログ記事を表示するで、content.data、content.blocks、ページネーション、メニュー、多言語 URL の実装例を確認してください。テーマにサンプルデータを含める場合は、デモコンテンツを提供するを参照してください。テーマがプラグインの任意機能に対応する場合は、テーマとプラグインを連携するへ進みます。

site-runtime から渡されたデータだけをレンダリングする。
信頼できないコンテンツをフィールドの型に応じてエスケープする。
適切な heading structure、keyboard navigation、focus state を用意する。
狭い viewport と広い viewport の responsive behavior を定義する。
任意のコンテンツ、メディア、メニューがない場合に安全な代替表示を用意する。

ステップ 4: 設定項目を定義する

テーマの設定項目は JSON Schema で定義します。Admin はこのスキーマから設定フォームを生成するため、admin-web を変更せずにテーマ固有の設定を追加できます。

設定の後方互換性を維持してください。新しいフィールドには既定値を設定し、既存フィールドの意味を予告なく変更せず、必要な移行手順を文書化します。

ステップ 5: アセットと翻訳を追加する

テーマが使用するアセットだけをパッケージに含める。
Package 作成前に画像と font を最適化する。
UI の文言をハードコードせず翻訳キーを使用する。
すべてのキーに既定のメッセージを用意する。
ユーザーコンテンツとテーマの翻訳メッセージを分離する。

ステップ 6: ローカルでプレビューする

テーマをビルドし、ローカルの開発ビルドをテストサイトへ読み込みます。少なくとも次の項目をプレビューしてください。

ホーム、一覧、詳細、404 ページ。
空の状態、最小限のコンテンツ、長いコンテンツ。
対応するすべての locale。
Desktop と mobile layout。
対応している場合は、明るい背景と暗い背景でのブランドアセット。
Metadata、Open Graph、robots policy、JSON-LD output。

別のテーマに切り替えてから再度有効化し、コンテンツや設定が削除されないことを確認します。

ステップ 7: テストとパッケージ作成

型チェック、lint、ユニットテスト、アクセシビリティチェック、ビジュアルリグレッションテストを実行します。その後、次の手順でリリース用ファイルを作成します。

Version と changelog を更新する。
Commit 済み lockfile を使い、clean checkout から build する。
Publisher key pair がない場合は、一度だけ生成する。
Terminal window
```
zcms keygen --out ./keys
```
出力先ディレクトリを作成し、プロジェクトルートを直接パッケージ化する。CLI はソース、依存関係、開発用設定を自動的に除外します。
Terminal window
```
mkdir -p release

zcms pack . --kind theme \
  --key ./keys/publisher-private.pem \
  --pub ./keys/publisher-public.pem \
  --out ./release/corporate-0.1.0.zcms
```
公開者の署名を検証する。
Terminal window
```
zcms verify ./release/corporate-0.1.0.zcms
```
zcms pack が出力した checksum を記録する。

この段階では publisher signature : VALID と表示されることを確認します。Marketplace はアップロード後に静的スキャンを実行し、審査の過程で 2 つ目の署名を追加します。続きはパッケージを公開するを参照してください。