feat: make @ui5/webcomponents-fiori peer-dependency optional (#7640)

Lukas742 · MarcusNotheis · web-flow · commit da20bb60cf30 · 2025-09-04T11:30:52.000+02:00
Closes #7720 --------- Co-authored-by: Marcus Notheis <marcus.notheis@sap.com>
diff --git 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 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
+```
+
 ## 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`.<br/>
-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(
-        <ThemeProvider>
-          <App />
-        </ThemeProvider>
-);
-```
+   ```tsx
+   import { ThemeProvider } from '@ui5/webcomponents-react';
+   ...
+   createRoot(document.getElementById('root') as HTMLElement).render(
+     <ThemeProvider>
+       <App />
+     </ThemeProvider>,
+   );
+   ```
 
-Then you are ready to use `@ui5/webcomponents-react` and you can import the desired component(s) in your app:<br />
-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
-<Button onClick={() => alert('Hello World!')}>Hello world!</Button>
-```
+   ```jsx
+   <Button onClick={() => alert('Hello World!')}>Hello world!</Button>
+   ```
 
 ### Browser Support
 
diff --git 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 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
+```
+
+### Version Alignment & Package Mapping
 
 <VersionTable />
 
-In order to use `@ui5/webcomponents-react` you have to wrap your application's root component into the `ThemeProvider`.<br/>
-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(
   <ThemeProvider>
     <App />
-  </ThemeProvider>
+  </ThemeProvider>,
 );
 ```
 
-Then you are ready to use `@ui5/webcomponents-react` and you can import the desired component(s) in your app:<br />
+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
@@ -74,6 +74,9 @@
     "@ui5/webcomponents-base": {
       "optional": true
     },
+    "@ui5/webcomponents-fiori": {
+      "optional": true
+    },
     "@ui5/webcomponents-icons": {
       "optional": true
     }
diff --git 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
@@ -63,6 +63,8 @@ const booleanProps = {
  *
  * __Note:__ Each `VariantManagement` component can only have one default and one selected variant.
  *
+ * __Note:__  You have 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:
diff --git a/yarn.lock b/yarn.lock
@@ -5004,6 +5004,8 @@ __metadata:
       optional: true
     "@ui5/webcomponents-base":
       optional: true
+    "@ui5/webcomponents-fiori":
+      optional: true
     "@ui5/webcomponents-icons":
       optional: true
   languageName: unknown

Original file line number	Diff line number	Diff line change
`@@ -63,6 +63,8 @@ const booleanProps = {`
`63`	`63`	`*`
`64`	`64`	* __Note:__ Each `VariantManagement` component can only have one default and one selected variant.
`65`	`65`	`*`
	`66`	+ * __Note:__ You have to install `@ui5/webcomponents-fiori` to use this component.
	`67`	`+ *`
`66`	`68`	`* ### Matching header styles`
`67`	`69`	`*`
`68`	`70`	* To ensure consistent header styles for different use-cases of the `VariantManagement`, we recommend setting the following styles to the `ui5-title` component: