WordPress Block Theme Template> wp-block-template

WordPressの新標準であるブロックテーマを従来のテーマ開発のようにコードベースで構築するためのテンプレート。

Organization

Coppie Packages

Packages in Coppie

GitHub

Nao Komura

UI Designer, PdM, Web Developer @ Emitgnos ?? Freelance

GitHubX(Twitter)

Web開発

Tailwind CSSTypeScriptWordPress

  • v0.1.0/
  • Apache License 2.0
  • 0 issues
  • 1 discussions
目次目次を閉める
  1. WordPress Block Theme Template
    1. Features
      1. GUIベースではなくコードベースで開発
      2. ブロックテーマ独特の記法を扱いやすく
      3. コアブロックに足りない機能を補う独自のブロック
      4. より良い開発体験の追求
    2. Getting Started
      1. 事前準備が必要なツール
      2. テンプレートの利用方法
    3. Development Notes
      1. Node.js/npmのバージョン管理
      2. GitHub Actionsのローカル実行
      3. wp:initでインポートされるWordPressデータの変更
      4. PHP CodeSniffer
    4. Production Deployment
      1. WordPressのホスティング
      2. 環境変数の設定
    5. FAQ & Troubleshooting
      1. wp-block-template / wp-headless-templateのどちらを使えば良い？
      2. `npm run wp:init`でWordPressが起動しない
      3. その他
    6. License
WordPress Block Theme Templateのアイキャッチ画像

WordPress Block Theme Template

WordPressの新標準であるブロックテーマを従来のテーマ開発のようにコードベースで構築するためのテンプレート。

🔗 Demo Site: wp-block-templateWordPress Block Theme Templatehttps://wp-block-template.coppie.app

Features

GUIベースではなくコードベースで開発

ブロックテーマでのWebサイト制作に関する文献の多くは、Full Site Editing(FSE)に対応したテーマやブロックパターン等を活用してGUIでテーマをデザインし、Create Block Themeプラグインでテーマを出力するような制作フローとなっていますが、こういったノーコードデザインツールのような制作フローは現状のGutenbergには荷が重いと考えています。

本テンプレートは従来のクラシックテーマのようにコード主体でテーマ開発を行うことに主眼を置いています。その一方で、成果物となるテーマをサイトエディターを通して編集できるようにもなっています。

ブロックテーマ独特の記法を扱いやすく

ブロックテーマはBlock markupと呼ばれるHTMLのコメントを拡張した独特の記法を多用しますが、おそらくブロックマークアップはGutenbergから機械的に出力される前提で設計されたものです。

コードエディターにとってはHTMLのコメントでしかないブロックマークアップは、補完・シンタックスハイライト・フォーマットが機能しません。ゆえに、ブロックマークアップを開発者が自らの手で書くのは一筋縄ではいきません。

本テンプレートでは、VS Code 拡張機能WP Block HTML、Prettier プラグインprettier-plugin-wp-block-htmlの開発者がブロックテーマ開発におけるコーディング支援の最大化を目指しました。

コアブロックに足りない機能を補う独自のブロック

ブロックテーマは基本的にGutenbergのコアブロックによって構築されますが、開発を進めていくとコアブロックの足りない機能に悩まされることでしょう。

本テンプレートはそんな足りない機能を補う独自のブロックをいくつか同梱しています。

📦 custom-group

標準のGroupブロックとの最大限の互換性を保ちながらリンク設定を追加したブロック

最もよく使用することになるであろうGroupブロックはリンクが設定できません。
<a>タグで複数の子要素を囲うというあまりにも一般的なコードがブロックテーマでは書けなかったため開発しました。 このブロックによって [Read More →] のようなテキストとアイコンを持つリンクや、記事カードといったUIを適切にマークアップできます。

📦 custom-icon

SVGアイコンをエディター上でグラフィックとして利用するためのブロック

Gutenbergの標準ではSVGコードはCustom HTMLブロックとして展開されるため、エディター上ではSVGをグラフィックとして認知することができません。
このブロックを使うことでSVGをGutenbergエディター上で正しく展開しFSEの体験を向上させます。

📦 custom-spacer

Spacerブロックをより抽象化し空divとして様々なユースケースに応えるブロック

このブロックは空の<div>タグを単純にラップしただけのブロックですが、CSSクラス名を自由に付けることでより柔軟に使用できるようにしました。
標準のSpacerブロックはレスポンシブにサイズを変更することができず、その問題に対処するためにこのブロックを開発しましたが、空<div>としてSpacer以外の使い方も出来そうです。

🙋 And more! リクエストに応じて他にもブロックを追加

より良い開発体験の追求

wp-envを最大限活用

wp-envをベースにnpm run wp:initの1コマンドですぐにローカルWordPress環境を立ち上げられるようにしました。
SQLのマイグレーションとuploadsフォルダのマッピングによって、複数人の開発者が同じデータを持った環境をすぐに構築できるようにしています。
https://github.com/WordPress/gutenberg/tree/HEAD/packages/env#readme

GitHub Actionsのセットアップ

GitHub ActionsをCI/CDツールとしてすぐに利用できるようにセットアップしました。
現時点では「PHP CodeSnifferによるリンティング自動化」「SSHを用いたレンタルサーバー等へのデプロイ自動化」がジョブとして定義済みです。
ActionsGitHub Actionsを使用することで、高機能のCI / CDですべてのソフトウェアワークフローを簡単に自動化できます。 GitHubから直接コードをビルド、テスト、デプロイします。コードレビュー、ブランチ管理、問題のトリアージを希望どおりに機能させます。https://github.co.jp/features/actions

theme.jsonのコード分割

長くて見づらく型も無いtheme.jsonをTypeScriptコードから生成できるようにしました。
/themes/block-wp/theme.jsonはサイトエディターから見た目の変更は基本的に行わない方針で設定した/themes/block-wp/theme/*.tsから生成されたファイルです。

Getting Started

事前準備が必要なツール

テンプレートの利用方法

  1. git cloneコマンド等でリポジトリをクローン
  2. npm installを実行して依存関係をインストール
  3. composer installを実行して依存関係をインストール
  4. npm run wp:initを実行してWordPressを初期化
    • WordPress: http://localhost:8888
    • wp:initの実行前にDocker Desktopが起動している必要があります
    • wp:init後は、npx wp-env start/stopでDockerコンテナを起動/停止できます（その他のコマンドはwp-env Command Referenceを参照）
yaml
# 管理者ユーザーの情報
login: admin
password: password
email: [email protected]

Development Notes

Node.js/npmのバージョン管理

.node-versionに記載のバージョンのNode.jsを使用します。

これはnodenvを使用する前提で配置されたファイルです。そのため、nvmやvoltaなどを使用する場合は、記載のバージョンを別途.nvmrcやpackage.jsonに追加してください。

また、npmのバージョンはCorepackで管理します。CorepackはNode.js v14.19.0以降に同梱されています。

Corepackでnpmを管理下に置くにはcorepack enable npmを実行します。

ただ、Corepackはまだ実験的なツールであり、npmのバージョン差異による影響も限定的であるため、特に本プロジェクトにおいて導入は必須ではありません。

GitHub Actionsのローカル実行

./github/workflowsにGitHub Actionsの設定ファイルを配置しています。

ローカルでのジョブの実行確認にはactを使用できます。 また、ジョブ内で使用する環境変数は.secretsに記載することでactから参照できるようになります。

wp:initでインポートされるWordPressデータの変更

wp:initでインポートされるデータはtheme-test-data-jaを利用しています。

このデータはWP-CLIのwp db exportコマンドでwordpress/migrations/seed.sqlにエクスポートされています。

wp:initはこのSQLファイルをインポートして初期データを読み込んでいます。そのため、各々で都合の良いWordPressデータをwp db exportコマンドでエクスポートすることで、wp:initでのインポートデータを変更することができます。

また、WP-CLIのwp db import/exportコマンドをこの用途に使い易いように、npm scriptsにwp:import/wp:exportコマンドを用意しています。このラッパーコマンドではexportが不要と思われるテーブルは除外しているため、必要に応じて編集してください。

PHP CodeSniffer

PHPのリンティングおよびフォーマッティングに使用しています。 .phpcs.xml に設定を記述しています。これはWordPressのコーディング規約に準拠しています。

この規約では、グローバルな関数や変数には独自の接頭辞を付けることが求められています。 デフォルトではcustomという接頭辞を設定していますが、必要に応じてWordPress.NamingConventions.PrefixAllGlobalsのprefixesに追加してください。

Production Deployment

wp-headless-templateを本番環境で使用する際は、以下の項目を確認してください。

WordPressのホスティング

WordPressのホスティングは多様な選択肢がありますが、デモサイトではさくらのレンタルサーバーを使用しています。
さくらのレンタルサーバーを使用している理由は、何より安価であることと、WP-CLIがデフォルトで使えるくらいです。

本テンプレートを動かすにあたってWordPressに対しての特別な要件はないので、お好きなホスティングサービスをご利用ください。

また、任意ではありますが、SSHでのファイル操作が可能な場合、定義済みのGitHub Actionsのジョブ（.github/workflows）によって特定のGitHubのアクションをトリガーに自動的にWordPress関連のファイルを更新することができます。

SSHの要件にくわえて、複数のWordPressのホスティングが可能な場合、ステージング環境用のWordPressを用意することで、GitHubでのプルリクエスト時にステージング環境にデプロイすることも可能です。

環境変数の設定

本テンプレートでCI/CDとして利用しているGitHub Actionsにもシークレットを設定すると、WordPress関連のファイルをSSHで自動的にデプロイできるようになります。

.github/workflows/deploy-production.ymlと.github/workflows/deploy-staging.ymlにて、以下のシークレットを使用しています。

yaml
SERVER_SSH_PRIVATE_KEY: # SSH秘密鍵
SERVER_HOST: # SSHホスト
SERVER_USER: # SSHユーザー
SERVER_PORT: # SSHポート
SERVER_PATH: # 本番環境のWordPressディレクトリまでのパス （例: `/home/coppie/www/headless-wp`）
SERVER_STAGING_PATH: # ステージング環境のWordPressディレクトリまでのパス （例: `/home/coppie/www/headless-wp-staging`）

FAQ & Troubleshooting

wp-block-template / wp-headless-templateのどちらを使えば良い？

それぞれのテンプレートの違いを把握することが選択の判断材料になると思います。
細かい違いは色々とありますが、明らかな違いとしては以下のような項目が挙げられそうです。

wp-block-template

  • WordPress管理画面からノーコードツールのような感覚でWebサイトの内容を変更できる
  • ホスティングのために用意するサーバーが1つで済むため、小〜中規模であればランニングコストが抑えられる
  • WordPressテーマ開発者にとっては、テーマ開発の知識がそのまま活かせる
  • Webサイトの内容次第では、HTMLとCSSを書くだけでWebサイトを構築できる

wp-headless-template

  • 開発の柔軟性・拡張性が高い
  • 高速なページ遷移やインタラクティブなUIを実装しやすい
  • 大規模なアクセスを効率よく処理できるため、コスト面を含めスケーラビリティが高い
  • 実装方法次第では、セキュリティリスクを大きく低減できる

大雑把に言えば、小〜中規模のアクセスが見込まれるWebサイトで、ランニングコストもあまりかけられないような場合においては、wp-block-templateは手離れしやすいWebサイトを開発できる良い選択となりそうです。

Tip

Tip

[!TIP] 上記のリストには含めていませんが、wp-block-template自体はサードパーティのプラグインをWP Multibyte Patch以外使用しておらず、不具合・脆弱性対応なども最小限に抑えられると思います。

反対に、wp-headless-templateは大規模なアクセスが見込まれるケースや、セキュリティが重視されるケース、Webサイトの拡張性を最大化したいケースなどに適した選択です。 前者2つのケースにおいてはwp-block-templateでも対応可能ですが、最後の「Webサイトの拡張性を最大化したいケース」への対応はwp-headless-templateでないと困難を極めます。

Tip

Tip

[!TIP] 具体的には、複数のデータソースやWebアプリケーション的な機能を持つWebサイトの開発が難しくなるはずです。

例えば、Shopify Storefront APIを使ってヘッドレスにECサイトを構築してその中にWordPressを使ったブログも含めたり、ユーザーアカウントのサブスクリプション状態に応じて記事の閲覧権を付与したり、そういった要件がこれに該当します。

また、個々の開発者のスキルセットに依存するとは思いますが、WordPressテーマ/プラグインの開発しか経験がない場合はwp-headless-templateを使いこなすまでの道のりは険しく、一方で、普段からNext.jsなどでWebアプリケーションを開発しているような方にとってはwp-block-templateは煩わしさを感じる部分も多いと思います。

とはいえ、それぞれのテンプレートで採られている手段を1から開発するのに比べれば、相当な時間短縮が図れるのは間違いないので、Webサイトの要件に応じて各テンプレートを選び、それぞれの開発手法にチャレンジしてみるのも良いのではないかと思います。困ったことがあれば気軽にご相談ください。

npm run wp:initでWordPressが起動しない

まず、Docker Desktopが起動しているか確認してみてください。

Docker Desktopが起動しているにも関わらずnpm run wp:initでWordPressが起動しない場合、wp-envを別のプロジェクトで使っている可能性があります。

別のプロジェクトで使っている場合は、そのプロジェクト内でnpx wp-env stopを実行してから、再度npm run wp:initを実行してください。

それでも解決しない場合は、npx wp-env clean allあるいはnpx wp-env destroyを実行してから再度お試しください。

その他

その他、不具合や疑問点があれば、IssuesとDiscussionsにて気軽にご相談ください。

License

本テンプレートのライセンスはApache License 2.0に基づきます。詳細はLICENSEを参照してください。

また、WordPressのGPL(GNU General Public License)によって認められる権利を除き、NOTICEに記載のように、本テンプレート内のソースコードを再配布することはできません。