Nativewind debug-nw

Name: debug-nw
Author: nativewind

Debug a Nativewind v5 setup issue. Walks through common configuration problems with metro, babel, postcss, and dependencies.

install

source · Clone the upstream repo

git clone https://github.com/nativewind/nativewind

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/nativewind/nativewind "$T" && mkdir -p ~/.claude/skills && cp -r "$T/.claude/skills/debug-nw" ~/.claude/skills/nativewind-nativewind-debug-nw && rm -rf "$T"

manifest: .claude/skills/debug-nw/SKILL.md

1. Version check

Is
```
nativewind
```
at v5.x? (
```
package.json
```
)
Is
```
react-native-css
```
installed as a peer dependency? Must be
```
^3.0.1
```
Is
```
tailwindcss
```
v4+? Must be
```
>4.1.11
```
Is
```
@tailwindcss/postcss
```
installed?

2. PostCSS config

Nativewind v5 uses Tailwind CSS v4's PostCSS plugin. Check for

postcss.config.mjs

export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

Common mistake: Using Tailwind v3's

tailwindcss

PostCSS plugin instead of

@tailwindcss/postcss

3. CSS entry file

Check that the global CSS file imports the nativewind theme:

@import "tailwindcss";
@import "nativewind/theme";

Common mistake: Missing

@import "nativewind/theme"

— this provides RN-specific utilities.

4. Metro config

Check

metro.config.js

for

withNativewind()

const { withNativewind } = require("nativewind/metro");
module.exports = withNativewind(config);

Common mistake: Using

withNativeWind

(capital W) — deprecated.

5. Babel config

Check that the babel plugin is configured. The react-native-css babel plugin should be active (this is handled by

withNativewind

in metro config, but verify).

6. TypeScript

Check for

nativewind-env.d.ts

in project root — should be auto-generated. If missing, the

withNativewind

metro config may not be running.

7. Common symptoms

"className is not a valid prop": Babel plugin not active — check metro config
Styles not applying: CSS file not imported, or PostCSS not processing
Build errors with Tailwind: Wrong Tailwind version (needs v4+)
Runtime errors about react-native-css: Missing peer dependency

Approach

Ask the user what symptom they're seeing, then check the relevant configs. Read their actual files to diagnose rather than guessing.