NativeWind v4 for Expo (React Native)

Non‑negotiables (v4)

• Use Tailwind CSS v3 and include

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

  in

  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"

  on

  babel-preset-expo

  .
• After any config change, restart Metro without cache:

  npx expo start --clear

  .

Quick start checklist

• 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.

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

  ).

package.json

"main": "expo-router/entry"

Implementation patterns

Build reusable components (recommended)

className

references/patterns.md

Style third‑party components (only when necessary)

remapProps

cssInterop

references/third-party-components.md

Dark mode + theming

useColorScheme

colorScheme.set()

vars()

references/theming-dark-mode.md

Safe area utilities

SafeAreaProvider

p-safe

pt-safe

SafeAreaProvider

Troubleshooting workflow (always in this order)

1. Start Expo without cache:

   npx expo start --clear

   .
2. Verify Tailwind CLI works by compiling your CSS entry file to an output file.
3. Confirm the “three paths” match:
   • CSS file exists

   • metro.config.js

     input

     points to it
   • your app imports it from the entry component
4. Confirm

   tailwind.config.js

   content

   globs include every directory that contains

   className

   strings.
5. Only then debug platform-specific behaviour (web bundler, Router, safe area, etc).

references/troubleshooting.md

THE EXACT PROMPT — NativeWind v4 config audit

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.