ディーゼロ フロントエンド標準開発環境ビルドツール

フロントエンド標準開発環境（@d-zero/scaffold）のビルド処理をパッケージしたものです。 Scaffoldに含めているpackage.jsonのdevDependenciesに記載してあるため、追加のインストールは基本的に不要です。

他の環境にインストールする場合は次のように追加します。

yarn add @d-zero/builder

使用方法

以下のコマンドを実行することでビルド処理が実行されます。

npx @d-zero/builder

オプション

--clear-cache

Eleventyのキャッシュをクリアしてビルドを実行します。テンプレートの変更が反映されない場合や、ビルド結果に問題がある場合に使用します。

npx @d-zero/builder --clear-cache

利用技術

• Eleventy: HTMLトランスパイルおよび全体のビルド処理
• esbuild: JavaScriptトランスパイル
• PostCSS: CSSトランスパイル

設定

ベースがEleventyとなるので、Eleventyの設定ファイルを利用することができます。Scaffoldではeleventy.config.mjsを用意しています。

import path from 'node:path';

import eleventy from '@d-zero/builder/11ty';

export default function (eleventyConfig) {
	return eleventy(eleventyConfig, {
		alias: {
			'@': path.resolve(import.meta.dirname, '__assets', '_libs'),
		},
		outputCssDir: 'css',
		outputJsDir: 'js',
		outputImgDir: 'img',
		imageSizes: { selector: '*' },
		prettier: false,
		minifier: { minifyJS: false },
		lineBreak: '\r\n',
		charset: 'shift_jis',
		characterEntities: true,
		pathFormat: 'directory',
		autoDecode: true,
		ssi: { '**/*': { encoding: 'shift_jis' } },
		htmlHooks: {
			beforeSerialize: (content, isServe) => content,
			afterSerialize: (window, isServe) => {},
			replace: (content, paths, isServe) => content,
		},
		extensions: {
			html: 'html', // html以外の拡張子（例：'php'）も指定可能
		},
		parserOptions: {
			pugOptions: {
				pretty: false,
				cache: true,
				filters: { customFilter: () => {} },
			},
		},
	});
}

基本的なビルド設定は@d-zero/builder/11tyに規定されているため、それに追加の設定を行うことでビルド処理をカスタマイズすることができます。

フローチャート

flowchart LR
	#inHTML["*.html"]
	#inPug["*.pug"]
	#inCSS["*.css"]
	#inJS["*.{js,cjs,mjs}"]
	#inTS["*.ts"]
	#outHTML["*.html"]
	#outCSS["*.css"]
	#outJS["*.js"]

	#inHTML --> #dzBuilder
	#inPug --> #dzBuilder
	#inCSS --> #dzBuilder
	#inJS --> #dzBuilder
	#inTS --> #dzBuilder
	#dzBuilder --> #outHTML
	#dzBuilder --> #outCSS
	#dzBuilder --> #outJS

	subgraph #dzBuilder["@d-zero/builder"]
		direction LR

		subgraph #eleventy["11ty"]
			#html["*.html"]
			#pug["*.pug"]
			#css["*.css"]
			#js["*.{js,cjs,mjs}"]
			#ts["*.ts"]

			subgraph #transformHTML["addTransform"]
				direction TB

				#beforeSerialize(["DOM処理前フック<br>(htmlHooks.beforeSerialize)"])
				#characterEntities(["文字参照変換<br>(characterEntities)"])
				#prettier(["整形<br>(prettier)"])
				#minifier(["最適化<br>(minifier)"])
				#lineBreak(["改行コード変換<br>(lineBreak)"])
				#charset(["文字コード変換<br>(charset)"])
				#afterSerialize(["DOM処理後フック<br>(htmlHooks.afterSerialize)"])
				#replaceHook(["最終出力前フック<br>(htmlHooks.replace)"])

				subgraph #domSerialize["domSerialize"]
					direction TB

					#jsdom(["JSDOM.serialize()"])
					#imageSizes(["画像<br>width/height<br>属性自動付与<br>(imageSizes)"])

					#jsdom --> #imageSizes
				end

				#beforeSerialize --> #domSerialize --> #afterSerialize --> #characterEntities --> #prettier --> #minifier --> #lineBreak --> #charset --> #replaceHook
			end

			subgraph #transpileCSS["addExtension"]
				direction TB

				#postcss(["トランスパイル<br>(PostCSS)"])
			end

			subgraph #transpileJS["addExtension"]
				direction TB

				#esbuild(["トランスパイル<br>(esbuild)"])
			end

			#html --> #transformHTML
			#pug --> #eleventy-plugin-pug(["Pugプラグイン<br>(eleventy-plugin-pug)"]) --> #transformHTML
			#css --> #transpileCSS
			#js --> #transpileJS
			#ts --> #transpileJS
		end

		subgraph #pathFormat["出力ファイルのパス変更<br>(pathFormat)"]
		end

		#eleventy --> #pathFormat
	end

カスタマイズ設定

addGlobalDataメソッドを利用することで、ビルド処理に必要な設定を上書きします。

| オプションID | 説明 | | ------------------- | ---------------------------------------------------- | | alias | パスのエイリアスを設定します。 | | outputCssDir | CSSの出力ディレクトリを設定します。 | | outputJsDir | JSの出力ディレクトリを設定します。 | | outputImgDir | 画像の出力ディレクトリを設定します。 | | imageSizes | 画像のwidth/height属性を自動付与します。 | | prettier | Prettierを有効にします。 | | minifier | Minifierを有効にします。 | | lineBreak | 改行コードを設定します。 | | charset | 文字コードを設定します。 | | characterEntities | 文字参照を変換します。 | | pathFormat | パスのフォーマットを設定します。 | | autoDecode | 開発用ローカルサーバーの自動デコードを有効にします。 | | ssi | 開発用ローカルサーバーのSSIの設定を行います。 | | htmlHooks | HTML処理のカスタマイズ用フックを設定します。 | | extensions | ファイル拡張子をカスタマイズします。 | | parserOptions | パーサのオプションを設定します。 |

詳細はコーディングガイドラインを確認してください。

htmlHooks

HTML処理の各段階でカスタム処理を挿入するためのフックを提供します。

| フックID | 説明 | | ----------------- | -------------------------------------------------------- | | beforeSerialize | DOM処理前のHTML文字列に対して処理を行います。 | | afterSerialize | DOM処理後のWindowオブジェクトに対して処理を行います。 | | replace | 最終出力前にHTML文字列とパス情報を使って処理を行います。 |

htmlHooks: {
  // DOM処理前のHTMLを処理
  beforeSerialize: (content, isServe) => {
    // isServe: 開発サーバーで実行中かどうか
    return content.replace(/特定の文字列/g, '置換後の文字列');
  },
  // DOM処理後にWindowオブジェクトを操作
  afterSerialize: (window, isServe) => {
    // isServe: 開発サーバーで実行中かどうか
    const elements = window.document.querySelectorAll('.target');
    elements.forEach(el => el.classList.add('modified'));
  },
  // 最終出力前に処理（パス情報も利用可能）
  replace: (content, paths, isServe) => {
    // isServe: 開発サーバーで実行中かどうか
    const { filePath, dirPath, relativePathFromBase } = paths;
    return content.replace(/{{relativePath}}/g, relativePathFromBase);
  }
}

その他、eleventyConfigインスタンスのプロパティやメソッドを用いてEleventyの設定を追加することで、ビルド処理をカスタマイズすることができます。

extensions

出力されるファイルの拡張子をカスタマイズします。

extensions: {
  html: 'php', // HTMLファイルをPHP拡張子で出力
}

現在サポートされている拡張子タイプ：

• html: HTMLファイルの拡張子（デフォルト: 'html'）

esbuildやRollupに関する設定、その他ディレクトリ構成の変更などは@d-zero/builder/11tyで行うのは現状難しいため、Eleventyの設定ファイルで一から設定することになります。または、Issueもしくはプルリクエスト変更可能なオプションをリクエストしてください。

ロードマップ

静的サイトもしくはCMSのテンプレートを素早く構築するため、利用技術についてこだわりがあるわけではありません。そのため、利用技術の変更や追加を行うことがあります。現状、Eleventy/esbuildを利用している理由はちょうどよかっただけです。

技術採用のポイント

• HTML/CSS/JSの切り離しが容易であること
• HTMLに余計な要素・属性・コードが挿入されないこと
• ビルド処理が高速であること

予定

• Eleventy以外の選択肢の検討