OpenParable
Skip to content
← Back to skills

Debug Nw

Testing & Quality
debug-nw

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

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
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 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.