styling-nativewind-v4-expo

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

NativeWind v4 for Expo (React Native)

适用于Expo（React Native）的NativeWind v4

Non‑negotiables (v4)

必须遵守的规则（v4版本）

Use Tailwind CSS v3 and include

presets: [require("nativewind/preset")]

tailwind.config.js

Keep exactly one Tailwind entry CSS file (commonly

global.css

) and keep its path consistent across:

metro.config.js

→

withNativeWind(..., { input: "./global.css" })

your app entry →

import "./global.css"

(or

import "../global.css"

from

app/_layout.tsx

)

Keep

nativewind/babel

in Babel
presets
and set

jsxImportSource: "nativewind"

babel-preset-expo

After any config change, restart Metro without cache:
```
npx expo start --clear
```
.

使用Tailwind CSS v3，并在

tailwind.config.js

中添加

presets: [require("nativewind/preset")]

。

仅保留一个Tailwind入口CSS文件（通常为
```
global.css
```
），并确保其路径在以下位置保持一致：
- ```
metro.config.js
```
  →
```
withNativeWind(..., { input: "./global.css" })
```
- 应用入口文件 →
```
import "./global.css"
```
  （或从
```
app/_layout.tsx
```
  中导入
```
import "../global.css"
```
  ）

在Babel的

presets

中保留

nativewind/babel

，并在

babel-preset-expo

上设置

jsxImportSource: "nativewind"

。

任何配置变更后，清除缓存重启Metro：
```
npx expo start --clear
```
。

Quick start checklist

快速启动检查清单

Copy/paste and tick off:

Install deps (NativeWind + Tailwind + peers). See
```
references/expo-setup.md
```
.
Create/verify
```
tailwind.config.js
```
(content globs +
```
nativewind/preset
```
).
Create/verify
```
global.css
```
with Tailwind directives.
Create/verify
```
babel.config.js
```
(jsxImportSource +
```
nativewind/babel
```
).
Create/verify
```
metro.config.js
```
(wrap config with
```
withNativeWind
```
, set
```
input
```
).
If targeting web, set
```
app.json
```
→
```
expo.web.bundler = "metro"
```
.

If TypeScript, add

nativewind-env.d.ts

with

/// <reference types="nativewind/types" />

Start with cache cleared and validate on-device + web:
```
npx expo start --clear
```
.
Validate with an obvious “smoke test” screen: background colour + centred text.

复制粘贴并逐一勾选：

安装依赖（NativeWind + Tailwind + 对等依赖）。详见
```
references/expo-setup.md
```
。
创建/验证
```
tailwind.config.js
```
（内容匹配规则 +
```
nativewind/preset
```
）。
创建/验证包含Tailwind指令的
```
global.css
```
。
创建/验证
```
babel.config.js
```
（配置jsxImportSource +
```
nativewind/babel
```
）。
创建/验证
```
metro.config.js
```
（用
```
withNativeWind
```
包装配置，设置
```
input
```
路径）。
如果面向Web平台，在
```
app.json
```
中设置
```
expo.web.bundler = "metro"
```
。

如果使用TypeScript，添加

nativewind-env.d.ts

并写入

/// <reference types="nativewind/types" />

。

清除缓存启动应用，并在设备端和Web端验证：
```
npx expo start --clear
```
。
通过一个直观的“冒烟测试”页面验证：设置背景色 + 居中文字。

Project type selection

项目类型选择

Expo Router: entry is usually
```
app/_layout.tsx
```
→ import CSS there (relative path is typically
```
../global.css
```
).
Classic: entry is usually
```
App.tsx
```
→ import CSS there (
```
./global.css
```
).

If unsure, search

package.json

for

"main": "expo-router/entry"

Expo Router：入口通常为
```
app/_layout.tsx
```
→ 在此处导入CSS（相对路径通常为
```
../global.css
```
）。
传统项目：入口通常为
```
App.tsx
```
→ 在此处导入CSS（
```
./global.css
```
）。

若不确定，可在

package.json

中搜索

"main": "expo-router/entry"

来判断。

Implementation patterns

实现模式

Build reusable components (recommended)

构建可复用组件（推荐）

className

, merge defaults, and optionally use a class-variance helper.

Read:

references/patterns.md

接收

className

属性，合并默认样式，可选择使用类变体辅助工具。

详见：

references/patterns.md

Style third‑party components (only when necessary)

为第三方组件设置样式（仅必要时使用）

Use

remapProps

(multiple style props) or

cssInterop

(map a class prop to a style prop).

Read:

references/third-party-components.md

使用

remapProps

（处理多个样式属性）或

cssInterop

（将类属性映射到样式属性）。

详见：

references/third-party-components.md

Dark mode + theming

深色模式 + 主题定制

Use

useColorScheme

colorScheme.set()

and CSS variables via

vars()

Read:

references/theming-dark-mode.md

使用

useColorScheme

colorScheme.set()

以及通过

vars()

实现的CSS变量。

详见：

references/theming-dark-mode.md

Safe area utilities

安全区域工具

On Expo Router, do not add your own

SafeAreaProvider

(Router already does). Use

p-safe

pt-safe

, etc.

If you are not using Expo Router, wrap the root with

SafeAreaProvider

在Expo Router中，不要自行添加

SafeAreaProvider

（Router已内置该功能）。使用

p-safe

、

pt-safe

等工具类。

若未使用Expo Router，请在根组件外层包裹

SafeAreaProvider

。

Troubleshooting workflow (always in this order)

故障排查流程（请严格按此顺序执行）

Start Expo without cache:
```
npx expo start --clear
```
.
Verify Tailwind CLI works by compiling your CSS entry file to an output file.
Confirm the “three paths” match:
- CSS file exists
- ```
metro.config.js
```
```
input
```
  points to it
- your app imports it from the entry component
Confirm
```
tailwind.config.js
```
```
content
```
globs include every directory that contains
```
className
```
strings.
Only then debug platform-specific behaviour (web bundler, Router, safe area, etc).

Read:

references/troubleshooting.md

清除缓存启动Expo：
```
npx expo start --clear
```
。
编译CSS入口文件到输出文件，验证Tailwind CLI是否正常工作。
确认“三个路径”一致：
- CSS文件存在
- ```
metro.config.js
```
  中的
```
input
```
  路径指向该CSS文件
- 应用入口组件正确导入该CSS文件
确认
```
tailwind.config.js
```
中的
```
content
```
匹配规则包含所有包含
```
className
```
字符串的目录。
仅在完成上述步骤后，再排查平台特定问题（Web打包工具、Router、安全区域等）。

详见：

references/troubleshooting.md

THE EXACT PROMPT — NativeWind v4 config audit

精确检查指令 — NativeWind v4配置审计

Use this prompt to perform a deterministic audit of an existing repo:

You are auditing an Expo React Native repo for NativeWind v4 correctness.

1) Identify whether the project uses Expo Router (app/ directory + package.json main = expo-router/entry) or classic App.tsx.
2) Check and report on:
   - tailwind.config.js: presets + content globs
   - global.css: Tailwind directives exist
   - babel.config.js: jsxImportSource nativewind + nativewind/babel in presets; preserve any existing required plugins
   - metro.config.js: withNativeWind wrapper; input path matches the CSS file
   - app.json: web bundler metro when web is used
   - TypeScript: nativewind-env.d.ts present and correctly named
3) For every issue, propose the minimal diff needed to fix it.
4) End by listing the exact commands to restart Metro and validate the fix.

使用以下指令对现有仓库进行确定性审计：

You are auditing an Expo React Native repo for NativeWind v4 correctness.

1) Identify whether the project uses Expo Router (app/ directory + package.json main = expo-router/entry) or classic App.tsx.
2) Check and report on:
   - tailwind.config.js: presets + content globs
   - global.css: Tailwind directives exist
   - babel.config.js: jsxImportSource nativewind + nativewind/babel in presets; preserve any existing required plugins
   - metro.config.js: withNativeWind wrapper; input path matches the CSS file
   - app.json: web bundler metro when web is used
   - TypeScript: nativewind-env.d.ts present and correctly named
3) For every issue, propose the minimal diff needed to fix it.
4) End by listing the exact commands to restart Metro and validate the fix.