styling-nativewind-v4-expo

Expo での NativeWind v4

これは意図的に v4 を対象としたスキルです。レビュー時点で、公式サイトでは v5 はプレリリースとされています。v5／Tailwind v4 の設定は別の構成であり、これらのファイルをそのまま更新するものではありません。編集前にロックファイルを確認し、このスキルで依存関係のメジャーバージョンを明示してください。

設定を確立する

package.json とロックファイル、実際のアプリのエントリーポイント、Expo の設定、Babel の設定、Metro の設定、Tailwind の設定、CSS のエントリーポイントを確認します。Expo Router を使用しているか、従来のエントリーポイントを使用しているかを特定し、src/app、モノレポ、カスタムプロジェクトルートも考慮してください。

v4 の設定を連携させるには、references/expo-setup.md を参照してください。不変条件は次のとおりです。

• nativewind@^4 と tailwindcss@^3.4.17 を使用し、ネイティブ側の peer 依存関係はアプリの Expo SDK 経由で解決します。
• nativewind/preset を使用し、完全なユーティリティ文字列が記述されたすべてのソースを対象とする content glob を設定します。
• Tailwind v3 ディレクティブを使う CSS エントリーポイントを1つ用意し、Metro の withNativeWind 入力と実際のアプリのエントリーポイントの両方に接続します。
• Babel の presets に nativewind/babel を指定し、babel-preset-expo に jsxImportSource: "nativewind" を設定します。
• パッケージ名／モジュール名を覆い隠さず、nativewind/types を参照する nativewind-env.d.ts を用意します。

無関係な Metro ラッパー、Babel プラグイン、設定プラグイン、プロジェクトのモジュール形式は維持してください。正常に動作しているアプリの設定を丸ごと置き換えたり、互換性のない Reanimated／Worklets スタックを追加でインストールしたりしないでください。

役立つ順序でデバッグする

1. 解決された依存関係のメジャーバージョンと、実際に発生した最初のエラーを確認します。キャッシュをリセットしても、Tailwind v4／v3 の不一致は解消されません。
2. プロジェクトにインストールされている Tailwind v3 CLI で CSS エントリーポイントをコンパイルします。content glob、静的なクラス文字列、NativeWind プリセットを確認します。
3. CSS ファイル、Metro の入力、アプリケーションでのインポートが、同じファイルを参照していることを確認します。src/app/_layout.tsx を含め、実際の各配置場所からパスを計算します。
4. 必要な Babel／Metro の連携をマージし、npx expo start --clear で Metro を再起動します。
5. 各ターゲットプラットフォームで、明確なレイアウト、テキスト、色の変更を試してから、問題のあるコンポーネントをテストします。Web で正常に表示されても、ネイティブとの相互運用性が証明されたことにはなりません。

さらに詳しく診断するには、references/troubleshooting.md を参照してください。同梱の参照ファイルへのパスは、アプリのディレクトリではなく、このスキルのディレクトリを基準に解決してください。

コンポーネントを構築する

スキャナーが検出できない動的なクラス名の構築は避け、リテラルなバリアントマップを使用します。型付きコンポーネント、明示的なオーバーライドのセマンティクス、アクセシブルな Pressable コンテンツについては、references/patterns.md を参照してください。クラス文字列を連結しても、競合するユーティリティのうち最後のものが必ず優先されるとは限りません。

コンポーネントで remapProps または cssInterop が必要な場合に限り、references/third-party-components.md を使用してください。相互運用性の設定はレンダーのたびに行わず、一度だけ行ってください。v4 のカラー・スキーム API と CSS 変数 API については、references/theming-dark-mode.md を参照してください。

セーフエリアプロバイダーを追加する前に、既存のものを確認してください。Expo Router は通常、ルートの統合を提供します。独立したネイティブルートやモーダルの境界では、個別のプロバイダーが必要になる場合があります。プロバイダー数を普遍的なルールとして扱わず、実際のインセット、入れ子になったナビゲーション、回転時の挙動を確認してください。

検証して報告する

プロジェクトの型チェックと Expo の依存関係チェックを実行し、実際のターゲットをコンパイル／バンドルします。利用可能な環境では、ネイティブおよび Web の表示も確認してください。ダークモード、無効／押下状態、フォントの拡大縮小、セーフエリア、変更の影響を受けるサードパーティ製コンポーネントを確認します。解決された依存関係のバージョン、変更したファイル、実際にテストしたプラットフォームを報告してください。静的な設定の確認は、デバイスでのテストではありません。

参考資料

2026-09-13 に、NativeWind のインストール とカスタムコンポーネントを参照してレビューしました。競合を任意でマージする場合、tailwind-merge は、Tailwind v3 のユーザーに v2.6.0 系を明示的に案内しています。