Zenn
⚡

wp-envとViteで作る爆速WordPress開発環境

2024/02/01に公開
WordPress
開発環境
Vite
tech

Viteの速さを知って以来その開発体験の虜になってしまい、Viteを使ったWordPress開発環境を考えたので紹介します。あくまで自分の開発フローに合わせたものであり、全ての開発シーンで利用できるとも限らないので予めご了承ください。

こちらがそのリポジトリになります
https://github.com/Crayfisher-zari/my-best-wp-env

ViteのHMRを効かせながら開発できるので高速なWordPress開発体験を提供できるはずです。

前提とコンセプト

この開発環境は下記前提とコンセプトに基づいています。

  1. 旧来のPHPをベースとしたクラシックテーマでの開発を想定しています。新しいブロックテーマ開発で適用できるかどうか分からないです。
  2. MacOS環境を前提としています。（Windowsでも動くと思いますが、NPM Scriptsにrmコマンドが入っているので適宜置き換えてください）
  3. 静的なHTMLを作成してからWordPress開発を行うフローを前提としていますが、直接WordPressを開発する場合でも利用できます。
  4. 中長期的に使えることを目標に、できる限りシンプルな構成でサードパーティ製プラグインなどはできるかぎり利用しないようにしています。
  5. Sass（SCSS）とTypeScriptを使います。
  6. テーマファイルの中はできるだけクリーンな状態にしたい。
  7. 複数人での開発でできるだけ開発者間の環境差異も減らすことも考慮しています。

WordPressテーマ開発のみでViteを使うなら、開発するテーマファイルの中にVite環境を構築すれば可能ですが、静的なHTMLを作成→WordPress開発というフローを取ることもあります。それにも対応した形になります。（あと、最終的にアップロードするテーマファイル内に開発用ソースをあまり入れたくないともいうのもあります）

必要環境

こちらの構成は下記のインストールが予め必要です。

  • Node.js
  • Docker

大まかな構成

この開発環境はwp-envでDocker上にWordPress環境を構築し、Viteで開発用ローカルサーバーを起動します。SassやTypeScriptはVite上のローカルサーバー上のものを参照することで高速な開発体験を提供します。

以下のようなフォルダ構成になっています。

└src
  └assets
    └images
    └js
    └style
  └pubilc
    └images
└wordpress
  └wordpress
    └plugins
    └themes
    └uploads
└package.json
└vite.config.ts

静的HTMLはsrcフォルダ内で行い、完成したらビルドしてWordPressでの開発に移るのが基本的な流れです。しかし、静的HTMLで完成後もCSSやJavaScriptは引き続き変更するのでその度にビルドしなくてもよいことを目指して作りました。

かんたんな仕組み解説

静的開発時とWordPress開発時でViteの設定を変えられるようにしています。

▼vite.config.ts（一部）

const root = resolve(__dirname, "src");

// WordPress用ビルドのinput設定。WordPress用にはhtmlファイルは不要なため、scssとtsのみをビルド対象にする
const inputsForWordPress = {
  style: resolve(root, "/assets/style/style.scss"),
  // 動的にファイルを取得する @see https://rollupjs.org/configuration-options/#input
  ...Object.fromEntries(
    globSync("src/assets/js/*.ts").map((file) => [
      relative(
        "src/assets/js",
        file.slice(0, file.length - extname(file).length),
      ),
      fileURLToPath(new URL(file, import.meta.url)),
    ]),
  ),
};

// 静的開発用のinput設定。静的資材用にはhtmlファイルを経由してscss,tsなどをビルドする
const inputsForStatic = {
  style: resolve(root, "/assets/style/style.scss"),
  ...Object.fromEntries(
    globSync("src/**/*.html").map((file) => [
      relative("src", file.slice(0, file.length - extname(file).length)),
      fileURLToPath(new URL(file, import.meta.url)),
    ]),
  ),
};

export default defineConfig(({ mode }) => ({
  build: {
    rollupOptions: {
      input: mode === "wp" ? inputsForWordPress : inputsForStatic,
    },
  },
}));

静的開発時はCSSおよびsrcフォルダ内の.htmlをViteに読み込みます。WordPress用にビルドする場合はHTMLファイルは不要なので直接CSSと.tsを読み込みます。これらをNPM Scriptsの--mode引数を通じて変えています。静的開発せず直接WordPressで開発する場合はrollupOptionsのinputを場合分けせずinputsForWordPressのみに設定すればOKです。

またWordPress側のindex.phpのヘッダー部分にも工夫をいれています。

▼index.phpのヘッダー部分

<?php 
  if(WP_DEBUG){
    $root = "http://localhost:5173";
    $css_ext = "scss";
    $js_ext = "ts";
    echo '<script type="module" src="http://localhost:5173/@vite/client"></script>';
  }else{
    $root = get_template_directory_uri();
    $css_ext = "css";
    $js_ext = "js";
  } 
?>
<link rel="stylesheet" href="<?php echo $root;?>/assets/style/style.<?php echo $css_ext?>">
<script src="<?php echo $root;?>/assets/js/script.<?php echo $js_ext?>" type="module"></script>

.wp-env.jsonの設定で"WP_DEBUG": trueとなっているので開発時は$rootをViteのlocalhost:5173に向けたSCSSファイルやTypeScriptファイルを参照します。またHMR用のスクリプトも読み込んでいるのでソースの反映がすぐにWordPressの画面に反映されます。

非開発時はテーマファイル内のビルドされたCSSとJavaScriptを参照します。開発時にビルド後のファイルを参照したい場合は、上記のif文をif(false)などに書き換えると確認できます。.wp-env.jsonの値を書き換えるとDockerが別コンテナ扱いになるようなのでおすすめしません。本番環境でWP_DEBUGがtrueになることはまずないはずですが、納品時には念のため消しておくと良いです。

WordPressコンテンツをほかの開発者と同期する

WordPress開発時にはWordPress内で作成した記事やページ、その他設定を開発者間でそろえたいこともあります。実際のアクセス制限されたサーバー上にWordPressを構築してそこを共有することでもできますが、都度都度ファイルをアップしないといけないなど手間がかかります。

そこである程度同期できるよう、WordPressのバックアップファイルを開発者間で共有することでコンテンツの同期を図ります。

NPM Scriptsのwp-contents exportコマンドでバックアップファイルを出力、wp-contents importコマンドでインポートできます。このバックアップファイルをGitなどで管理し、開発者間でのWordPressコンテンツを同期できます。あくまで単一のバックアップファイルなので差分管理などはできず、頻繁な更新には向きません（コンフリクトしてもどちらかのファイルしか採用できません）。

使い方

リポジトリのREADMEからの抜粋ですが、簡単な使い方を説明します。

静的制作時

静的なHTMLを作成する場合はNPM Scriptsのdevコマンドを起動するとローカルサーバーlocalhost:5173が立ち上がります。このポート番号はWordPress時にも参照するので固定でお願いします。（変更する場合はWordPress側も変更する必要あります）

静的HTMLは基本srcフォルダ内で作ります。CSSやJavaScriptは直接.scssファイルや.tsを参照すれば、Viteがいい感じにしてくれます。

▼HTMLのヘッダー部分

<link rel="stylesheet" href="/assets/style/style.scss" />
<script src="/assets/js/script.ts" type="module"></script>

あとはそのままHTML・CSS・JavaScriptを開発していけばOKです。

WordPressテーマ開発時

まずDockerを立ち上げてください。静的制作時と同様にNPM Scriptsのdevコマンドを起動し、さらにwp-startコマンドを実行します。初回起動のみ色々ダウンロードなどがあるので時間がかかります。wp-startが立ち上がるとlocalhost:8888にアクセスできるようになります。ここがWordPressのローカル環境になります。

開発時はCSSやJavaScriptはViteのローカルサーバーのものを参照しているので、静的作成時と同じようにsrcフォルダ内のファイルを操作してください。終了時はwp-stopでDockerのコンテナを停止します。

画像の格納先、読み込み方について（大事）

画像パスなどが開発・ビルド後できちんと通るように下記ルールでお願いします。

imgタグで読み込む画像はsrc/public/images内に、CSSやjsで読み込む画像はsrc/assets/images/に格納してください。

フォルダ構造

└src
  └assets
    └images
      └background.png
      └js.png
  └pubilc
    └images
      └static.png

Viteではpublicフォルダはルートとして扱われるため、/images/static.pngというパスで画像を読み込むことができます。

▼HTML

<img src="/images/static.png" alt="" width="300" height="300" />

CSSで画像を読み込む場合は相対パスではなく、/assetsから始めるパス名にしてください。こちらもビルド時にViteがパスを解決するためです。

▼CSS

background-image: url("/assets/images/background.png");

jsで画像ファイルを読み込む場合はViteにビルド時にパス解決されるようimport文で読み込んでください。

▼JS

import imgsrc from "/assets/images/js.png";
// jsから画像を読み込むサンプル
const canvas = document.querySelector<HTMLCanvasElement>("#canvas");
const context = canvas!.getContext("2d");
const image = new Image(300, 300);
image.src = imgsrc;
image.addEventListener("load", () => {
  context?.drawImage(image, 0, 0, 300, 300);
})

WordPress開発時にPHPで画像を読み込む場合はテンプレートフォルダ内の画像を参照します。WordPress用ビルド時に静的制作時のpublicの画像はテンプレートフォルダに出力されますが、動的に変更はなされないので画像変更時は都度ビルド、もしくは手動でコピーが必要になります。

<img src="<?php echo get_template_directory_uri();?>/images/static.png" alt="" width="300" height="300" />

上記のように静的資材HTMLのコードのsrcの頭に<?php echo get_template_directory_uri();?>を付与することでうまく読み込めるようになります。

静的資材ビルドについて

静的資材をビルドする場合はNPM Scriptsのbuidコマンドを実行してください。distフォルダに一式出力されます。

WordPress用ビルドについて

WordPress用にCSSやJavaScriptをビルドする場合はNPM Scriptsのbuid for WPコマンドを実行してください。wordpress/themes/TEMPLATE_NAME/内にassetsフォルダとimagesフォルダが出力されます。assetsフォルダにはビルドした各種CSSやJavaScriptが、imagesにはHTMLから読み込んだ静的な画像が出力されています。

WordPressのログイン方法

http://localhost:8888/wp-admin/にアクセスし、IDはadminパスワードはpasswordでログインできます。初回は言語設定が英語なので日本語に変えておくと良いでしょう。

さいごに

リンターやフォーマッターなども入っていますがそれらの設定はお好みでお願いします。またプラグインも特に入れていないので適宜案件に応じた形にカスタマイズしてください。

よかったら使ってみてください。

Discussion