gluestack-ui-v4:performance

Gluestack UI v4 - Performance & Cross-Platform

This sub-skill focuses on performance optimization, cross-platform compatibility, and React Native best practices for gluestack-ui v4.

Rule 12: Cross-Platform Rendering (Native & Web)

Gluestack UI v4 components are designed to work seamlessly on both React Native (iOS/Android) and Web platforms. Always use Gluestack wrapper components instead of direct React Native imports to ensure cross-platform compatibility.

Critical Rule: Always Use Gluestack Wrappers

NEVER import components directly from react-native when a Gluestack wrapper exists. Gluestack wrappers handle platform-specific differences automatically.

Platform-Specific Component Mapping

React Native Import	Gluestack Wrapper	Notes
KeyboardAvoidingView from react-native	KeyboardAvoidingView from @/components/ui/keyboard-avoiding-view	Required for web compatibility
Platform from react-native	Use only when absolutely necessary	Prefer Gluestack's built-in platform handling
View, Text, etc.	Box, Text from @/components/ui/*	Always use Gluestack components

Correct Pattern: Cross-Platform Components

// ✅ CORRECT: Using Gluestack KeyboardAvoidingView wrapper
import { KeyboardAvoidingView } from '@/components/ui/keyboard-avoiding-view';
import { Platform } from 'react-native'; // Only when needed for platform-specific logic

<KeyboardAvoidingView
  behavior={Platform.OS === 'ios' ? 'padding' : 'height'}
  className="flex-1"
>
  <ScrollView>
    {/* Content */}
  </ScrollView>
</KeyboardAvoidingView>

Incorrect Pattern: Direct React Native Imports

// ❌ INCORRECT: Direct import from react-native
import { KeyboardAvoidingView, Platform } from 'react-native';

<KeyboardAvoidingView behavior={Platform.OS === 'ios' ? 'padding' : 'height'}>
  {/* This may not work correctly on web */}
</KeyboardAvoidingView>

Web-Specific Considerations