From e4ae6198dcd2058baf269ccf8099156e3f977301 Mon Sep 17 00:00:00 2001 From: Lukas Harbarth Date: Mon, 11 Aug 2025 14:15:03 +0200 Subject: [PATCH 1/7] feat: make `@ui5/webcomponents-fiori` peer-dependency optional --- README.md | 68 +++++++++++-------- docs/Welcome.mdx | 42 +++++++++--- packages/main/package.json | 3 + packages/main/scripts/generateI18n.mjs | 20 +++--- .../components/VariantManagement/index.tsx | 2 + 5 files changed, 88 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index 1e5b47da14e..9ecbfa7b7e2 100644 --- a/README.md +++ b/README.md @@ -74,12 +74,32 @@ You can find our documentation under the following links: ## Download and Installation -To consume `ui5-webcomponents-react`, you need to install the npm modules and required peer dependencies: +You can install `@ui5/webcomponents-react` along with the required peer-dependencies based on the components you plan to use. **In most cases, the recommended installation is the most maintainable option.** + +### Recommended Installation + +Install `@ui5/webcomponents-react` along with the `@ui5/webcomponents` and `@ui5/webcomponents-fiori` peer-dependencies as dependencies in your project: ```sh npm install @ui5/webcomponents-react @ui5/webcomponents @ui5/webcomponents-fiori ``` +**Note:** If you import anything from another `@ui5/webcomponents-xyz` package, we recommend installing it as a (dev-)dependency as well, even if it’s already included through another package. + +### Minimal Installation + +Since version `v2.14.0` of `@ui5/webcomponents-react`, `@ui5/webcomponents-fiori` is an optional peer-dependency. You will still need to install it if: + +- You want to use any [component](https://sap.github.io/ui5-webcomponents/components/fiori/) from the `@ui5/webcomponents-fiori` package. +- You want to use the [VariantManagement](https://sap.github.io/ui5-webcomponents-react/v2/?path=/docs/inputs-variantmanagement--docs) component. +- You import anything from the `@ui5/webcomponents-fiori` package. + +**Note:** Most popular bundlers enable tree-shaking for production builds, so there’s no difference in the final bundle size between the recommended and minimal installations. + +```sh +npm install @ui5/webcomponents-react @ui5/webcomponents-fiori +``` + ## End of Support for Version 1.x The support for version 1.x of `ui5-webcomponents-react` has ended on **July 1, 2025**. We recommend migrating to version 2.x as soon as possible. For more information, please refer to our [Migration Guide](https://sap.github.io/ui5-webcomponents-react/v2/?path=/docs/migration-guide--docs). @@ -110,38 +130,32 @@ You can find a curated list of project templates and examples on our [Project Te ### Add `@ui5/webcomponents-react` to an existing app -First of all, you need to add the `@ui5/webcomponents-react` dependency to your project. Please also keep in mind installing the required peer dependencies: +1. Install all [required dependencies](#download-and-installation) -```sh -npm install @ui5/webcomponents @ui5/webcomponents-react @ui5/webcomponents-fiori -``` +2. Import the `ThemeProvider` component and wrap your root component with it: -In order to use `@ui5/webcomponents-react` you have to wrap your application's root component into the `ThemeProvider`.
-You will find this component most likely in `src/index.js`: - -```jsx -import { ThemeProvider } from '@ui5/webcomponents-react'; -... -const root = createRoot(document.getElementById("root")); -root.render( - - - -); -``` + ```tsx + import { ThemeProvider } from '@ui5/webcomponents-react'; + ... + createRoot(document.getElementById('root') as HTMLElement).render( + + + , + ); + ``` -Then you are ready to use `@ui5/webcomponents-react` and you can import the desired component(s) in your app:
-For example, to use the `Button` component you need to import it: +3. Use `@ui5/webcomponents-react` components in your app by importing them. + For example, to use the `Button` component you need to import it: -```jsx -import { Button } from '@ui5/webcomponents-react'; // loads ui5-button wrapped in a ui5-webcomponents-react component -``` + ```jsx + import { Button } from '@ui5/webcomponents-react'; // loads ui5-button wrapped in a ui5-webcomponents-react component + ``` -Then, you can use the Button in your app: +4. Add the imported component to your JSX: -```jsx - -``` + ```jsx + + ``` ### Browser Support diff --git a/docs/Welcome.mdx b/docs/Welcome.mdx index f191874ad40..de14123dad3 100644 --- a/docs/Welcome.mdx +++ b/docs/Welcome.mdx @@ -46,33 +46,53 @@ In about an hour you will create a business dashboard from scratch and get famil You can find a curated list of project templates and examples on our [Project Templates & Examples page](?path=/docs/project-templates-examples--docs). -### Add `@ui5/webcomponents-react` to an existing app +### Download and Installation -First of all, you need to add the `@ui5/webcomponents-react` dependency to your project. Please also keep in mind installing the required peer dependencies: +You can install `@ui5/webcomponents-react` along with the required peer-dependencies based on the components you plan to use. **In most cases, the recommended installation is the most maintainable option.** + +#### Recommended Installation + +Install `@ui5/webcomponents-react` along with the `@ui5/webcomponents` and `@ui5/webcomponents-fiori` peer-dependencies as dependencies in your project: ```sh -npm install @ui5/webcomponents @ui5/webcomponents-react @ui5/webcomponents-fiori +npm install @ui5/webcomponents-react @ui5/webcomponents @ui5/webcomponents-fiori ``` -#### Versions Table +**Note:** If you import anything from another `@ui5/webcomponents-xyz` package, we recommend installing it as a (dev-)dependency as well, even if it’s already included through another package. + +#### Minimal Installation + +Since version `v2.14.0` of `@ui5/webcomponents-react`, `@ui5/webcomponents-fiori` is an optional peer-dependency. You will still need to install it if: + +- You want to use any [component](https://sap.github.io/ui5-webcomponents/components/fiori/) from the `@ui5/webcomponents-fiori` package. +- You want to use the [VariantManagement](https://sap.github.io/ui5-webcomponents-react/v2/?path=/docs/inputs-variantmanagement--docs) component. +- You import anything from the `@ui5/webcomponents-fiori` package. + +**Note:** Most popular bundlers enable tree-shaking for production builds, so there’s no difference in the final bundle size between the recommended and minimal installations. + +```sh +npm install @ui5/webcomponents-react @ui5/webcomponents-fiori +``` + +### Version Alignment & Package Mapping -In order to use `@ui5/webcomponents-react` you have to wrap your application's root component into the `ThemeProvider`.
-You will find this component most likely in `src/index.js`: +### Using UI5 Web Components for React -```jsx +In order to use `@ui5/webcomponents-react` you have to wrap your application's root component into the `ThemeProvider` component. + +```tsx import { ThemeProvider } from '@ui5/webcomponents-react'; ... -const root = createRoot(document.getElementById("root")); -root.render( +createRoot(document.getElementById('root') as HTMLElement).render( - + , ); ``` -Then you are ready to use `@ui5/webcomponents-react` and you can import the desired component(s) in your app:
+Then you are ready to use `@ui5/webcomponents-react` and you can import the desired component(s) in your app. For example, to use the `Button` component you need to import it: ```jsx diff --git a/packages/main/package.json b/packages/main/package.json index acf41f34a6d..7c216d05849 100644 --- a/packages/main/package.json +++ b/packages/main/package.json @@ -76,6 +76,9 @@ }, "@ui5/webcomponents-icons": { "optional": true + }, + "@ui5/webcomponents-fiori": { + "optional": true } }, "publishConfig": { diff --git a/packages/main/scripts/generateI18n.mjs b/packages/main/scripts/generateI18n.mjs index d95206c446c..133fc9e9cc6 100644 --- a/packages/main/scripts/generateI18n.mjs +++ b/packages/main/scripts/generateI18n.mjs @@ -58,15 +58,17 @@ spawnSync('npx', ['prettier', '--write', path.resolve(SRC_I18N_PROPERTIES, 'i18n // generate Assets.js and Assets-fetch.js const jsonImports = await readdir(TARGET_I18N_JSON_IMPORTS); -const assets = [`import '@ui5/webcomponents/dist/Assets.js';`, `import '@ui5/webcomponents-fiori/dist/Assets.js';`]; -const assetsFetch = [ - `import '@ui5/webcomponents/dist/Assets-fetch.js';`, - `import '@ui5/webcomponents-fiori/dist/Assets-fetch.js';`, -]; -const assetsNode = [ - `import '@ui5/webcomponents/dist/Assets-node.js';`, - `import '@ui5/webcomponents-fiori/dist/Assets-node.js';`, -]; +function createDynamicFioriAssetsImport(suffix) { + return `try { + await import('@ui5/webcomponents-fiori/dist/Assets${suffix}.js'); +} catch { + console.warn("Skipped '@ui5/webcomponents-fiori/dist/Assets${suffix}.js' import!") +}`; +} + +const assets = [`import '@ui5/webcomponents/dist/Assets.js';`, createDynamicFioriAssetsImport('')]; +const assetsFetch = [`import '@ui5/webcomponents/dist/Assets-fetch.js';`, createDynamicFioriAssetsImport('-fetch')]; +const assetsNode = [`import '@ui5/webcomponents/dist/Assets-node.js';`, createDynamicFioriAssetsImport('-node')]; for (const file of jsonImports) { if (file.includes('-fetch')) { diff --git a/packages/main/src/components/VariantManagement/index.tsx b/packages/main/src/components/VariantManagement/index.tsx index b674d8df1df..d0e16a679f9 100644 --- a/packages/main/src/components/VariantManagement/index.tsx +++ b/packages/main/src/components/VariantManagement/index.tsx @@ -63,6 +63,8 @@ const booleanProps = { * * __Note:__ Each `VariantManagement` component can only have one default and one selected variant. * + * __Note:__ Additionally to the mandatory `@ui5/webcomponents` package, you also need to install `@ui5/webcomponents-fiori` to use this component. + * * ### Matching header styles * * To ensure consistent header styles for different use-cases of the `VariantManagement`, we recommend setting the following styles to the `ui5-title` component: From afd4e4989db3f36dbeb8c3d64273d53eb80cd395 Mon Sep 17 00:00:00 2001 From: Lukas Harbarth Date: Mon, 11 Aug 2025 14:18:09 +0200 Subject: [PATCH 2/7] run `yarn i` --- packages/main/package.json | 4 ++-- yarn.lock | 2 ++ 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/packages/main/package.json b/packages/main/package.json index 7c216d05849..c8ba250cb71 100644 --- a/packages/main/package.json +++ b/packages/main/package.json @@ -74,10 +74,10 @@ "@ui5/webcomponents-base": { "optional": true }, - "@ui5/webcomponents-icons": { + "@ui5/webcomponents-fiori": { "optional": true }, - "@ui5/webcomponents-fiori": { + "@ui5/webcomponents-icons": { "optional": true } }, diff --git a/yarn.lock b/yarn.lock index 4d2a2dfdcc3..46d9048026b 100644 --- a/yarn.lock +++ b/yarn.lock @@ -4745,6 +4745,8 @@ __metadata: optional: true "@ui5/webcomponents-base": optional: true + "@ui5/webcomponents-fiori": + optional: true "@ui5/webcomponents-icons": optional: true languageName: unknown From 278641a64f2ef7f8fa1e8177ef2fa36a73454ea5 Mon Sep 17 00:00:00 2001 From: Lukas Harbarth Date: Mon, 11 Aug 2025 14:31:36 +0200 Subject: [PATCH 3/7] use IIFE for fiori assets import --- packages/main/scripts/generateI18n.mjs | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/packages/main/scripts/generateI18n.mjs b/packages/main/scripts/generateI18n.mjs index 133fc9e9cc6..88626b389ea 100644 --- a/packages/main/scripts/generateI18n.mjs +++ b/packages/main/scripts/generateI18n.mjs @@ -59,11 +59,13 @@ spawnSync('npx', ['prettier', '--write', path.resolve(SRC_I18N_PROPERTIES, 'i18n const jsonImports = await readdir(TARGET_I18N_JSON_IMPORTS); function createDynamicFioriAssetsImport(suffix) { - return `try { - await import('@ui5/webcomponents-fiori/dist/Assets${suffix}.js'); -} catch { - console.warn("Skipped '@ui5/webcomponents-fiori/dist/Assets${suffix}.js' import!") -}`; + return `(async () => { + try { + await import('@ui5/webcomponents-fiori/dist/Assets${suffix}.js'); + } catch { + console.warn("Skipped '@ui5/webcomponents-fiori/dist/Assets${suffix}.js' import!"); + } +})();`; } const assets = [`import '@ui5/webcomponents/dist/Assets.js';`, createDynamicFioriAssetsImport('')]; From ffcd75059492c48a3908bf2f726072a9e2569501 Mon Sep 17 00:00:00 2001 From: Lukas Harbarth Date: Mon, 11 Aug 2025 14:57:41 +0200 Subject: [PATCH 4/7] Update generateI18n.mjs --- packages/main/scripts/generateI18n.mjs | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/packages/main/scripts/generateI18n.mjs b/packages/main/scripts/generateI18n.mjs index 88626b389ea..133fc9e9cc6 100644 --- a/packages/main/scripts/generateI18n.mjs +++ b/packages/main/scripts/generateI18n.mjs @@ -59,13 +59,11 @@ spawnSync('npx', ['prettier', '--write', path.resolve(SRC_I18N_PROPERTIES, 'i18n const jsonImports = await readdir(TARGET_I18N_JSON_IMPORTS); function createDynamicFioriAssetsImport(suffix) { - return `(async () => { - try { - await import('@ui5/webcomponents-fiori/dist/Assets${suffix}.js'); - } catch { - console.warn("Skipped '@ui5/webcomponents-fiori/dist/Assets${suffix}.js' import!"); - } -})();`; + return `try { + await import('@ui5/webcomponents-fiori/dist/Assets${suffix}.js'); +} catch { + console.warn("Skipped '@ui5/webcomponents-fiori/dist/Assets${suffix}.js' import!") +}`; } const assets = [`import '@ui5/webcomponents/dist/Assets.js';`, createDynamicFioriAssetsImport('')]; From 07b216fe88c8032638519590909cfabedf58a090 Mon Sep 17 00:00:00 2001 From: Lukas Harbarth Date: Mon, 11 Aug 2025 16:59:48 +0200 Subject: [PATCH 5/7] phrasing Co-authored-by: Marcus Notheis --- packages/main/src/components/VariantManagement/index.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/main/src/components/VariantManagement/index.tsx b/packages/main/src/components/VariantManagement/index.tsx index d0e16a679f9..e4680107975 100644 --- a/packages/main/src/components/VariantManagement/index.tsx +++ b/packages/main/src/components/VariantManagement/index.tsx @@ -63,7 +63,7 @@ const booleanProps = { * * __Note:__ Each `VariantManagement` component can only have one default and one selected variant. * - * __Note:__ Additionally to the mandatory `@ui5/webcomponents` package, you also need to install `@ui5/webcomponents-fiori` to use this component. + * __Note:__ You have to install `@ui5/webcomponents-fiori` to use this component. * * ### Matching header styles * From 2996b7192ed01f216dac5f45e858d3b7449dc643 Mon Sep 17 00:00:00 2001 From: Lukas Harbarth Date: Mon, 11 Aug 2025 17:02:33 +0200 Subject: [PATCH 6/7] fix typo --- README.md | 2 +- docs/Welcome.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 9ecbfa7b7e2..46ca9aeb2cd 100644 --- a/README.md +++ b/README.md @@ -97,7 +97,7 @@ Since version `v2.14.0` of `@ui5/webcomponents-react`, `@ui5/webcomponents-fiori **Note:** Most popular bundlers enable tree-shaking for production builds, so there’s no difference in the final bundle size between the recommended and minimal installations. ```sh -npm install @ui5/webcomponents-react @ui5/webcomponents-fiori +npm install @ui5/webcomponents-react @ui5/webcomponents ``` ## End of Support for Version 1.x diff --git a/docs/Welcome.mdx b/docs/Welcome.mdx index de14123dad3..d007dbff595 100644 --- a/docs/Welcome.mdx +++ b/docs/Welcome.mdx @@ -71,7 +71,7 @@ Since version `v2.14.0` of `@ui5/webcomponents-react`, `@ui5/webcomponents-fiori **Note:** Most popular bundlers enable tree-shaking for production builds, so there’s no difference in the final bundle size between the recommended and minimal installations. ```sh -npm install @ui5/webcomponents-react @ui5/webcomponents-fiori +npm install @ui5/webcomponents-react @ui5/webcomponents ``` ### Version Alignment & Package Mapping From 554b9c8a2dda7457f76f5b0d38924108362a00e5 Mon Sep 17 00:00:00 2001 From: Lukas Harbarth Date: Mon, 11 Aug 2025 17:18:45 +0200 Subject: [PATCH 7/7] phrasing --- README.md | 2 +- docs/Welcome.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 46ca9aeb2cd..cf08d69743c 100644 --- a/README.md +++ b/README.md @@ -84,7 +84,7 @@ Install `@ui5/webcomponents-react` along with the `@ui5/webcomponents` and `@ui5 npm install @ui5/webcomponents-react @ui5/webcomponents @ui5/webcomponents-fiori ``` -**Note:** If you import anything from another `@ui5/webcomponents-xyz` package, we recommend installing it as a (dev-)dependency as well, even if it’s already included through another package. +**Note:** If you import anything from another `@ui5/webcomponents-xyz` package, we recommend installing it as a dependency as well, even if it’s already included through another package. ### Minimal Installation diff --git a/docs/Welcome.mdx b/docs/Welcome.mdx index d007dbff595..ed23d6efbc4 100644 --- a/docs/Welcome.mdx +++ b/docs/Welcome.mdx @@ -58,7 +58,7 @@ Install `@ui5/webcomponents-react` along with the `@ui5/webcomponents` and `@ui5 npm install @ui5/webcomponents-react @ui5/webcomponents @ui5/webcomponents-fiori ``` -**Note:** If you import anything from another `@ui5/webcomponents-xyz` package, we recommend installing it as a (dev-)dependency as well, even if it’s already included through another package. +**Note:** If you import anything from another `@ui5/webcomponents-xyz` package, we recommend installing it as a dependency as well, even if it’s already included through another package. #### Minimal Installation