December 13, 2023

Why We Built gluestack-ui
Sanket Sahu
Building NativeBase

gluestack-ui v1.0 was launched almost a month back, and we are now 1000+ stars strong on GitHub. But as new users adopted the library quickly, we also got queries and concerns on how gluestack-ui compares with its predecessor NativeBase.
Key concerns were received from users with ongoing and finished projects dependent on NativeBase. We feel that their apprehension is valid and understand their perspective.
That is why we felt it would be best to share why we created a different library from the ground up without upgrading NativeBase. We also wanted to share what we are doing to address the concerns of current users of NativeBase through an intermediate library and a migration guide.

Quest for Universal

Universality in app development has been our goal from the beginning. We chased it relentlessly and envisioned creating a UI library that lets you "write once, run anywhere.”
The result was NativeBase.
It started well. NativeBase became a toolkit that provided everything essential for crafting interfaces that worked on the Web, iOS, and Android. It was loaded with styling libraries, components, APIs, universal functionalities, and many other features.
Not to mention, it became one of the most beloved React libraries around and was extensively used for major projects.
But the library had its own set of hiccups.

Challenges with NativeBase

As NativeBase expanded and consequently issues started surfacing, we encountered challenges in maintaining different parts of the library.
We can categorize these challenges into three buckets.
  1. Step
    Performance — The styling engine with NativeBase was all runtime, and with so many features packed in, it resulted in slower performance compared to pure React Native counterparts.
  2. Step
    Maintainability — The complex styling engine and component library needed different APIs. This made it difficult to maintain the library and bring in public contributors.
  3. Step
    Large Bundle Size — We packed all the components and features into a single bundle. Tree-shaking was needed to remove unused bundles on build time. This led to massive bundle sizes for just the NativeBase components.
Recognizing the importance of enhancing performance, usability, and maintainability, we went on to address these key areas.

Road to gluestack-ui

Our first instinct to fix NativeBase was to solve individual issues. But soon, we realized that it would be just patchwork. A real solution would be to rebuild NativeBase from the ground using the lessons we had learned.
We created a separate package for each component to allow incremental adoption. This solved the thing with bundle size. Users could now add components to a project using CLI.
Another key decision was to break down the library into two separate libraries.
  • gluestack-ui  - A set of ready-to-use and unstyled components that can be added to any project across any device and styled to fit your needs.
  • gluestack-style  - A highly performant styling and universal CSS-in-JS library.
This solved the complication that we faced with maintainability.
Further, we separated the UI library into Unstyled and Themed libraries for greater flexibility. More of that later.
So, in summary, we built a new library altogether because we wanted everything good from NativeBase, but none of the hiccups it was facing. Doing that on NativeBase’s architecture would have been difficult and messy. Hence, we decided to build something entirely new, which is now gluestack-ui.
💡 Why did we not call it NativeBase v4? Two reasons! First, gluestack-ui can co-exist with NativeBase v3 for incremental adoption and smoother migration. Second, it is a ground-up rewrite with many API changes.

Why Separate Styled and UI ?

The decision was made based on performance and maintainability. Unstyled UI components are easily reusable across projects, adapting to different visual styles through styling libraries.
This provided multiple advantages:
Separation of Concerns:
  • Enhances maintainability and understanding by separating component logic from styling.
  • Developers can focus on structure and functionality independently of visual presentation.
  • Designers can work on styles independently without affecting underlying component logic.
  • Enables use across various front-end frameworks for versatility.
  • Easier maintenance with clear separation of concerns.
  • Styling and functionality changes can be made independently.
  • Adaptable to design changes without modifying component logic.
Theming and Customization:
  • Facilitates theming and customization with separated components and styles.
  • Dynamic application of styles based on themes or user preferences.
  • Simplifies testing with components designed without styling.
Reduced Bundle Size:
  • Results in smaller bundle sizes for UI components.
Why Separate Unstyled and Themed Library?
A separate themed library enables a uniform and consistent design language across applications or projects. This facilitates quick development and prototyping with predefined styles for common UI components.
We built unstyled library to have a uniform and consistent API and functionality across applications or projects without being constrained by predefined base styles. This Avoids the inclusion of unnecessary styles, resulting in smaller bundle sizes and optimized applications.

Migrating from NativeBase to gluestack-ui

We understand that shifting from NativeBase to gluestack-ui is monumental. Therefore, we have tried to address the concerns of most users and provide solutions for each use case.
For our valued NativeBase users, we've introduced a purpose-built Migration library to make the transition to gluestack-ui hassle-free and efficient. The Migration library employs the same API as NativeBase, but under the hood, utilizes gluestack-ui components.
Since the Migration library acts as a layer on top of gluestack components, it isn’t as fast but still significantly outperforms NativeBase, providing a noticeable boost in performance.

Why We Recommend gluestack-ui

Universal Application
gluestack components are usable across all platforms - mobile or web, thus eliminating effort duplication and unnecessary overheads.
Highly Performant
With a Babel plugin for pre-computing styles during the build process and runtime performance optimizations, gluestack-ui delivers high-performance styling.
Great DX
VS Code Extension for ease of coding. Just type the name of the desired component and get the entire length of code written for you.
Accessible & Customizable Components
Fully operable and navigable components provide an allowance for personalization according to the use case.
Smaller Bundle Size
The unstyled library has been kept separate from the themed, resulting in a low bundle-size library. The fact that the libraries are tree-shakable and eliminate unused exports during the run process further results in an optimized bundle.
Easy Onboarding
Start your first gluestack-ui project with an easy one-line installation: npm create gluestack. A free starter kit is also provided for the developers to get a preview of the library.

Future of gluestack-ui

gluestack-ui v1.0 is just the tip of the iceberg. We will ensure that lessons learned materialize into a better developer experience and higher performance benchmarks. At the moment, we fare better than a few counterparts. The plan is to keep improving with your support.
GeekyAnts is also backing the library. That means better maintenance and accountability. We have started using it in our internal projects, which opens up opportunities to test the library in real-time applications. The learnings and fixes are being transferred.
Do keep supporting us and sharing thoughts on how gluestack-ui should progress. We would love to hear from you.
Reach out to us at email:

ui logo
Made with gluestack-ui