From 77ce4a1e18fdaf725a43d451d797237a4414f389 Mon Sep 17 00:00:00 2001 From: sra1kumar-NULL Date: Thu, 27 Jun 2024 12:18:26 +0530 Subject: [PATCH] feat: added migration guide --- .../Upgrade to v2/index.nw.stories.mdx | 573 +++++++++++++++++- 1 file changed, 570 insertions(+), 3 deletions(-) diff --git a/example/storybook-nativewind/src/home/overview/Upgrade to v2/index.nw.stories.mdx b/example/storybook-nativewind/src/home/overview/Upgrade to v2/index.nw.stories.mdx index 2581d53ed..a65617552 100644 --- a/example/storybook-nativewind/src/home/overview/Upgrade to v2/index.nw.stories.mdx +++ b/example/storybook-nativewind/src/home/overview/Upgrade to v2/index.nw.stories.mdx @@ -1,14 +1,581 @@ --- title: Upgrade to v2 | gluestack-ui -description: Upgrade to Gluestack UI v2 for enhanced performance, improved features, and better support. Follow our guide for a smooth and successful transition. +description: A migration guide is a document designed to help you seamlessly transition from your current gluestack ui version v1 to the new version v2. Whether you are upgrading, switching to a new version directly this guide provides step-by-step instructions, best practices, and troubleshooting tips to ensure a smooth migration process.. +pageTitle: Upgrade to v2 + +pageDescription: A migration guide is a document designed to help you seamlessly transition from your current gluestack ui version v1 to the new version v2. Whether you are upgrading, switching to a new version directly this guide provides step-by-step instructions, best practices, and troubleshooting tips to ensure a smooth migration process.. + +showHeader: true --- -import { Canvas, Meta, Story } from '@storybook/addon-docs'; +import { Meta } from '@storybook/addon-docs'; +import { Tabs, CollapsibleCode } from '@gluestack/design-system'; + + # Upgrade to v2 -Coming Soon! \ No newline at end of file +
+ +## **Installation** + +Run the below command to setup the project: + +``` +npx gluestack-ui@latest init +``` + +Above command will override certain files and add `gluestack-ui-provider`, + +- `tailwind.config.js` +- `global.css` +- `babel.config.js` / `next.config.*` +- `metro.config.js` +- `tsconfig.json` + +## Setup the GluestackUIProvider: + +Add the following code at the root of your project: + +**Before :** + +```jsx +import { GluestackUIProvider } from '@gluestack-ui/themed'; +export default function App() { + return ( + + {/* Your code */} + + ); +} +``` + +**After :** + +```jsx +import { GluestackUIProvider } from "@/components/ui/gluestack-ui-provider"; + export default function App() { + return ( + + {/* Your code */} + + ); } +``` + +## **Setup tailwind CSS:** + +Import `global.css` / `globals.css` where Tailwind directives are defined. + +```jsx + import { GluestackUIProvider } from "@/components/ui/gluestack-ui-provider"; + import "@/global.css" + + export default function App() { + return ( + + {/* Your code */} + + ); + } +``` + +## Component addition: + +To add all the components run the following command: + +```jsx +npx gluestack-ui@latest add --all +``` + +You can add only the necessary components instead of including all. Check [here](https://gluestack.io/ui/nativewind/docs/components/heading). + +```jsx +npx gluestack-ui@latest add heading +``` + +## Update config : + +### 1. If you are using `@gluestack-ui/config-v2` + +- If you are using `@gluestack-ui/config-v2`, there's no need to make any changes since the default NativeWind configuration is already similar. + +### 2 . If you are using `@gluestack-ui/config` or custom config or ejected config + +- In both of the cases, we should manually change the tailwind config respective to the style changes we made in the `gluestack-ui` configuration. + +For config conversion, the changes will be made to the config which is being passed to the provider in v2. + +### **Config conversion :** + +```jsx +// Gluestack-UI v1 + +// Without CSS Variables +{ + tokens: { + ...defaultConfig.tokens, + colors: { + ...defaultConfig.tokens.colors, + primary0: "#F5F3FF", + primary50: "#999999", + }, + }, +}; + +// Gluestack-UI v2 + +// With CSS variables +{ + light: vars({ + "--color-primary-0": "#F5F3FF", + "--color-primary-50": "#999999", + }), +}; + +// Updating the config(nativewind) file +{ + extends: { + colors: { + primary: var(--colors-primary), + }, + }, +}; + +// Different color modes +{ + light: vars({ + "--color-background-0": "#B3B3B3", + "--color-background-50": "#999999", + }), + dark: vars({ + "--color-background-0": "#111827", + "--color-background-50": "#171717", + }), +}; + +``` + +For Tailwind config configuration please refer to [this](https://tailwindcss.com/docs/configuration) . + +## Screens Migration + +### 1. Codemod + +- We made a codemod that will turn all your stylings in v1 code to v2 compatibility styles. +- All the styles will be converted matching the appropriate styling for that in NativeWind. +- Limitations: + - Descendant Styling ( As it’s not supported in NativeWind at the moment.) + - Value of `sx` prop is variable + +### Descendant Styling : + +- Descendant styling will not be resolved and we’ll keep it as it is. +- You can update it manually by moving it to the respective element where the style is required + +```jsx +// Before: +import { Box,Text } from "@gluestack-ui/themed"; + + + Simple Text + + +// After: +import { Box } from "@/components/ui/box"; +import { Text } from "@/components/ui/text"; + +// descendant style will remain as it is. + + Simple Text + + +// Update the descendant styling: +import { Box } from "@/components/ui/box"; +import { Text } from "@/components/ui/text"; + +// descendant style will remain as it is. + +// color:'white' --> text-white + + Simple Text + +``` + +### Usage : + +```jsx +npx @gluestack-ui/v2-codemod@latest +``` + +### 2. Manual Styling Changes + +To manually change the styling of any respective v1 specific style we can follow this property mapper to ideally convert the styles to `NativeWind` stylings. + +### Property Mapper : + +In this property mapper table you can find all the properties of v1 and how they can be written in v2 + +| Gluestack-UI v1 | Gluestack-UI v2 | +| --- | --- | +| underline={true} | className=”underline” | +| bold={true} | className=”font-*” | +| size={'*'} | className=”text-*” | +| bg=”*” / bgColor=”*” | className=”bg-*” | +| p=”*” | className=”p-*” | +| color=”*” | className=”color-*” / className=”text-*” | +| h={"*"} | className=”h-*” | +| w={"*"} | className=”w-*” | +| fontWeight=”*” | className=”font-*” | +| my=”*” | className=”my-*” | +| justifyContent=”*” | className=”justify-*” | +| alignItems=”*” | className=”items-*” | +| mx=”*” | className=”mx-*” | +| $dark={{ "*" :"*"}} | className=”dark:*” | +| px=”*” | className=”px-*” | +| borderColor=”*” | className=”border-*” | +| borderWidth=”*” | className=”border-*” | +| borderRightWidth=”*” | className=”border-r-*” | +| borderLeftWidth=”*” | className=”border-l-*” | +| borderTopWidth=”*” | className=”border-t-*” | +| borderBottomWidth=”*” | className=”border-b-*” | +| borderRadius=”*” / rounded=”*” | className=”rounded-*” | +| mt=”*” | className=”mt-*” | +| mb=”*” | className=”mb-*” | +| m=”*” | className=”m-*” | +| py=”*” | className=”py-*” | +| pt=”*” | className=”pt-*” | +| pb=”*” | className=”pb-*” | +| pl=”*” | className=”pl-*” | +| pr=”*” | className=”pr-*” | +| ml=”*” | className=”ml-*” | +| mr=”*” | className=”mr-*” | +| flex={"*"} | className=”flex-*” | +| flexDirection={"*"} | className=”flex-*” | +| lineHeight=”*” | className=”leading-*” | +| h={value} | className=’h-[value]’ | +| alignSelf=”*” | className=”self-*” | +| position=”*” | className=”position-*” | +| maxWidth={"*"} | className=”max-w-*” | +| maxHeight={"*"} | className=”max-h-*” | +| minWidth={"*"} | className=”min-w-*” | +| minHeight={"*"} | className=”min-h-*” | +| fontFamily=”*” | className=”font-*” | +| fontStyle=”*” | className=”*” | +| fontSize=”*” | className=”text-*” | +| top={"*"} | className=”top-*” | +| bottom={"*"} | className=”bottom-*” | +| left={"*"} | className=”left-*” | +| right={"*"} | className=”right-*” | +| zIndex={"*"} | className=”z-*” | +| shadowColor=”*” | className=”shadow-*” | +| overflow=”*” | className=”overflow-*” | +| textAlign=”*” | className=”text-*” | +| display=”*” | className=”hidden / flex / block / inline” | +| $sm={"*"} | className=”sm:*” | +| $md={"*"} | className=”md:*” | +| $lg={"*"} | className=”lg:*” | + + +### Property Combinations : + +| Gluestack-UI v1 | Gluestack-UI v2 | +| --- | --- | +| `$sm-`=`` / `$sm-bg`=`red500` | className=`sm:*` | +| `$sm-dark-`=`` / `$sm-dark-bg`= `*` | className=`sm:dark:-` | +| sx=`{{: }}` | className=`-` | +| `$dark-bg`=”*” / `$dark-color`=”*” / `$dark-%`=”*” | className=`dark:bg-*` / className=`dark:color-*` / className=`dark:%-*` | +| `$-property`=`value` | className=`mode::value` | +| sx=`{{ _dark: { :} }}` | className=`dark::` | +| sx=`{{_ios: {property: },_android: {property: }}}` | className=`ios:property- android:property-` | +| sx=`{{"@base": {_light: {property:},_dark: { property: }},"@md": {_light: { property: },_dark: { property: }}}` | className=”property-value dark:property-value md:property-value md:dark:property-value” | + +## Examples of some property combinations : + +**Applying styles in different color modes ( light/dark ) :** + +**Before:** + +```jsx +import { Box } from "@gluestack-ui/themed"; + +export default function App() { + return ( + + Simple Text + + ); +} +``` + +**After:** + +```jsx +import { Box } from "@/components/ui/box"; + +export default function App() { + return Simple Text; +} +``` + +**Applying styles for different media queries ( sm/md/lg ) using `@`:** + +**Before:** + +```jsx +import { Box } from "@gluestack-ui/themed"; + +export default function App() { + return ( + + Simple Box + + ); +} +``` + +**After:** + +```jsx +import { Box } from "@/components/ui/box"; + +export default function App() { + return ( + Simple Box + ); +} + +``` + +**Applying styles for different media queries ( sm/md/lg ) using `$` :** + +**Before:** + +```jsx +import { Box } from "@gluestack-ui/themed"; + +export default function App() { + return ( + + Simple Box + + ); +} +``` + +**After:** + +```jsx +import { Box } from "@/components/ui/box"; + +export default function App() { + return ( + Simple Box + ); +} +``` + +**Applying basic layout stylings :** + +**Before:** + +```jsx +import { Box } from "@gluestack-ui/themed"; + +export default function App() { + return ( + + Simple Box + + ); +} +``` + +**After:** + +```jsx +import { Box } from "@/components/ui/box"; + +export default function App() { + return Simple Box; +} +``` + +**Applying basic layout stylings in different color modes :** + +**Before:** + +```jsx +import { Box } from "@gluestack-ui/themed"; + +export default function App() { + return ( + + Simple Box + + ); +} +``` + +**After:** + +```jsx + +import { Box } from "@/components/ui/box"; + +//By default if you don't mention any mode it's take light mode. +export default function App() { + return Simple Box; +} +``` + +**Applying styles for different action states ( hover/active etc..,) :** + +**Before:** + +```jsx +import { Box } from "@gluestack-ui/themed"; + +export default function App() { + return ( + + Simple + + ); +} +``` + +**After:** + +```jsx +import { Box } from "@/components/ui/box"; + +//If not mentioned any mode explicitly then it's gonna take light mode only. +export default function App() { + return ( + + Simple + + ); +} +``` + +**Applying styles for different platforms ( mobile/web/android/ios) :** + +**Before:** + +```jsx +import { Text } from "@gluestack-ui/themed"; + +export default function App() { + return ( + + Gluestack + + ); +} +``` + +**After:** + +```jsx +import { Text } from "@/components/text"; + +export default function App() { + return Gluestack; +} +``` + +**Applying styles for different color modes at different media queries :** + +**Before:** + +```jsx +import { Center } from "@gluestack-ui/themed"; + +export default function App() { + return ( +
+ ); +} +``` + +**After:** + +```jsx +import { Center } from "@/components/center"; + +export default function App() { + return ( +
+ ); +} +``` + +**`Descendant Styling` ( we need to manually change these styling as this is not available in NativeWind) :** + +**Before:** + +```jsx +import { CheckboxLabel,Text } from "@gluestack-ui/themed"; + +export default function App() { + return ( + + Gluestack + + ); +} +``` + +**After:** + +```jsx +import { CheckboxLabel } from "@/components/checkbox"; +import { Text } from "@/components/text"; + +// we need to remove the descendant styling from parent element and add that +// styling to all the child elements +export default function App() { + return ( + + Gluestack + + ); +} +``` \ No newline at end of file