Hugo + Tailwind CSS v4 のスターターテンプレートを作ってみた

そもそも Hugo + Tailwind が最強な理由

Hugo が爆速すぎる

Hugo は Go 製の静的サイトジェネレーターで、ビルドが異常に速いです。

SSG	1000ページのビルド時間
Hugo	約1秒
Next.js (SSG)	30秒〜数分
Gatsby	1〜3分
Jekyll	30秒〜1分

桁が違います。記事が100本あろうが500本あろうが、Hugo なら一瞬でビルドが終わる。hugo server のホットリロードもほぼ一瞬なので、Markdown を保存した瞬間にブラウザに反映されます。開発体験がめちゃくちゃ良い。

Tailwind CSS がちょうどいい

「CSS 書くの面倒だけど、フレームワーク入れるほどでもない」という人に Tailwind はぴったりです。

• クラスを並べるだけでデザインが決まる。CSS ファイルと HTML を行き来しなくていい
• 未使用CSSが自動で消えるので、最終的な CSS は使ってるぶんだけ。数KBで済む
• v4 からは CSS ファイルだけで設定が完結する。tailwind.config.js は不要になった

組み合わせると何がいいのか

項目	Hugo + Tailwind	Next.js + CSS Modules	WordPress
ビルド速度	秒	分	— (動的)
ランタイム	なし（静的HTML）	Node.js サーバー	PHP + MySQL
ホスティング費用	無料（Netlify）	Vercel 無料枠 or 有料	月額数百円〜
セキュリティ	攻撃面ゼロ（静的）	サーバー依存	プラグイン脆弱性リスク
学習コスト	HTML + Markdown	React + JSX	PHP + テーマ構造

要するに、ブログや個人サイトに React は要らない。静的 HTML を爆速で生成して、Tailwind でサクッと見た目を整えて、無料でデプロイする。それだけでいい。

Hugo + Tailwind はこの「それだけでいい」を最短で実現できる組み合わせです。

忙しい人向けまとめ

「Hugo + Tailwind v4 使いたいけど、ビルド周りだるくない？」って思ってる人向けです。

やったこと: Hugo の中に Tailwind v4 のビルドを全部突っ込んだ。

何がうれしいの？: npm run dev と hugo server を2つターミナルで走らせるとか、concurrently で並列実行するとか、そういうの全部いらない。hugo server だけで全部動く。

どうやって？: Hugo Pipes っていう組み込み機能が PostCSS 呼べるので、そこに Tailwind v4 を噛ませた。

使い方は？:

git clone && npm install && hugo server

以上。 3コマンドで Tailwind v4 入りの Hugo サイトが手元で動く。Netlify にデプロイしたければ README のボタンぽちーで終わり。

詳しく知りたい人は↓読んでください。

作ったもの

Hugo + Tailwind CSS v4 のスターターテンプレートを作りました。

最大の特徴は、hugo コマンドだけでTailwind v4のCSSビルドが完結すること。 npm run build や並列プロセスは不要です。

• Demo: https://cerulean-fox-8d3d8b.netlify.app/
• GitHub: https://github.com/i-cezuki/hugo-tailwind-starter

なぜ作ったか

Hugo + Tailwind の既存スターターは、大半が以下のどちらかです。

1. npm run dev と hugo server を並列実行する構成
2. Tailwind v3 ベースで v4 に対応していない

Hugo には Hugo Pipes という組み込みのアセットパイプラインがあり、PostCSS を直接呼べます。これを使えば Tailwind のビルドを Hugo 内で完結できるのに、活用されていないケースが多いと感じました。

仕組み

アーキテクチャ

assets/css/main.css
  │  @import "tailwindcss"     ← v4 のCSS-first設定
  │  @theme { ... }            ← カスタムカラー
  ↓
baseof.html: css.PostCSS → minify → fingerprint
  ↓
<link rel="stylesheet" href="/css/main.xxxxx.min.css" integrity="sha256-...">

Hugo Pipes が PostCSS（Tailwind v4）を呼び出し、CSSのミニファイ・フィンガープリント・SRI を自動で付与します。

実装のポイント

baseof.html（CSS読み込み部分）:

{{ with resources.Get "css/main.css" }}
{{ $css := . | css.PostCSS | minify | fingerprint }}
<link rel="stylesheet" href="{{ $css.RelPermalink }}" integrity="{{ $css.Data.Integrity }}">
{{ end }}

package.json:

{
  "name": "hugo-tailwind-starter",
  "private": true,
  "devDependencies": {
    "@tailwindcss/postcss": "^4.0.0",
    "postcss-cli": "^11.0.0"
  }
}

postcss.config.js:

module.exports = {
  plugins: {
    "@tailwindcss/postcss": {}
  }
}

assets/css/main.css:

@import "tailwindcss";

@source "../../layouts";
@source "../../content";

@custom-variant dark (&:where(.dark, .dark *));

@theme {
  --color-primary: #3b82f6;
  --color-secondary: #64748b;
  --color-accent: #f59e0b;
}

Tailwind v4 は CSS ファイルからのモジュールグラフでクラスを検出するため、Hugo の layouts/ と content/ を @source で明示的に指定しています。

機能一覧

機能	実装方法
ダークモード	class ベース + localStorage 保持 + システム設定検出
クライアントサイド検索	Hugo の JSON 出力 + fetch + filter（外部ライブラリなし）
SEO	OGP / Twitter Card / JSON-LD 構造化データ / RSS / サイトマップ
パフォーマンス	CSS フィンガープリント + SRI / 画像 loading="lazy" / fetchpriority="high"
Netlify デプロイ	netlify.toml でビルド設定完結。ワンクリックデプロイ対応

使い方

git clone https://github.com/i-cezuki/hugo-tailwind-starter.git
cd hugo-tailwind-starter
npm install
hugo server

これだけで http://localhost:1313 にサイトが立ち上がります。

Netlify へのデプロイ

GitHub の README にある「Deploy to Netlify」ボタンをクリックするだけです。netlify.toml にビルド設定が含まれているので、追加設定は不要です。

ダークモードの実装

Tailwind v4 では @custom-variant でダークモードを定義します。

@custom-variant dark (&:where(.dark, .dark *));

baseof.html でページ描画前にテーマを適用し、FOUC（Flash of Unstyled Content）を防いでいます。

<script>
  (function() {
    var theme = localStorage.getItem('theme');
    if (theme === 'dark' || (!theme && window.matchMedia('(prefers-color-scheme: dark)').matches)) {
      document.documentElement.classList.add('dark');
    }
  })();
</script>

クライアントサイド検索

外部ライブラリを使わず、Hugo の JSON 出力を fetch して検索しています。

fetch('/index.json')
  .then(function(r) { return r.json(); })
  .then(function(d) { data = d; });

検索インデックスは Hugo のテンプレート（layouts/_default/index.json）で生成しています。

個人ブログとして普通に使えます

「スターターテンプレートって結局デモ止まりでしょ？」と思うかもしれませんが、これはそのまま個人ブログとして運用できます。ダークモード、検索、タグ、SEO、RSS — ブログに必要なものは一通り入っています。記事を書くときは content/blog/ に Markdown を追加するだけ。

ホスティングどうするの問題

個人ブログのホスティングは選択肢がいろいろありますが、正直 Netlify が一番楽で安いです。

サービス	月額	SSL	独自ドメイン	デプロイ方法
Netlify	無料	自動（Let's Encrypt）	OK	git push で自動
Xserver 静的サイト	無料枠あり / 有料プランは月額990円〜	対応	OK	手動アップロード or FTP
S3 + CloudFront	月数十円〜（従量課金）	ACM で無料だが設定が手間	OK	aws cli でデプロイ or CI構築
GitHub Pages	無料	自動	OK	GitHub Actions 構築が必要

Xserver との比較

Xserver の静的サイトホスティングでも動きますが、Hugo のビルド成果物を手動でアップロードするか FTP で転送する必要があります。Netlify なら git push するだけで自動ビルド＆デプロイ。CI/CD を自分で組む必要がありません。

S3 + CloudFront との比較

AWS でやろうとすると「S3 バケット作って、CloudFront ディストリビューション作って、ACM で証明書取って、Route 53 でドメイン設定して、GitHub Actions でデプロイパイプライン組んで……」と、ブログ書き始める前にインフラで1日溶けます。費用も従量課金なので地味に請求が来る。

Netlify なら netlify.toml 1ファイルで全部終わります。無料で。

結論

個人ブログ規模なら Netlify の無料枠（100GB/月、ビルド300分/月）を超えることはまずないです。独自ドメインも SSL も無料。ブログを書くことに集中したいなら、インフラで悩む時間がもったいない。

ハマったポイント

resources.PostCSS → css.PostCSS

Hugo v0.128 以降、PostCSS のパイプ関数が resources.PostCSS から css.PostCSS に変更されています。古い記事やスターターを参考にすると動かないので注意してください。

postcss-cli が必要

Hugo Pipes の css.PostCSS は内部で PostCSS CLI を呼び出します。@tailwindcss/postcss だけでは動かず、postcss-cli も devDependencies に必要です。

まとめ

• Hugo Pipes を使えば Tailwind v4 のビルドを Hugo 内で完結できる
• npm run build のような追加スクリプトは不要
• Netlify へのワンクリックデプロイにも対応

フィードバックや Star をいただけると励みになります。

GitHub: https://github.com/i-cezuki/hugo-tailwind-starter