Gluestack UI V5:setup

Gluestack UI v5 — Setup & Installation

This sub-skill covers gluestack-ui v5 setup. v5 runs on Tailwind CSS v4 (CSS-first, no tailwind.config.js) with two supported styling engines:

Next.js support is pending NativeWind v5 web support. Use gluestack-ui v4 for Next.js projects for now.

v5 only — do not use v1/v2/v3/v4 packages or docs

• Never use or suggest: @gluestack/styled, @gluestack-ui/themed, @gluestack-ui/nativewind-utils (v4 package), tailwind.config.js (Tailwind v3), or any packages/docs from v4.gluestack.io (v4 docs, still available for reference).
• v5 packages: @gluestack-ui/core@^5, @gluestack-ui/utils@^5, plus the styling engine (nativewind@^5.0.0-preview.2 + react-native-css@^3.0.4 OR uniwind@^1.3.0).

CLI (Recommended)

Prerequisites

Step 1: Initialize

From your project root:

npx gluestack-ui@latest init

This adds GluestackUIProvider and essential components (icon, overlay, toast). The @latest tag is for greenfield projects. During migration from older versions, use @alpha.

Step 2: Add Components

# Add individual components
npx gluestack-ui@latest add button

# Add all components at once
npx gluestack-ui@latest add --all

Step 3: If migrating from v4

# Use @alpha tag for migration
npx gluestack-ui@alpha upgrade
npx gluestack-ui@alpha add gluestack-ui-provider
npx gluestack-ui@alpha add --all

After migration, delete tailwind.config.js — Tailwind v4 is CSS-first. See the migrate-to-v5 skill for full details.

Manual: NativeWind v5 (Expo / React Native CLI)

Packages

# Styling engine
npm install nativewind@^5.0.0-preview.2 react-native-css@^3.0.4

# Dev dependencies (Tailwind v4 + PostCSS)
npm install -D tailwindcss@^4.2.0 @tailwindcss/postcss@^4.2.0 postcss@^8.5.0

Pin lightningcss

NativeWind v5 requires exactly lightningcss@1.30.1. Add to package.json:

{
  "overrides": { "lightningcss": "1.30.1" },
  "resolutions": { "lightningcss": "1.30.1" }
}

global.css

Create at project root. This replaces tailwind.config.js — all tokens are defined here:

@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: explicit class-based dark/light mode */
  :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));
}

The @theme inline {} block maps CSS custom properties to Tailwind utility classes — so bg-primary resolves to var(--color-primary) which is rgb(var(--primary)).

postcss.config.js

Create at project root (required for NativeWind v5):

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

metro.config.js

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

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

react-native-css-env.d.ts

Create at project root:

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

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

babel.config.js

Remove the 'tailwind.config': './tailwind.config.js' alias if present — it was a v3/v4 workaround. Tailwind v4 doesn't use a config file.

Rebuild (bare Expo / React Native CLI only)

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

Manual: UniWind (Expo only)

UniWind is an alternative styling engine that does not require PostCSS, making the setup simpler than NativeWind v5.

Packages

# Styling engine
npm install uniwind@^1.3.0

# Dev dependency (Tailwind v4)
npm install -D tailwindcss@^4.1.18

No lightningcss pin or PostCSS config needed.

global.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));
}

Important: The .dark {} / .light {} selectors must be top-level inside @layer theme, never nested inside :root {}. Nested selectors won't match when UniWind transforms them for web.

metro.config.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'],
});

uniwind-types.d.ts

/// <reference types="uniwind/types" />

declare module 'uniwind' {
  export interface UniwindConfig {
    themes: readonly ['light', 'dark']
  }
}

export {}

babel.config.js

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

Theme Switching (UniWind)

With UniWind, use Uniwind.setTheme() instead of Appearance.setColorScheme():

import { Uniwind } from 'uniwind';

// In your GluestackUIProvider or theme toggle
Uniwind.setTheme('dark');   // Force dark
Uniwind.setTheme('light');  // Force light
Uniwind.setTheme('system'); // Follow device setting

After re-adding the provider via npx gluestack-ui@alpha add gluestack-ui-provider, the UniWind version handles this automatically.

Engine Comparison

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: npx expo install react-native-reanimated && npx expo install --fix.

Theme not applying on Expo Web (UniWind)

.dark {} / .light {} selectors in global.css must be top-level inside @layer theme, not nested inside :root {}.

NativeWind v5 build errors

Ensure lightningcss is pinned to exactly 1.30.1 in both overrides and resolutions, then rm -rf node_modules && npm install.

tailwind.config.js still referenced after migration

Delete it. Remove any 'tailwind.config': './tailwind.config.js' alias from babel.config.js presets.

Reference

• Migration guide: Use the migrate-to-v5 skill for step-by-step v2/v3/v4 → v5 migration
• NativeWind v5 docs: https://www.nativewind.dev/
• UniWind docs: Check the UniWind package documentation