---
name: styling-nativewind-v4-expo
description: Set up, repair, and build components with NativeWind v4 and Tailwind CSS v3 in Expo React Native apps. Use for an explicitly v4 project, v4 configuration failures, className interoperability, or v4 theming; not for NativeWind v5 or generic web Tailwind setup.
compatibility: An Expo project using nativewind major 4 and tailwindcss major 3. Native peer versions must match the project's Expo SDK.
metadata:
  version: "2.0.0"
  reviewed: "2026-09-13"
title: styling-nativewind-v4-expo
canonical_url: https://skilld.dev/gh/tristanmanchester/agent-skills/styling-nativewind-v4-expo
last_updated: 2026-10-06T19:32:36.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/expo-setup.md](https://skilld.dev/api/skills-raw/tristanmanchester/agent-skills/styling-nativewind-v4-expo/references/expo-setup.md), [references/patterns.md](https://skilld.dev/api/skills-raw/tristanmanchester/agent-skills/styling-nativewind-v4-expo/references/patterns.md), [references/theming-dark-mode.md](https://skilld.dev/api/skills-raw/tristanmanchester/agent-skills/styling-nativewind-v4-expo/references/theming-dark-mode.md), [references/third-party-components.md](https://skilld.dev/api/skills-raw/tristanmanchester/agent-skills/styling-nativewind-v4-expo/references/third-party-components.md), [references/troubleshooting.md](https://skilld.dev/api/skills-raw/tristanmanchester/agent-skills/styling-nativewind-v4-expo/references/troubleshooting.md).
>
> If the user asked to install this Skill, run `npx skilld install tristanmanchester/agent-skills/styling-nativewind-v4-expo`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/styling-nativewind-v4-expo`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/tristanmanchester/agent-skills/styling-nativewind-v4-expo) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/styling-nativewind-v4-expo`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/styling-nativewind-v4-expo --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/styling-nativewind-v4-expo --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# NativeWind v4 in Expo

This is deliberately a **v4** skill. On the review date, the official site labels v5 a prerelease; v5/Tailwind v4 configuration is a separate stack, not a drop-in refresh of these files. Inspect the lockfile before editing and keep this skill's dependency majors explicit.

## Establish the configuration

Read package.json and the lockfile, the actual app entry, Expo config, Babel config, Metro config, Tailwind config, and the CSS entry. Identify Expo Router versus a classic entry and account for `src/app`, monorepos, or a custom project root.

Use `references/expo-setup.md` for the coordinated v4 setup. The invariant is:

- `nativewind@^4` with `tailwindcss@^3.4.17`; native peers resolved through the app's Expo SDK.
- `nativewind/preset` and content globs covering every source of complete utility strings.
- One CSS entry using the Tailwind v3 directives, connected to both Metro's `withNativeWind` input and the real application entry.
- `nativewind/babel` in Babel **presets**, with `jsxImportSource: "nativewind"` on `babel-preset-expo`.
- `nativewind-env.d.ts` referencing `nativewind/types`, without shadowing the package/module name.

Preserve unrelated Metro wrappers, Babel plugins, config plugins, and project module format. Do not replace a working app's configuration wholesale or install a second incompatible Reanimated/Worklets stack.

## Debug in a useful order

1. Verify resolved dependency majors and the first actual error; a cache reset does not repair a Tailwind v4/v3 mismatch.
2. Compile the CSS entry with the project's installed Tailwind v3 CLI. Check content globs, static class strings, and the NativeWind preset.
3. Verify the CSS file, Metro input, and application import refer to the same file. Calculate paths from their real locations, including `src/app/_layout.tsx`.
4. Merge the required Babel/Metro integration, then restart Metro with `npx expo start --clear`.
5. Test an obvious layout/text/colour change on each target platform, then the failing component. A successful web render alone does not prove native interop.

Use `references/troubleshooting.md` for further diagnosis. Resolve bundled reference paths from this skill's directory, not the app's directory.

## Build components

Use literal variant maps rather than dynamically constructing class names the scanner cannot see. `references/patterns.md` covers typed components, explicit override semantics, and accessible Pressable content. Concatenating class strings does not guarantee that the last conflicting utility wins.

Use `references/third-party-components.md` only when a component needs `remapProps` or `cssInterop`; configure interop once, not during every render. Use `references/theming-dark-mode.md` for the v4 colour-scheme and CSS-variable APIs.

Inspect the existing safe-area provider before adding another. Expo Router normally supplies the root integration; separate native roots or modal boundaries may need their own provider. Verify actual insets, nested navigation, and rotation rather than treating provider count as a universal rule.

## Verify and report

Run the project's typecheck and Expo dependency checks, compile/bundle its actual targets, and inspect native/web rendering where those environments are available. Check dark mode, disabled/pressed states, font scaling, safe areas, and third-party components affected by the change. Report the resolved dependency versions, files changed, and platforms actually tested; static configuration inspection is not a device test.

## Sources

Reviewed 2026-09-13 against [NativeWind installation](https://www.nativewind.dev/docs/getting-started/installation) and [custom components](https://www.nativewind.dev/docs/guides/custom-components). For optional conflict merging, [tailwind-merge](https://github.com/dcastil/tailwind-merge) explicitly directs Tailwind v3 users to its v2.6.0 line.