debug-nw
Debug a Nativewind v5 setup issue. Walks through common configuration problems with metro, babel, postcss, and dependencies.
About this skill
This AI agent skill provides a systematic approach to debugging Nativewind v5 configuration issues within a React Native project. It guides the agent through a series of checks, including verifying Nativewind, Tailwind CSS, and `react-native-css` versions, inspecting PostCSS and Metro configurations, and ensuring correct Babel plugin setup. The skill also checks for the presence of the `nativewind-env.d.ts` TypeScript declaration file. The skill is designed to help developers quickly pinpoint the root cause of common Nativewind setup problems, such as styles not applying, build errors, or incorrect `className` prop handling. By automating these checks, it saves time and reduces frustration often associated with diagnosing configuration-related bugs. Users would deploy this skill when their Nativewind v5 integration isn't behaving as expected, providing a structured diagnostic path to identify specific misconfigurations or missing dependencies that could be preventing Nativewind from functioning correctly.
Best use case
The primary use case for this skill is to troubleshoot and fix common setup and configuration errors when integrating or using Nativewind v5 in a React Native application. Developers struggling with initial Nativewind setup, unexpected styling issues, or build problems related to its tooling will benefit most by quickly identifying misconfigurations without manual file-by-file inspection.
Debug a Nativewind v5 setup issue. Walks through common configuration problems with metro, babel, postcss, and dependencies.
The user should expect to receive a detailed diagnosis of their Nativewind v5 configuration issues, identifying specific misconfigurations or missing dependencies, along with actionable steps to resolve them.
Practical example
Example input
My Nativewind v5 styles aren't applying, and I'm seeing 'className is not a valid prop' errors. Can you help debug my setup?
Example output
Upon checking your `package.json`, `tailwindcss` is at `v3.x` but `v4+` is required for Nativewind v5. Additionally, your `postcss.config.mjs` is using `tailwindcss` plugin instead of `@tailwindcss/postcss`. Please update Tailwind CSS to v4+ and correct your PostCSS configuration. Also, verify `nativewind/theme` is imported in your global CSS.
When to use this skill
- Nativewind v5 styles are not applying as expected in your React Native project.
- You encounter 'className is not a valid prop' or other build/runtime errors related to Nativewind v5.
- Setting up a new Nativewind v5 project and facing initial configuration hurdles.
- You suspect a mismatch in Nativewind, Tailwind CSS, or `react-native-css` versions or configurations.
When not to use this skill
- Debugging issues unrelated to Nativewind v5 configuration (e.g., general React Native bugs, core application logic).
- Working with Nativewind v4 or older versions, as this skill is specific to v5's configuration.
- When the problem is clearly a custom CSS styling issue or a component's internal logic, not a setup problem.
- If you require debugging for a JavaScript/TypeScript error that is not related to asset compilation or styling.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/debug-nw/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How debug-nw Compares
| Feature / Agent | debug-nw | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | easy | N/A |
Frequently Asked Questions
What does this skill do?
Debug a Nativewind v5 setup issue. Walks through common configuration problems with metro, babel, postcss, and dependencies.
How difficult is it to install?
The installation complexity is rated as easy. You can find the installation instructions above.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
Related Guides
AI Agents for Coding
Browse AI agent skills for coding, debugging, testing, refactoring, code review, and developer workflows across Claude, Cursor, and Codex.
Cursor vs Codex for AI Workflows
Compare Cursor and Codex for AI coding workflows, repository assistance, debugging, refactoring, and reusable developer skills.
Best AI Skills for Claude
Explore the best AI skills for Claude and Claude Code across coding, research, workflow automation, documentation, and agent operations.
SKILL.md Source
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`:
```javascript
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:
```css
@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()`:
```javascript
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.Related Skills
Go Production Engineering
You are a Go production engineering expert. Follow this system for every Go project — from architecture decisions through production deployment. Apply phases sequentially for new projects; use individual phases as needed for existing codebases.
Database Engineering Mastery
> Complete database design, optimization, migration, and operations system. From schema design to production monitoring — covers PostgreSQL, MySQL, SQLite, and general SQL patterns.
afrexai-code-reviewer
Enterprise-grade code review agent. Reviews PRs, diffs, or code files for security vulnerabilities, performance issues, error handling gaps, architecture smells, and test coverage. Works with any language, any repo, no dependencies required.
API Documentation Generator
Generate production-ready API documentation from endpoint descriptions. Outputs OpenAPI 3.0, markdown reference docs, and SDK quickstart guides.
bili-rs
Development skill for bili-rs, a Rust CLI tool for Bilibili (B站). Use when implementing features, fixing bugs, or extending the bilibili-cli-rust codebase. Provides architecture conventions, API endpoints, coding patterns, and project-specific constraints. Triggers on tasks involving adding CLI commands, calling Bilibili APIs, handling authentication, implementing output formatting, or working with the layered cli/commands/client/payloads architecture.
Puppeteer
Automate Chrome and Chromium with Puppeteer for scraping, testing, screenshots, and browser workflows.
pharaoh
Codebase knowledge graph with 23 development workflow skills. Query architecture, dependencies, blast radius, dead code, and test coverage via MCP. Requires GitHub App installation (read-only repo access) and OAuth authentication. Connects to external MCP server at mcp.pharaoh.so.
git-commit-helper
Generate standardized git commit messages following Conventional Commits format. Use this skill when the user asks to commit code, write a commit message, or create a git commit. Enforces team conventions for type prefixes, scope naming, message length, and breaking change documentation.
ask-claude
Delegate a task to Claude Code CLI and immediately report the result back in chat. Supports persistent sessions with full context memory. Safe execution: no data exfiltration, no external calls, file operations confined to workspace. Use when the user asks to run Claude, delegate a coding task, continue a previous Claude session, or any task benefiting from Claude Code's tools (file editing, code analysis, bash, etc.).
bnbchain-mcp
Interact with the BNB Chain Model Context Protocol (MCP) server. Blocks, contracts, tokens, NFTs, wallet, Greenfield, and ERC-8004 agent tools. Use npx @bnb-chain/mcp@latest or read the official skill page.
helius-phantom
Build frontend Solana applications with Phantom Connect SDK and Helius infrastructure. Covers React, React Native, and browser SDK integration, transaction signing via Helius Sender, API key proxying, token gating, NFT minting, crypto payments, real-time updates, and secure frontend architecture.
micropython-skills/sensor
MicroPython sensor reading — DHT11/22, BME280, MPU6050, ADC, ultrasonic HC-SR04, photoresistor, generic I2C sensors.