migrate-to-v5

What this skill does

# Migrate to gluestack-ui v5

This skill migrates any gluestack-ui project to v5, regardless of the starting version. gluestack-ui v5 runs on **Tailwind CSS v4** (CSS-first, no `tailwind.config.js`) with two supported styling engines:

| Engine | Tailwind | Platforms | When to choose |
|---|---|---|---|
| **NativeWind v5** | v4 | Expo, RN CLI, Next.js* | Recommended default |
| **UniWind** | v4 | Expo only | No PostCSS build step, simpler Expo setup |

> *Next.js support is pending NativeWind v5 web support. Use NativeWind v4 for Next.js for now.

---

## Step 0: Detect Your Current Version

Run in the project root:

```bash
npx gluestack-ui@alpha upgrade
```

The CLI detects your version automatically. To check manually, inspect `package.json`:

| Dependency present | Version |
|---|---|
| `@gluestack-ui/themed` or `@gluestack-ui/config` | **v2** |
| `@gluestack-ui/core` major = 3, or `@gluestack-ui/nativewind-utils` | **v3** |
| `@gluestack-ui/core` major ≥ 4 + no `uniwind` | **v4 (NativeWind)** |
| `@gluestack-ui/core` major ≥ 4 + `uniwind` present | **v4 (UniWind)** — already on v5 |

---

## Automated Migration (Recommended)

The CLI handles all file changes automatically:

```bash
# Commit your work first (strongly recommended)
git add -A && git commit -m "chore: before gluestack-ui v5 upgrade"

# Run the upgrade wizard
npx gluestack-ui@alpha upgrade
```

The wizard detects your version, walks through each upgrade step with prompts, and handles:
- Package installs / removals
- `global.css` rewrite
- `metro.config.js` updates
- `babel.config.js` updates
- `tailwind.config.js` migration prompts
- `postcss.config.js` creation (NativeWind v5)
- `lightningcss` pinning (NativeWind v5)
- Type definition files

> **Next.js projects**: The automated CLI does not support Next.js upgrades yet. Follow the manual path below.

---

## Migration Paths

### v4 (NativeWind) → v5

Choose your target engine when prompted (or follow the manual steps below).

#### Option A: v4 NativeWind → NativeWind v5

**Packages**

```bash
# Remove NativeWind v4
npm uninstall nativewind
# or: yarn remove / pnpm remove / bun remove nativewind

# Install NativeWind v5 + react-native-css
npm install nativewind@^5.0.0-preview.2 react-native-css@^3.0.4

# Upgrade Tailwind to v4 (dev deps)
npm install -D tailwindcss@^4.2.0 @tailwindcss/postcss@^4.2.0 postcss@^8.5.0
```

**Pin lightningcss** (required — NativeWind v5 requires exactly 1.30.1):

```jsonc
// package.json
{
  "overrides": { "lightningcss": "1.30.1" },
  "resolutions": { "lightningcss": "1.30.1" }
}
```

**`global.css`** — replace contents with Tailwind v4 imports + CSS custom properties:

```css
@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/preflight.css" layer(base);
@import "tailwindcss/utilities.css";
@import "nativewind/theme";

@layer theme {
  :root {
    --primary: 23 23 23;
    --primary-foreground: 250 250 250;
    --card: 255 255 255;
    --secondary: 245 245 245;
    --secondary-foreground: 23 23 23;
    --background: 255 255 255;
    --popover: 255 255 255;
    --popover-foreground: 10 10 10;
    --muted: 245 245 245;
    --muted-foreground: 115 115 115;
    --destructive: 231 0 11;
    --foreground: 10 10 10;
    --border: 229 229 229;
    --input: 229 229 229;
    --ring: 212 212 212;
    --accent: 247 247 247;
    --accent-foreground: 52 52 52;
  }

  @media (prefers-color-scheme: dark) {
    :root {
      --primary: 255 245 245;
      --primary-foreground: 23 23 23;
      --card: 23 23 23;
      --secondary: 38 38 38;
      --secondary-foreground: 250 250 250;
      --background: 10 10 10;
      --popover: 23 23 23;
      --popover-foreground: 250 250 250;
      --muted: 38 38 38;
      --muted-foreground: 161 161 161;
      --destructive: 255 100 103;
      --foreground: 250 250 250;
      --border: 46 46 46;
      --input: 46 46 46;
      --accent: 38 38 38;
      --accent-foreground: 250 250 250;
      --ring: 115 115 115;
    }
  }

  /* Web only: higher specificity (0,2,0) wins over media query (0,1,0) */
  :root.dark {
    --primary: 255 245 245;
    --primary-foreground: 23 23 23;
    --card: 23 23 23;
    --secondary: 38 38 38;
    --secondary-foreground: 250 250 250;
    --background: 10 10 10;
    --popover: 23 23 23;
    --popover-foreground: 250 250 250;
    --muted: 38 38 38;
    --muted-foreground: 161 161 161;
    --destructive: 255 100 103;
    --foreground: 250 250 250;
    --border: 46 46 46;
    --input: 46 46 46;
    --accent: 38 38 38;
    --accent-foreground: 250 250 250;
    --ring: 115 115 115;
  }

  :root.light {
    --primary: 23 23 23;
    --primary-foreground: 250 250 250;
    --card: 255 255 255;
    --secondary: 245 245 245;
    --secondary-foreground: 23 23 23;
    --background: 255 255 255;
    --popover: 255 255 255;
    --popover-foreground: 10 10 10;
    --muted: 245 245 245;
    --muted-foreground: 115 115 115;
    --destructive: 231 0 11;
    --foreground: 10 10 10;
    --border: 229 229 229;
    --input: 229 229 229;
    --ring: 212 212 212;
    --accent: 247 247 247;
    --accent-foreground: 52 52 52;
  }
}

@theme inline {
  --color-primary: rgb(var(--primary));
  --color-primary-foreground: rgb(var(--primary-foreground));
  --color-card: rgb(var(--card));
  --color-secondary: rgb(var(--secondary));
  --color-secondary-foreground: rgb(var(--secondary-foreground));
  --color-background: rgb(var(--background));
  --color-popover: rgb(var(--popover));
  --color-popover-foreground: rgb(var(--popover-foreground));
  --color-muted: rgb(var(--muted));
  --color-muted-foreground: rgb(var(--muted-foreground));
  --color-destructive: rgb(var(--destructive));
  --color-foreground: rgb(var(--foreground));
  --color-border: rgb(var(--border));
  --color-input: rgb(var(--input));
  --color-ring: rgb(var(--ring));
  --color-accent: rgb(var(--accent));
  --color-accent-foreground: rgb(var(--accent-foreground));
}
```

**`postcss.config.js`** — create at project root:

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

**`metro.config.js`** — ensure `nativewind/metro` is present:

```js
const { getDefaultConfig } = require("expo/metro-config");
const { withNativewind } = require("nativewind/metro");

const config = getDefaultConfig(__dirname);
module.exports = withNativewind(config);
```

**`tailwind.config.js`** — Tailwind v4 is CSS-first. This file is no longer needed.
- Migrate any custom `fontFamily`, `boxShadow`, `safelist`, `fontSize`, etc. to `global.css` using `@theme {}` or `@layer utilities {}`
- See: https://tailwindcss.com/docs/upgrade-guide
- Delete the file once migrated

**`react-native-css-env.d.ts`** — create at project root:

```ts
/// <reference types="react-native-css/types" />

// NOTE: This file is generated by react-native-css and it should not be edited manually.
```

**`babel.config.js`** — remove the `tailwind.config` alias if present:

```js
// Remove this line if present:
// 'tailwind.config': './tailwind.config.js'
```

**Re-add components** to get NativeWind v5 versions:

```bash
npx gluestack-ui@alpha add gluestack-ui-provider
npx gluestack-ui@alpha add --all
# or add components individually
```

**Native rebuild** (bare Expo or RN CLI only):

```bash
# iOS
cd ios && pod install && npx expo run:ios
# Android
npx expo run:android
```

---

#### Option B: v4 NativeWind → UniWind

UniWind requires an **Expo** project. Next.js and RN CLI support is coming soon.

**Packages**

```bash
# Remove NativeWind
npm uninstall nativewind
# or: yarn remove / pnpm remove / bun remove nativewind

# Install UniWind + updated gluestack packages
npm install uniwind@^1.3.0 @gluestack-ui/core@^4.1.0-alpha.0 @gluestack-ui/utils@^4.1.0-alpha.0

# Upgrade Tailwind to v4 (dev dep)
npm install -D tailwindcss@^4.1.18
```

**`metro.config.js`** — switch from NativeWind to UniWind:

```js
const { getDefaultConfig } = require("expo/metro-config");
const { withUniwindConfig } = require("uniwind/metro");

const config = getDefaultCo