Debug Nw
Testing & Qualitydebug-nwDebug Nw is an Agent Skill for testing & quality published in the nativewind/nativewind repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Debug a Nativewind v5 setup issue. Walks through common configuration problems with metro, babel, postcss, and dependencies.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/nativewind/nativewind/blob/HEAD/.claude/skills/debug-nw/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/debug-nw, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
You are helping debug a Nativewind v5 configuration issue. Walk through these checks systematically.
1. Version check
- Is
nativewindat v5.x? (package.json) - Is
react-native-cssinstalled as a peer dependency? Must be^3.0.1 - Is
tailwindcssv4+? Must be>4.1.11 - Is
@tailwindcss/postcssinstalled?
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.