CLI

• Currently we are working on support for Windows OS. For now, we recommend using the manual installation guide to avoid any issues.

Init

• metro.config.js
• babel.config.js
• next.config.js

  ( for Next.js)
• tailwind.config.js
• global.css

  (for Tailwind CSS)
• ts.config.json
• entry file (for your project)

npx gluestack-ui@alpha init

Monorepo Example

# Navigate to your monorepo root
cd my-monorepo

# Initialize gluestack-ui in monorepo mode
npx gluestack-ui init --monorepo --path packages/ui

# The CLI will:
# 1. Prompt you to select a styling engine (NativeWind v5, UniWind, etc.)
# 2. Create GluestackUIProvider in packages/ui
# 3. Generate gluestack-ui.config.json at repo root:
#    {
#      "app": {
#        "components": "packages/ui"
#      }
#    }
# 4. Install dependencies and update config files

# Later, add components
npx gluestack-ui add button --monorepo

# Or add all components
npx gluestack-ui add --all --monorepo

npx gluestack-ui init --monorepo --path packages/ui --nativewind-v5 -y
npx gluestack-ui add button --monorepo -y

Options:

• --path <path>

  : Specifies the directory path where you want to add the GluestackUIProvider component. By default, it creates the component in the

  components/ui

  directory within your project's root.
• --monorepo

  : When used in monorepo repositories, this flag switches the init flow to monorepo mode. In monorepo mode the CLI will treat the project as a shared component library (projectType: library) and will:

  • Prompt to select or enter the components path where GluestackUIProvider and components should be written (e.g.

    packages/ui

    ,

    packages/components

    ,

    apps/ui

    ).
  • Generate a top-level

    gluestack-ui.config.json

    that points

    app.components

    to the chosen components path (relative to repo root).
  • Add provider and core components into the chosen components path and update configs (tailwind, metro, tsconfig) appropriately.
• --use-<package>

  : This flag specifies the package manager to use when initializing gluestack-ui. Supported options are npm (default), yarn, bun, and pnpm. Replace

  <package>

  with your preferred package manager.
• --nativewind

  : Use NativeWind v4 (Tailwind CSS v3) as the styling engine. Useful for projects that need to stay on Tailwind v3.
• --nativewind-v5

  : Use NativeWind v5 (Tailwind CSS v4) as the styling engine. Note: NativeWind v5 is not yet web-compatible in monorepo mode; the CLI will fall back to NativeWind v4 in monorepo setups.
• --uniwind

  : Use UniWind (Tailwind CSS v4, Expo-only) as the styling engine. Note: UniWind is not supported for monorepo Next.js setups. In monorepo mode the CLI will fall back to NativeWind v4.
• -y, --yes

  : Answer yes to all prompts. Use this for non-interactive environments like CI/CD pipelines.

Usage: npx gluestack-ui@alpha init [options] 
 
 initialize your gluestack-ui and install dependencies 
 
 Options: 
   --path <path>      Path to add GluestackUIProvider, defaults to components/ui in the current directory. 
   --monorepo         Run init in monorepo/library mode and interactively choose components path. 
   --use-npm          Use npm as the package manager (default) 
   --use-yarn         Use yarn as the package manager 
   --use-bun          Use bun as the package manager 
   --use-pnpm         Use pnpm as the package manager 
   --nativewind       Use NativeWind v4 (Tailwind CSS v3) 
   --nativewind-v5    Use NativeWind v5 (Tailwind CSS v4) 
   --uniwind          Use UniWind (Tailwind CSS v4, Expo-only) 
   -y, --yes          Answer yes to all prompts (non-interactive mode)

Add

npx gluestack-ui@alpha add [component]

Options:

• --all

  : This flag can be used to add all available components from gluestack-ui to your project.
• --path <path>

  : Specifies the directory path where you want to add the component. By default, it will add the component to the same directory where the GluestackUIProvider is located.
• --monorepo

  : When adding components into a monorepo, use --monorepo to enable monorepo-aware flows. With --monorepo the CLI will:

  • Prompt you to select or enter the components path (e.g.

    packages/ui

    ) if not provided via

    --path

    .
  • Validate and write

    gluestack-ui.config.json

    at the repo root pointing to the selected components path.
  • Ensure components are added into the chosen path rather than the repo root.
• --use-<package>

  : Specifies the package manager to use. Supported options are npm (default), yarn, bun, and pnpm. Replace

  <package>

  with your preferred package manager.
• -y, --yes

  : Answer yes to all prompts. Use this for non-interactive environments like CI/CD pipelines.

Usage: npx gluestack-ui@alpha add [component] [options] 
 
 add component to your project 
 
 Options: 
   --all            Adds all existing components from gluestack-ui 
   --path <path>    Path to add components, defaults to the directory where GluestackUIProvider is located. 
   --monorepo       Run add in monorepo mode and interactively choose components path. 
   --use-npm        Set npm as the project's package manager, default 
   --use-yarn       Set yarn as the project's package manager 
   --use-bun        Set bun as the project's package manager 
   --use-pnpm       Set pnpm as the project's package manager, currently not supported in react-native-cli projects. 
   -y, --yes        Answer yes to all prompts (non-interactive mode)

Upgrade

npx gluestack-ui@alpha upgrade

◆ Which styling engine would you like to upgrade to?
│ ● NativeWind v5 (Tailwind CSS v4)
│ ○ UniWind (Tailwind CSS v4, Expo-only)
│ ○ Stay on current version

NativeWind v5 upgrade path

1. Step 1:Pin

   lightningcss@1.30.1

   in

   package.json

   overrides/resolutions
2. Step 2:Replace

   nativewind@^4.x

   with

   nativewind@^5.0.0-preview.2

   and add

   react-native-css
3. Step 3:Upgrade

   tailwindcss

   to v4 and add

   @tailwindcss/postcss
4. Step 4:Rewrite

   global.css

   to Tailwind v4 format (with theme tokens)
5. Step 5:Create

   postcss.config.js
6. Step 6:Add

   withNativewind

   to

   metro.config.js

   (preserves existing options)
7. Step 7:Prompt whether to delete

   tailwind.config.js

   (never auto-deleted — may contain custom tokens)
8. Step 8:Create

   react-native-css-env.d.ts

UniWind upgrade path

1. Step 1:Replace

   nativewind

   with

   uniwind
2. Step 2:Upgrade

   tailwindcss

   to v4
3. Step 3:Rewrite

   global.css

   to UniWind / Tailwind v4 format
4. Step 4:Update

   metro.config.js

   to use

   withUniwindConfig
5. Step 5:Remove

   nativewind/babel

   entries from

   babel.config.js
6. Step 6:Remove

   tailwind.config.js

   (Tailwind v4 is CSS-first)
7. Step 7:Remove

   nativewind-env.d.ts

   and create

   uniwind-types.d.ts

gluestack-ui.config.json

npx gluestack-ui@alpha init

Monorepo Configuration

{
  "app": {
    "components": "packages/ui"
  }
}

tailwind

tailwind.config

{
  "tailwind": {
    "config": "tailwind.config.js",
  }
}

tailwind.css

{
  "tailwind": {
    "css": "global.css"
  }
}

app

app.entry

{
  "app": {
    "entry": "app/_layout.tsx",
  }
}

app.components

{
  "app": {
    "components": "components/ui",
  }
}