RFC: gluestack-ui v2 release

[surajahmed]

Summary

We are planning to release gluestack-ui v2, which includes significant changes and new features designed to enhance performance, improve the developer experience, and provide more flexible, customizable components.

Motivation

gluestack-ui v2 aims to address several limitations identified in the previous version. By adopting a more modular architecture and leveraging the power of NativeWind for styling, we strive to offer a highly performant, easily integrable, and accessible components.

Key Features and Changes

Incremental Adoption

• Selective Usage: Developers can now choose only the components they need, eliminating unnecessary bundle sizes and allowing for incremental adoption.
• Modular Approach: Components are distributed individually, allowing developers to import and use only the parts they need, reducing the initial setup and maintenance overhead.

Styling Engine: NativeWind

• Tailwind ClassName Support: NativeWind is used as the styling engine, enabling Tailwind class names for seamless customization and styling.

• Universal App Development: Tailwind classes facilitate the development of universal apps compatible with Expo and Next.js.

• Example:

  import { Button, ButtonText } from '@/components/ui/button';
  
  const MyComponent = () => (
    <Button className="bg-blue-500">
      <ButtonText className="text-typgraphy-500">Click Me</ButtonText>
    </Button>
  );

RSC Compatibility

• React Server Components: Components are designed to be compatible with React Server Components (RSC), enabling parts of the application to be rendered on the server. This reduces the client-side JavaScript required, leading to faster load times and improved performance.

Non-Bundled Library

• Avoid Unnecessary Bloat: gluestack-ui v2 is not a pre-packaged dependency. Developers can copy-paste the required components directly into their projects, ensuring only the necessary code is included.

Default Primary Color

• Neutral Default Design: The default primary color is now set to gray to ensure a non-opinionated design by default. Existing users can easily update their configuration to adopt this change.

Improved Developer Experience

• Performance Optimization: The library is designed to be highly performant, ensuring fast load times and efficient resource usage.
• Easy Integration: Components can be seamlessly integrated into projects with simple copy-paste functionality.
• Comprehensive Documentation: Enhanced documentation provides clear guides and examples to help developers quickly get up to speed.

Similar API and Patterns

We are maintaining similar APIs and patterns in gluestack-ui v2 as in the previous version. The only significant change is in the styling API, making it easier for developers to transition without needing to learn new usage patterns.

Tested and Proven

We have tested gluestack-ui v2 extensively with multiple projects, and the results have been impressive. Here are some example projects where gluestack-ui v2 has been successfully implemented:

• Storybook (https://storybook-v2.gluestack.io/)
• Dashboard App (https://ui-example-nativewind.vercel.app/)

Upgrade from v1

To help existing v1 users get started with gluestack-ui v2, we have prepared detailed migration guide:

• Migration Guide

Adoption Strategy

To adopt gluestack-ui v2, developers should follow these steps:

1. Install Required Dependencies: Ensure that NativeWind and Tailwind CSS are set up in the project.
2. Import and Use Components: Copy the necessary components from the gluestack-ui v2 library into the project.
3. Customize with Tailwind: Use Tailwind CSS classes to customize the components as needed.
4. Leverage RSC: For projects using React Server Components, ensure the components are utilized to take advantage of server-side rendering.
5. Update Configuration for Existing Users: Existing users need to update their configuration to adopt the new default primary color and other changes.
6. To help new users get started with gluestack-ui v2, we have prepared detailed installation document:
   • Installation guide

Example Usage

import { Button, ButtonText } from '@/components/ui/button';

const MyComponent = () => (
  <Button className="bg-blue-500">
    <ButtonText className="text-typgraphy-500">Click Me</ButtonText>
  </Button>
);

Conclusion

We are planning to release gluestack-ui v2 and are seeking comments and feedback from the community. This release represents a major step forward in creating a more performant, customizable, and developer-friendly component library. By focusing on incremental adoption, leveraging NativeWind for styling, and ensuring RSC compatibility, we aim to provide developers with the tools they need to build modern, responsive, and accessible web applications.

Please review this RFC and provide your feedback. Your input is valuable to ensure that gluestack-ui v2 meets the needs and expectations of the developer community.

---

Feel free to adjust any part of this RFC as needed for your specific context and requirements.

[kaumac]

Am I correct to assume that the utility/SX props will be dropped? I'm coming from Tamagui to Gluestack and I decided to use gluestack exactly because of the utility/SX props. Not a big fan of the tailwind class hell to be honest.

[ankit-tailor]

I've been working on a Babel plugin that adds support for utility props for Tailwind classes. It transforms utility props into class names during the build time, ensuring zero runtime overhead. I'm considering releasing it to the public.

You can check it out here: https://github.com/ankit-tailor/utility-wind/

I'd love to hear your thoughts!

[FezVrasta]

@ankit-tailor thanks for the utility, I guess there's no support for typescript intellisense right?

[ankit-tailor]

I am working on typescript support to get it correct for all cases. So the idea is to have a script that will create a TS declaration file and extend all the existing interfaces.

[kaumac]

@ankit-tailor I think using a plugin could be fine, but it should be integrated into v2. If classNames were the default and I had to use a 3rd party lib/plugin to have a decent DX for me it'd be a red flag.

[surajahmed]

@kaumac Unfortunately, the utility/SX props feature will be dropped by default. However, we can develop a Babel plugin to support these useful utility props. This plugin will internally convert utility props to classNames.

[FezVrasta]

That's a big no for me, class hell is terrible and utility props are so much nicer to work with, especially with typescript help.

[kaumac]

Yeah personally I'd be a big no for me too. I think the className mess + lack of TS support makes for a very bad DX.

I think the plugin could be a way but it should be throughly documented and the process streamlined. If the plugin is a separate project that is treated like not 1st class citizen it'd be a red flag for me.

[surajahmed]

Thanks for your feedback!

We're prioritizing universal app development, and by incorporating NativeWind, we can create RSC-compatible components and reduce the learning curve for web developers while taking advantage of other Tailwind features. We're committed to ensuring this Babel plugin works seamlessly, along with TypeScript, to provide an excellent developer experience. Your concerns are important to us, and we'll make sure the plugin is well-documented.

[kaumac]

That's great to hear @surajahmed !

It's always nice to see OSS maintainers listening to community feedback, I believe that leads to the best projects.
Looking forward to the outcome of this effort! 🚀

[tiagobnobrega]

Hi. I think Tailwind integration is a great addition. Does it mean we should be able to use class-variance-authority, tailwind-merge and clsx?

[Viraj-10]

Yes, we have a wrapper around tailwind-variant for adding variants and we also have cn function inside our @gluestack-ui/nativewind-utils with clsx and tailwind-merge combined.

[ofersadgat]

Personally, my use case wants a run-time evaluated library (think about a code-pen like component) which is what attracted me to the current styling system. I'll probably stay on that for as long as possible.

[surajahmed]

@ofersadgat gluestack-ui v2 will offer low-level components with styling that you can copy and paste to build your own component library, which you can then use as needed.

[evelant]

I just discovered Gluestack and IMO going with NativeWind is a great decision. My team has generally stayed away from UI libraries because they have invariably ended up lacking necessary customization options or having performance problems. I think the Gluestack v2 approach of cloning components into the project where they can then be tailored to the specific use case with the power of tailwind is a really unique solution that strikes the perfect balance. Great stuff! 🎉 🚀 🎸 😃

[PPHelios]

Is it going to support RTL layout?

[Viraj-10]

Hey @PPHelios, all our components come with RTL support by default. If you encounter any issues, please create an issue on GitHub. We are happy to help and will fix any bugs you report.

[SantoJambit]

Any plans on when this will be released?

Generally, I like the idea of tailwind, as the IDE/intellisense support for the props-based configuration is very bad and seems inconsistent at times (I've just started looking into gluestack a week ago).

My concerns: Nativewind seems to be developed by a single developer (looking at the commit history) and the last "release" of Nativewind v4 (which is still canary) dates back 5 months. There doesn't seem to be a timeline for a release either: nativewind/nativewind#724 (comment)

[Viraj-10]

Hey @SantoJambit, we released the beta version last week. Regarding your concern about nativewind v4, we are in sync with its contributors, who will be releasing a stable version in the upcoming weeks. Additionally, this project is now managed by Expo, as the creator of the repository works there.

[markgaucher]

My implementation of Gluestack v1 relies on @gluestack-style/react (for applying base styles consumed by functions like createButton) and the GluestackUIProvider config value (for applying a brand). Does the migration to NativeWind in v2 change that?

The documentation gets into customizing tokens, but it doesn't mention whether it's possible to customize components via config. Is it still possible to customize components in the same way as v1, or has that changed as well?

[Viraj-10]

Hey @markgaucher, the low-level accessibility functions like createButton remain the same. In gluestack-ui v2, the only changes are in the styling library, switching from gluestack-style/react to nativewind v4.

[Viraj-10]

We have a codemod to assist you in migrating from v1 to v2. However, if you prefer not to migrate, v1 remains stable, and we will continue to resolve any bugs. Any bug fixes for low-level functions will also be released for v1. We do recommend migrating to v2, as it is very similar to v1 in terms of API. Additionally, the copy-pastable components make integration easy. If you encounter any difficulties during the migration, please let us know, and our team will personally assist you.