tailwind-capacitor

Capacitor アプリでの Tailwind CSS

使用する場面

次の場合に使用します：

• Capacitor アプリに Tailwind を追加する場合（Vite、Angular、Next の静的エクスポートなど）
• Tailwind v3 から v4 にアップグレードする場合、または v4 をインストールしてもスタイルが適用されない場合
• tailwind.config.js の変更が反映されない場合（v4 は CSS ファーストです）
• 古い iOS デバイスで色やグラデーションが壊れたり、透明になったりする場合
• セーフエリア、ダークモード、プラットフォーム固有のユーティリティ、またはタッチターゲットのユーティリティを使用する場合

次の場合は使用しないでください：

• Konsta UI のセットアップ／コンポーネント：konsta-ui
• Ionic コンポーネントおよび --ion-* 変数：ionic-design
• SystemBars／Android のエッジツーエッジ／ステータスバープラグイン：safe-area-handling
• キーボードで入力欄が隠れる場合：capacitor-keyboard
• フレームワークへの Capacitor の追加：framework-to-capacitor

バージョンに関する情報（2026 年 10 月）

• tailwindcss 4.x は latest（4.3.x）で、3.4.x は v3-lts です。
• v4 は CSS で設定します。@config "./tailwind.config.js"; を追加しない限り、tailwind.config.js は読み込まれません。
• v4 の対象は Safari 16.4 以降、Chrome 111 以降、Firefox 128 以降です（@property、color-mix()、カスケードレイヤー、oklch を使用します）。
• Capacitor 8 は iOS 15 以降、Capacitor 9 は iOS 16 以降に対応しています。WKWebView はデバイスの Safari バージョンを使用します。**iOS 15.x～16.3 のデバイスでは v4 のスタイルが正しく表示されません。**Android System WebView は自動更新されるため、通常は Chrome 111 以降の条件を満たします（Capacitor 9 の minSdk は 26 です）。

判断：iOS のデプロイメントターゲット（または実際のユーザーベース）に iOS 16.4 未満が含まれる場合は、Tailwind 3.4 を使い続けるか、最小 OS バージョンを引き上げるかをユーザーに確認してください。v4 を黙ってリリースしないでください。

ワークフロー

1. 調査：npm ls tailwindcss、tailwind.config.*、postcss.config.*、バンドラー設定、メイン CSS ファイル、ios/App/App.xcodeproj の IPHONEOS_DEPLOYMENT_TARGET、Ionic または Konsta の有無を確認します。
2. 新規インストール（以下を参照）またはアップグレード：references/v3-to-v4.md。
3. モバイル向けユーティリティ（セーフエリア、プラットフォームバリアント、タッチ、ダークモード）：references/mobile-patterns.md。
4. 検証（以下を参照）。

関連するトピックを扱う場合にのみ、参照ファイルを読み込んでください。

インストール（Vite：React、Vue、Svelte、Solid）

npm i tailwindcss @tailwindcss/vite

// vite.config.ts
import { defineConfig } from 'vite';
import tailwindcss from '@tailwindcss/vite';
export default defineConfig({ plugins: [tailwindcss() /* + framework plugin */] });

/* src/styles.css */
@import "tailwindcss";

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

@theme {
  --color-brand: oklch(0.55 0.2 265);
  --font-sans: system-ui, -apple-system, "Roboto", sans-serif;
}

@utility pt-safe { padding-top: env(safe-area-inset-top); }
@utility pb-safe { padding-bottom: env(safe-area-inset-bottom); }
@utility px-safe { padding-left: env(safe-area-inset-left); padding-right: env(safe-area-inset-right); }

その他のツールチェーン：PostCSS（Angular、webpack、Next）では npm i tailwindcss @tailwindcss/postcss を実行し、postcss.config.mjs に { plugins: { "@tailwindcss/postcss": {} } } を設定します。単体で使う場合は @tailwindcss/cli を使用します。Angular CLI 17 以降は .postcssrc.json を読み込みます。

// main.ts: platform class for ios:/android: variants
import { Capacitor } from '@capacitor/core';
document.documentElement.classList.add(`plt-${Capacitor.getPlatform()}`); // plt-ios | plt-android | plt-web

ビューポートメタに viewport-fit=cover を追加してください。追加しないと、セーフエリアユーティリティの値が 0 になります。

注意点

• v4 ではコンテンツが自動検出されます（.gitignore の設定が反映されます）。node_modules 内またはプロジェクトルートの外にあるクラスには @source "../path"; が必要です。動的なクラス名（`bg-${color}-500`）は生成されません。完全なクラス文字列に対応付けてください。
• v4 の hover: は (hover: hover) を満たすデバイスでのみ適用されるため、タッチデバイスでホバー状態が固定される問題はデフォルトで解決されています。押下時のフィードバックには active: を使用してください。
• v4 ではデフォルトが変更されています。ボーダーの色は currentColor、ring は 1px になり、shadow-sm／shadow と rounded-sm／rounded の段階も変更され、outline-none は outline-hidden になりました。アップグレードツールで大半は名前が変更されますが、見た目を確認してください。
• Ionic と Tailwind を併用する場合：Preflight は Ionic のタイポグラフィをリセットします。Preflight を使わずに Tailwind をインポートするか（@layer theme, base, components, utilities; @import "tailwindcss/theme.css" layer(theme); @import "tailwindcss/utilities.css" layer(utilities);）、Tailwind の後に Ionic CSS を読み込んでください。
• Konsta UI v5 は konsta/<fw>/theme.css を通じて Tailwind のテーマ部分をすでにインポートしています。セットアップを重複させず、konsta-ui の手順に従ってください。
• 全画面レイアウトに 100vh を使用しないでください。h-dvh（v4 には dvh／svh／lvh ユーティリティがあります）またはフレックスシェルを使用してください。
• Android WebView < 140 ではセーフエリアの env() が 0 として返されます。Capacitor 8 の SystemBars は --safe-area-inset-* を挿入します。Android で確実に動作させるには、@utility pt-safe { padding-top: var(--safe-area-inset-top, env(safe-area-inset-top)); } を使用してください（safe-area-handling を参照）。

検証

1. npm run build が成功し、ビルドされた CSS にユーティリティが含まれていることを確認します：grep -c "pt-safe" dist/assets/*.css。
2. npx cap sync を実行し、次の環境で動作を確認します：サポート対象の最も古い iOS バージョン（色、グラデーション、シャドウが正しく表示されることを確認）、現行の iPhone、Android 15/16。
3. ダークモードのクラスと OS の外観設定を切り替え、<html class> を調べて ios:／android: バリアントを確認します。
4. アップグレード後に古い設定が残っていないことを確認します：grep -rn "@tailwind base\|@tailwind components\|@tailwind utilities\|require('tailwindcss')" src postcss.config.* 2>/dev/null が何も返さないこと。

エラー処理

エラー／症状	原因	解決方法
[postcss] It looks like you're trying to use tailwindcss directly as a PostCSS plugin. The PostCSS plugin has moved to a separate package	v4 で v3 形式の PostCSS 設定を使用しています	@tailwindcss/postcss（または @tailwindcss/vite）を使用します
スタイルがまったく適用されない	@import "tailwindcss" またはバンドラープラグインがありません	両方を追加します
@apply で Cannot apply unknown utility class が発生する	カスタムクラスが @utility で定義されていないか、CSS モジュール／Vue の <style> にテーマ参照がありません	@utility で定義します。スコープ付きスタイルに @reference "../styles.css"; を追加します
tailwind.config.js のテーマ変更が反映されない	v4 は JS 設定ファイルを自動で読み込みません	@theme に移行するか、@config を追加します
一部の iPhone で色が透明になる／表示されない	iOS < 16.4 は v4 が使用する機能に対応していません	最小 iOS バージョンを引き上げるか、3.4 を使い続けます
dark: が OS の設定に従い、切り替えを無視する	デフォルトのダークモードバリアントはメディアベースです	@custom-variant dark (&:where(.dark, .dark *)); を追加します
アップグレードツールが Node を要求して失敗する	@tailwindcss/upgrade には Node 20 以降が必要です	Node をアップグレードします（いずれにせよ Capacitor 9 には 24 以降が必要です）

リソース

• Tailwind v4 のインストール（Vite）：https://tailwindcss.com/docs/installation/using-vite
• アップグレードガイド：https://tailwindcss.com/docs/upgrade-guide
• テーマ変数：https://tailwindcss.com/docs/theme
• ブラウザーのサポート：https://tailwindcss.com/docs/compatibility
• ダークモード：https://tailwindcss.com/docs/dark-mode