Migrate To V5

gluestack/agent-skills/.agents/skills/gluestack-ui-v4/migrate-to-v5

作者 gluestack12ba10a0df78a65934d15fb217d9c89df949f826無授權條款1 個星標收錄於 2026年10月9日更新於 2026年10月9日儲存庫3 個月前更新

Migrate a gluestack-ui project from v2, v3, or v4 to v5 (NativeWind v5 or UniWind). Covers automated CLI upgrade and manual step-by-step migration for all source versions.

僅含說明Software Development
AI 產生的概覽

指導將 gluestack-ui 專案從 v2、v3 或 v4 遷移到 v5，可選 NativeWind v5 或 UniWind。

功能
提供將 gluestack-ui 專案升級到 v5 的逐步說明，涵蓋版本偵測、套件變更與設定檔重寫。文件同時介紹自動化 CLI 升級路徑，以及針對 v2、v3、v4 來源版本的手動遷移路徑。另外也列出常見問題與遷移後檢查清單。
適用情境
當 gluestack-ui 專案需要遷移到 v5 時使用，不論目前是 v2、v3 還是 v4。適合需要在 NativeWind v5 與 UniWind 兩種樣式引擎之間做選擇的開發者。
執行需求
需要一個現有的 gluestack-ui 專案，以及 Node.js 和套件管理工具（npm、yarn、pnpm 或 bun）。自動化路徑透過 npx 使用 gluestack-ui CLI；手動路徑需要編輯專案設定檔並重新安裝相依套件。此技能未附帶指令碼。

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:

EngineTailwindPlatformsWhen to choose
NativeWind v5v4Expo, RN CLI, Next.js*Recommended default
UniWindv4Expo onlyNo 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 presentVersion
@gluestack-ui/themed or @gluestack-ui/configv2
@gluestack-ui/core major = 3, or @gluestack-ui/nativewind-utilsv3
@gluestack-ui/core major ≥ 4 + no uniwindv4 (NativeWind)
@gluestack-ui/core major ≥ 4 + uniwind presentv4 (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 wizardnpx 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 v4npm uninstall nativewind# or: yarn remove / pnpm remove / bun remove nativewind
# Install NativeWind v5 + react-native-cssnpm 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.

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-providernpx gluestack-ui@alpha add --all# or add components individually

Native rebuild (bare Expo or RN CLI only):

bash
# iOScd ios && pod install && npx expo run:ios# Androidnpx 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 NativeWindnpm uninstall nativewind# or: yarn remove / pnpm remove / bun remove nativewind
# Install UniWind + updated gluestack packagesnpm 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 = getDefaultConfig(__dirname);module.exports = withUniwindConfig(config, {  cssEntryFile: './global.css',  dtsFile: './uniwind-types.d.ts',  extraThemes: ['dark'],});

global.css — replace with UniWind CSS (Tailwind v4 + :where() selectors):

css
@import 'tailwindcss';@import 'uniwind';
@layer theme {  :where(.light, .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;  }
  @media (prefers-color-scheme: light) {    :root:not(:where(.light, .light *, .dark, .dark *)) {      --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;    }  }
  :where(.dark, .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;  }
  @media (prefers-color-scheme: dark) {    :root:not(:where(.light, .light *, .dark, .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;    }  }}
@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));}

Web theming note: UniWind's CSS visitor transforms :where(.dark, .dark *) to .dark {}. For this to work on Expo Web, the .dark {} / .light {} selectors must be at the top level of @layer theme — never nested inside :root {}. The template above is already correct.

tailwind.config.js — delete it. Tailwind v4 is CSS-first; all tokens live in global.css.

nativewind-env.d.ts → delete. Create uniwind-types.d.ts instead:

ts
/// <reference types="uniwind/types" />
declare module 'uniwind' {  export interface UniwindConfig {    themes: readonly ['light', 'dark']  }}
export {}

babel.config.js — remove nativewind/babel preset/plugin, add react-native-worklets/plugin:

js
module.exports = {  presets: [    // Remove: 'nativewind/babel'    ['babel-preset-expo', { jsxImportSource: 'nativewind' }],  ],  plugins: [    'react-native-worklets/plugin',  ],};

GluestackUIProvider — re-add to get the UniWind version:

bash
npx gluestack-ui@alpha add gluestack-ui-provider

Key differences in the UniWind provider:

  • Native: use Uniwind.setTheme('light' | 'dark' | 'system') instead of Appearance.setColorScheme()
  • Web: script.ts adds .dark / .light class to document.documentElement; Uniwind.setTheme() also calls onThemeChange() for runtime CSS variable management

v3 → v5

Step 1: Upgrade v3 → v4 (NativeWind)

bash
# Detect old packages (check package.json for @gluestack-ui/* deps)# Remove all old gluestack packagesnpm uninstall @gluestack-ui/core @gluestack-ui/utils @gluestack-ui/nativewind-utils \  @gluestack-ui/themed @gluestack-ui/config @gluestack/ui-next-adapter
# Install gluestack v4 + NativeWind v4npm install @gluestack-ui/core@^4.0.0-alpha.0 @gluestack-ui/utils@^4.0.0-alpha.0 \  tailwind-variants@^0.1.20 nativewind@^4.1.23
# Expo: use expo install for native packages (resolves SDK-compatible versions)npx expo install react-native-reanimated @legendapp/motion react-native-svg \  react-native-safe-area-context @expo/html-elementsnpx expo install --fix   # resolves react-native-worklets at matching version
# RN CLI / non-Expo:npm install react-native-reanimated@~4.2.1 react-native-worklets@~0.7.1 \  @legendapp/motion@^2.4.0 react-native-svg@^15.12.0 \  react-native-safe-area-context@^5.6.1 @expo/html-elements@^0.12.5

tailwind.config.js — remove gluestackPlugin:

js
// Remove this import:// import gluestackPlugin from '@gluestack-ui/nativewind-utils/tailwind-plugin';
// Remove from plugins array:// plugins: [gluestackPlugin]

babel.config.js — add react-native-worklets/plugin:

js
plugins: [  'react-native-worklets/plugin',]

Import updates — imports are compatible between v3 and v4 (same format). No changes needed.

Native rebuild (bare Expo / RN CLI):

bash
# iOScd ios && pod install && npx expo run:ios# Androidnpx expo run:android

Step 2: v4 NativeWind → v5

Follow Option A or Option B above.

v2 → v5

Step 1: Upgrade v2 → v3

bash
# Remove all old v2 packagesnpm uninstall @gluestack-ui/themed @gluestack-ui/config \  @gluestack-style @gluestack-style/react @gluestack/ui-next-adapter
# Install v3 core packagesnpm install @gluestack-ui/[email protected] @gluestack-ui/[email protected] [email protected]
# Next.js only:npm install @gluestack/[email protected]

tailwind.config.js — remove old gluestack plugin (same as v3→v4 step above).

app/registry.tsx (Next.js only) — update flush import:

ts
// Old:import { flush } from '@gluestack-ui/nativewind-utils/flush';// New:import { flush } from '@gluestack-ui/utils/nativewind-utils';

next.config.js/ts/mjs (Next.js only) — update adapter import (same package, just re-save to refresh):

ts
import { withGluestackUI } from "@gluestack/ui-next-adapter";

Import updates — update component imports across components/ui/:

ts
// Old (v2):import { createButton } from '@gluestack-ui/button';// New (v3):import { createButton } from '@gluestack-ui/core/button/creator';
// Old (v2 utils):import { something } from '@gluestack-ui/nativewind-utils/something';// New (v3):import { something } from '@gluestack-ui/utils/nativewind-utils';

Step 2: v3 → v4 → v5

Follow the v3 → v5 path above.

What Changes in v5 (Summary)

Whatv4 (NativeWind)v5 NativeWindv5 UniWind
Tailwind versionv3v4v4
tailwind.config.jsRequiredDeleted (CSS-first)Deleted
global.css imports@tailwind base/components/utilities@import "tailwindcss/..."@import 'tailwindcss'; @import 'uniwind'
Theme tokenstailwind.config.js theme.extend.colorsglobal.css @layer theme { :root {} }global.css @layer theme { :where(.light) {} }
postcss.config.jsRequiredRequiredNot needed
lightningcss pinNot needed1.30.1 requiredNot needed
Packagenativewind@^4nativewind@^5.0.0-preview.2 + react-native-css@^3.0.4uniwind@^1.3.0
Platform supportExpo + RN CLI + Next.jsExpo + RN CLI (Next.js pending)Expo only
Metro configwithNativeWind(config)withNativewind(config)withUniwindConfig(config, {...})
Theme switchingAppearance.setColorScheme()Appearance.setColorScheme()Uniwind.setTheme()

Common Issues

Mismatch between JavaScript part and native part of Worklets

react-native-worklets version must match the minor of react-native-reanimated. For Expo projects, always use npx expo install react-native-reanimated && npx expo install --fix — never pin manually.

Theme not applying on Expo Web (UniWind)

The .dark {} / .light {} selectors in global.css must be top-level inside @layer theme, not nested inside :root {}. Nesting causes UniWind's CSS visitor to emit .dark {} as a descendant of :root, so html.dark never matches.

NativeWind v5 build errors

Ensure lightningcss is pinned to exactly 1.30.1 in both overrides and resolutions in package.json, then delete node_modules and reinstall.

tailwind.config.js still referenced

After deleting tailwind.config.js, remove any 'tailwind.config': './tailwind.config.js' alias from babel.config.js presets options.

nativewind/babel still in babel.config.js (UniWind)

UniWind does not use the NativeWind Babel preset. Remove 'nativewind/babel' from both presets and plugins arrays.

After Migration Checklist

  • lightningcss pinned to 1.30.1 (NativeWind v5 only)
  • global.css uses Tailwind v4 imports (no @tailwind base/components/utilities)
  • tailwind.config.js deleted and custom tokens moved to global.css @theme {}
  • postcss.config.js created with @tailwindcss/postcss (NativeWind v5 only)
  • metro.config.js updated to correct wrapper (withNativewind or withUniwindConfig)
  • babel.config.js — nativewind/babel removed (UniWind); react-native-worklets/plugin added
  • GluestackUIProvider re-added: npx gluestack-ui@alpha add gluestack-ui-provider
  • All components re-added: npx gluestack-ui@alpha add --all
  • Native rebuild done (bare Expo / RN CLI): pod install + expo run:ios
  • App starts without errors on iOS, Android, and Web
  • Light/dark mode toggles correctly on all platforms

來源與署名

來源：gluestack/agent-skills位於.agents/skills/gluestack-ui-v4/migrate-to-v5提交12ba10a

授權條款： 無授權條款

內容歸原作者所有。SourceWeft 從公開儲存庫中收錄這些內容。

檢舉或申請下架

更多來自 gluestack/agent-skills 的技能

Gluestack Ui V5

gluestack

協調 gluestack-ui v5 的約束性樣式規則，以及安裝、元件、變體、效能與驗證等子技能。

Software Development13 個月前更新

Gluestack Ui V4

gluestack

為 gluestack-ui v4 強制套用固定的樣式規範，並將工作分派到設定、元件、樣式、變體、效能與驗證等子技能。

Software Development13 個月前更新

更多Software Development技能

Playground

anthropics

精選

建立自成一體的互動式 HTML 遊樂場，包含控制項、即時預覽與可複製的提示詞輸出。

Software Development37K今天更新

M5 Onboard

anthropics

精選

透過 USB 偵測 M5Stack ESP32 開發板，燒錄 UIFlow 2.0 韌體並安裝 MicroPython 應用程式套件。

Software Development37K今天更新

Cardputer Buddy

anthropics

精選

指導迭代 Cardputer-Adv 的 MicroPython 應用程式套件：新增應用程式、透過 USB 序列埠推送檔案、查看日誌並執行 REPL 指令。

Software Development37K今天更新

Web Design Guidelines

vercel-labs

精選

依據從遠端來源取得的 Web Interface Guidelines 審查 UI 程式碼，並以 file:line 形式回報問題。

Software Development32K5 週前更新

Vercel React Native Skills

vercel-labs

精選

React Native 與 Expo 最佳實務規則，涵蓋清單效能、動畫、導覽、UI 模式、狀態與 monorepo 設定。

Software Development32K5 週前更新

Vercel React Best Practices

vercel-labs

精選

Vercel 的 React 與 Next.js 效能指南，以 70 條規則的形式用於撰寫、審查與重構程式碼。

Software Development32K5 週前更新