Upgrade to gluestack-ui v3

Why gluestack-ui v3?

Evolution to v3

gluestack-ui v3 represents a major evolution in our approach to universal component development. Building on the foundation of v2, v3 introduces a revolutionary source-to-destination architecture that ensures consistency across all platforms while maintaining maximum flexibility.

What's New in v3

Source-to-Destination Architecture (contribution change): All components are maintained in a single source of truth (

src/

directory) and automatically synced across all project templates and examples

Enhanced Package System (contribution change): Modular packages (

gluestack-core

gluestack-utils

ui-next-adapter

) for better maintainability and extensibility

Improved Developer Experience (contribution change): Streamlined development workflow with automated file synchronization and hot reloading

Advanced Component Creation (contribution change): New CLI tools and scripts for rapid component development and contribution

Better Documentation Integration (contribution change): Seamless integration between component source code and documentation

Enhanced Testing Infrastructure (contribution change): Comprehensive testing across multiple starter templates and applications

Migration from Previous Versions

From v2 to v3

What's Changed (Minimal Breaking Changes):

gluestack-ui v3 maintains API compatibility with v2 while introducing significant architectural improvements:

Package structure changes to @gluestack-ui/core and @gluestack-ui/utils

Import path updates for creator function

ARIA dependencies moved from react-native-aria to @gluestack-ui/core

Enhanced Next.js adapter

Better compatibility with Expo SDK 53 and Next.js 15

What Stays the Same:

Component APIs remain exactly the same

Styling system unchanged

Theming configurations continue to work

Copy-paste philosophy maintained

Migration Benefits

Seamless Upgrade: Simple upgrade process with

npx gluestack-ui@latest upgrade

command.

Minimal code changes (only import paths)

Enhanced stability and bug fixes

Future-ready foundation

Improved developer experience (contribution change)

Community Support: Active community and comprehensive migration resources

We've prepared a comprehensive migration guide to help you transition smoothly from v2 to v3, including automated migration tools and detailed instructions.

Manual Migration to gluestack-ui v3

If you have a simple Next.js or Expo project using Gluestack, you can upgrade directly by running:

npx gluestack-ui@latest upgrade

For monorepos, please follow the manual installation guide instead. This guide provides detailed manual steps to migrate from legacy gluestack-ui packages to the new gluestack-ui v3 ecosystem. Follow these steps carefully to ensure a smooth transition with minimal issues. We’ll be releasing an official Gluestack monorepo template soon to make the process even easier.

Migration Overview

The migration process involves several key steps:

Step 1:Backup and Preparation - Secure your codebase
Step 2:Package Management - Remove old packages and install new ones
Step 3:Configuration Updates - Update Tailwind and Next.js configurations
Step 4:Code Transformation - Update import statements and component usage
Step 5:Clean Installation - Ensure dependency integrity

Step 1: Backup and Preparation

Check Git Status

Before proceeding, ensure your project has no uncommitted changes:

git status

If you have uncommitted changes, either commit them or stash them:

# Commit changes
git add .
git commit -m "Pre-migration backup"

# Or stash changes
git stash

Identify Legacy Packages

Check your

package.json

to identify old gluestack packages that need to be removed. Look for packages starting with:

@gluestack-ui

gluestack

@gluestack

Step 2: Remove Legacy Packages

Detect Old Packages

First, list all the legacy packages in your

package.json

and remove them: Remove

react-native-aria

# Remove old packages
npm uninstall react-native-aria

Note: Replace the package names above with the actual legacy packages found in your

package.json

Step 3: Update Configuration Files

Update Tailwind Configuration

Remove the old gluestack plugin from your

tailwind.config.ts

tailwind.config.js

: Before:

import gluestackPlugin from '@gluestack-ui/nativewind-utils/tailwind-plugin';

export default {
// ... other config
plugins: [gluestackPlugin, /* other plugins */],
}

After:

export default {
// ... other config
plugins: [/* other plugins only */],
}

Update Next.js Configuration

Update your Next.js configuration files (

next.config.ts

next.config.js

, or

next.config.mjs

): Before:

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

const nextConfig = {
// ... your config
};

export default withGluestackUI(nextConfig);

After:

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

const nextConfig = {
// ... your config
};

export default withGluestackUI(nextConfig);

Update Registry File (Next.js 15)

If you have an

app/registry.tsx

file, update the flush import: Before:

import { flush } from '@gluestack-ui/nativewind-utils/flush';

After:

import { flush } from '@gluestack-ui/utils/nativewind-utils';

Step 4: Install New Packages

Install the new gluestack-ui v3 packages:

npm install @gluestack-ui/core@latest @gluestack-ui/utils@latest react-native-svg@15.12.0 @gluestack/ui-next-adapter@latest

Step 5: Clean Installation

To ensure all dependencies are properly resolved, perform a clean installation:

# Remove node_modules and package-lock.json
rm -rf node_modules package-lock.json

# Reinstall dependencies
npm install

Step 6: Update Import Statements

Transform Component Imports

Update all import statements in your

components/ui

folder and throughout your codebase: Before:


import { createButton  } from '@gluestack-ui/button';
import { createRadio } from '@gluestack-ui/radio';

After:


import { createButton } from '@gluestack-ui/core/button/creator';
import { createRadio } from '@gluestack-ui/core/radio/creator';

Transform Utility Imports

Before:

import { flush } from '@gluestack-ui/nativewind-utils/flush';
import { tva } from '@gluestack-ui/nativewind-utils/tva';

After:

import { flush } from '@gluestack-ui/utils/nativewind-utils';
import { tva } from '@gluestack-ui/utils/nativewind-utils';

Step 7: Update Component Usage Patterns

Import Path Transformation Rules

Use these patterns to transform your imports:

Old Import Pattern	New Import Pattern
from '@gluestack-ui/[component]'	from '@gluestack-ui/core/[component]/creator'
from '@gluestack-ui/nativewind-utils/[utility]'	from '@gluestack-ui/utils/nativewind-utils'
from '@gluestack/ui-next-adapter'	from '@gluestack/ui-next-adapter'

Step 8: Recursive File Processing

Process All Component Files

You'll need to update imports in all TypeScript/JavaScript files recursively. Here's a systematic approach:

Step 1:Start with the main components directory:
components/ui/
Step 2:Process subdirectories: Look for nested component folders
Step 3:Update file extensions: Process
.ts
,
.tsx
,
.js
,
.jsx
files
Step 4:Check other directories: Look for components in
src/
,
app/
,
screens/
, etc.

File Processing Checklist

For each file, verify:

All

@gluestack-ui/*

imports are updated

All

@gluestack/*

imports are updated

No legacy package imports remain

File compiles without import errors

Step 9: Verification and Testing

Verify Migration Success

After completing the migration:

Step1: Check for compilation errors:

npm run build

Step2: Run your development server:

npm run dev

Step3: Test core functionality: Ensure your components render and behave correctly

Common Issues and Solutions

Import Resolution Issues

If you encounter import errors:

Verify package installation: Check that all new packages are in

package.json

Clear cache: Delete

node_modules

and reinstall

Check import paths: Ensure they follow the new pattern exactly

Build Errors

If builds fail:

Check TypeScript configuration compatibility

Verify all configuration files are updated

Ensure no legacy imports remain

Runtime Issues

If components don't work at runtime:

Check browser console for errors

Verify CSS/styling is loading correctly

Test component functionality individually

Step 10: Post-Migration Cleanup

Final Verification Steps

Step1: Search for legacy references:

# Search for any remaining old imports
 grep -r "@gluestack-ui" src/ components/ app/
 grep -r "@gluestack/" src/ components/ app/

Step2: Commit your changes**:

git add .
 git commit -m "Migrate to gluestack-ui v3 packages"

Step 3:Test thoroughly: Run your test suite and manually test key features

Troubleshooting

Package Manager Issues

If you encounter dependency resolution issues:

Step1: Clear package manager cache:


 npm cache clean --force  # for npm
 yarn cache clean         # for yarn  
 pnpm store prune         # for pnpm
 bun pm cache rm          # for bun

Step2: Delete lock files and reinstall:

rm -rf node_modules package-lock.json
   npm install

Configuration Issues

If configurations aren't working:

Double-check file names and extensions

Ensure proper syntax in config files

Verify import statements in config files

Component Issues

If components aren't working:

Check component documentation for API changes

Verify styling and theming setup

Test components individually

Migration Checklist

Use this checklist to track your migration progress:

Preparation

Committed or stashed all changes

Identified all legacy packages

Created project backup

Package Management

Removed all legacy gluestack packages

Installed new gluestack packages

Performed clean installation

Configuration Updates

Updated Tailwind configuration

Updated Next.js configuration

Updated registry file (if applicable)

Code Updates

Updated all component imports

Updated utility imports

Processed all subdirectories

Verified no legacy imports remain

Testing

Project builds successfully

Development server runs

Components render correctly

Core functionality works

Finalization

Committed changes

Updated documentation

Tested thoroughly

Next Steps

After successful migration:

Step 1:Update your team: Inform team members about the migration
Step 2:Update documentation: Revise any project-specific documentation
Step 3:Monitor for issues: Keep an eye on the application for any unexpected behavior
Step 4:Stay updated: Follow gluestack-ui releases for future updates

Support

If you encounter issues during migration:

Check the

gluestack-ui documentation

Review common issues in this guide

Seek help from the gluestack-ui community

Remember to test thoroughly in a development environment before deploying to production!

Edit this page on GitHub