Styles are not loading after upgrading gluestack from v1 to v3

by

Summary

A routine upgrade from Gluestack v1 to v3 caused styles to stop loading correctly in a React Native project. The issue was not with Gluestack itself but with misaligned configuration files, stale build artifacts, and incomplete migration of the new styling pipeline. The result was a UI that rendered with broken or missing styles, especially on the login screen.

Root Cause

The failure stemmed from a combination of factors:

  • Leftover v1 configuration files (theme, tokens, provider setup) still being referenced by the bundler
  • Metro cache and build artifacts holding onto outdated style transforms
  • Incorrect or missing Gluestack v3 adapter setup (e.g., @gluestack/ui-next-adapter)
  • Conflicts with NativeWind / CSS Interop after the upgrade
  • Partially migrated folder structure, causing imports to resolve to old files

The upgrade changed how Gluestack handles theming, tokens, and component registration. Any leftover v1 files silently break the v3 pipeline.

Why This Happens in Real Systems

This class of failure is extremely common during major UI framework upgrades because:

  • Bundlers aggressively cache transforms, especially Metro
  • Developers often forget hidden config files (e.g., gluestack-ui.config.ts, styled.config.ts)
  • Breaking changes in theming systems require full migration, not partial
  • Multiple styling engines (Tailwind, NativeWind, CSS Interop, Gluestack) compete for precedence
  • File-based resolution means one stale file can override the entire theme

Real-world systems accumulate configuration debt, and UI frameworks are especially sensitive to it.

Real-World Impact

When this happens in production apps, teams typically see:

  • Broken layouts (spacing, padding, alignment collapse)
  • Missing colors or tokens
  • Components rendering with fallback/default styles
  • Inconsistent behavior across iOS/Android
  • Hours lost debugging “invisible” config issues

In severe cases, the app becomes unusable until the styling pipeline is fixed.

Example or Code (if necessary and relevant)

A minimal correct Gluestack v3 setup often looks like:

import { config } from '@gluestack-ui/config';
import { createProvider } from '@gluestack-ui/provider';

export const UIProvider = createProvider({ config });

If a project still contains something like this from v1:

import { GluestackUIProvider } from '@gluestack-ui/themed';

Metro may silently resolve to the wrong provider, breaking all styles.

How Senior Engineers Fix It

Experienced engineers approach this systematically:

  • Delete all build artifacts
    • rm -rf android/app/build
    • rm -rf ios/build
    • watchman watch-del-all
    • npx react-native start --reset-cache
  • Search the repo for leftover v1 imports
    • @gluestack-ui/themed
    • styled.config.ts
    • old theme/token files
  • Recreate the Gluestack v3 folder structure from scratch
  • Verify the adapter is installed and configured (@gluestack/ui-next-adapter)
  • Ensure NativeWind / CSS Interop is not overriding Gluestack
  • Rebuild the app fully, not just reload Metro
  • Check Metro config for custom resolvers that may point to old paths

The key is eliminating stale configuration and ensuring the new pipeline is the only one active.

Why Juniors Miss It

Less experienced developers often struggle because:

  • They assume Metro reload = clean rebuild, which is false
  • They don’t know that old config files silently override new ones
  • They underestimate how aggressive Metro caching is
  • They try to fix symptoms (broken styles) instead of the root cause (misconfiguration)
  • They don’t realize that UI frameworks depend heavily on file structure
  • They rarely perform full dependency + config audits after upgrades

Juniors look for “the broken component,” while seniors look for “the broken pipeline.”

Leave a Comment