/ui5wc-upgrade

name: ui5wc-upgrade
description: Guide a complete UI5 Web Components version upgrade in the ui5-webcomponents-react monorepo. Updates root and peer dependencies, regenerates wrapper components, syncs theming parameters, updates version-info, detects new components and breaking changes, and verifies the build. Use when a new @ui5/webcomponents version is released and the monorepo needs upgrading.
disable-model-invocation: true
argument-hint: target version (e.g. 2.22.0)
allowed-tools:
  - Bash(yarn create-webcomponents-wrapper*)
  - Bash(yarn create-webcomponents-wrapper-ai*)
  - Bash(yarn create-webcomponents-wrapper-compat*)
  - Bash(yarn create-theming-parameters*)
  - Bash(yarn create-exports*)
  - Bash(yarn install*)
  - Bash(yarn build*)
  - Bash(yarn build:mcp*)
  - Bash(yarn lint*)
metadata:
  internal: true

UI5 Web Components Upgrade Protocol

Follow each step in order. Do NOT skip verification gates.

Prerequisites

Ensure the working tree is clean before starting (`git status` should show no uncommitted changes). The upgrade touches many files across multiple packages, and a dirty tree makes it hard to isolate upgrade-related changes and risks committing unrelated work.

Initialization

1. Parse the **target version** from the argument (e.g. `2.25.0` or `2.25.1`). 2. Derive the **tilde range** `~TARGET_VERSION` for peerDependencies (e.g. `~2.25.1`). 3. Read the **current version** from root `package.json` → `dependencies["@ui5/webcomponents"]`. 4. If current matches target, ask if the user wants to re-run wrapper generation only (skip to Step 2). 5. Check if Renovate already updated root deps — if `dependencies["@ui5/webcomponents"]` already matches target, note that Step 1a can be skipped.

---

Step 1: Update Dependencies

1a. Root `package.json`

Skip if Renovate already handled this.

Update to the exact target version:

**dependencies:** `@ui5/webcomponents`, `@ui5/webcomponents-fiori`, `@ui5/webcomponents-ai`, `@ui5/webcomponents-compat`, `@ui5/webcomponents-icons`

**devDependencies:** `@ui5/webcomponents-tools`

> `@ui5/webcomponents-base` is NOT a direct root dependency — only update it in peerDependencies.

1b. Package peerDependencies

Update tilde ranges to `~TARGET_VERSION` in all sub-packages. See `references/package-json-peer-deps.md` for the exact map. Summary:

| File | Keys to update | | ---------------------------------------- | ------------------------------------------------------- | | `packages/main/package.json` | `@ui5/webcomponents`, `-base`, `-fiori`, `-icons` | | `packages/base/package.json` | `@ui5/webcomponents-base` | | `packages/ai/package.json` | `@ui5/webcomponents-ai` | | `packages/compat/package.json` | `@ui5/webcomponents-compat`, `@ui5/webcomponents-react` | | `packages/cypress-commands/package.json` | `@ui5/webcomponents`, `-base` |

> **Note:** `packages/charts/package.json` uses caret ranges (`^`) and does **not** need updating for minor version bumps.

1c. Install

yarn install

Verify

grep -r "~OLD_MINOR" packages/*/package.json

Must return zero results (replace OLD_MINOR with the previous minor version tilde range).

---

Step 2: Compile CLI & Generate Wrappers

Run in sequence:

yarn create-webcomponents-wrapper
yarn create-webcomponents-wrapper-ai
yarn create-webcomponents-wrapper-compat

Each script compiles the CLI internally before generating. No separate `tsc` step needed.

`create-webcomponents-wrapper` already runs prettier, eslint --fix, and `sb:prepare-cem`.

Verify

All commands exit 0. Then check for new components:

git diff --stat
git status --short -- packages/main/src/webComponents/ packages/ai/src/components/ packages/compat/src/components/ | grep "^?"

If any command fails, see `references/common-pitfalls.md`.

---

Step 2b: Restore Custom Code in Generated Wrappers

The wrapper generator overwrites ALL files, including ones with hand-written customizations. These components have custom code that MUST be restored after every generation run. See `references/custom-wrapper-code.md` for the exact code to restore.

**Components with custom code:**

| Component | Package | Custom Code | | ---------------- | ------- | ----------------------------------------------------------------------------------- | | `ExpandableText` | main | `addCustomCSSWithScoping` for whitespace, `DeprecatedExpandableTextProps` interface | | `Table` | compat | `getCompatCustomElementsScopingSuffix` + tag name suffix | | `TableCell` | compat | Same scoping suffix pattern | | `TableColumn` | compat | Same scoping suffix pattern | | `TableGroupRow` | compat | Same scoping suffix pattern | | `TableRow` | compat | Same scoping suffix pattern |

**Procedure:**

1. Read the current generated file for each component above. 2. Read the reference in `references/custom-wrapper-code.md` for the custom code to merge. 3. Merge the custom code into the generated output. The generated types/props/JSDoc may have changed — integrate the custom additions with the new generated base. 4. If a generated change conflicts with the custom code in a way that cannot be automatically resolved (e.g., a type the custom code depends on was removed), **STOP and inform the user** with details of the conflict. 5. If the merge is possible but the generated code changed for these specific components (new prop