ui5wc-upgrade
Skill542 starsChanged 14 months agoApache-2.0View on GitHub
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.
- Commits and pushes
In this repository2 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- analytical-tableSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
27 rules. About 0 are common, 15 are distinctive, and 12 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈15
Distinctive · estimate
This author's own choices. Worth a look.
12
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 23
Follow each step in order.
- Distinctive: line 27
Ensure the working tree is clean before starting (git status should show no uncommitted changes).
- Very specific: line 38
Read the current version from root package.json → dependencies["@ui5/webcomponents"].
- Very specific: line 39
Check if Renovate already updated root deps — if dependencies["@ui5/webcomponents"] already matches target, note that Step 1a can be …
- Distinctive: line 42
If the whole upgrade may already have been applied, still reconcile and verify Step 1b before deciding whether wrapper generation needs to …
- Distinctive: line 53
Update to the exact target version:
- Very specific: line 63
Update the upstream tilde ranges to ~TARGET_VERSION and the compat package's internal React wrapper peer to ~TARGET_MAJOR.TARGET_MINOR.0.
- Distinctive: line 85
Run the exact-value validator (replace the example with the real target):
- Distinctive: line 126
All commands exit 0. Then check for new components:
- Very specific: line 133
If any command fails, see references/common-pitfalls.md.
- Distinctive: line 156
Read the current generated file for each component above.
- Very specific: line 157
Read the reference in references/custom-wrapper-code.md for the custom code to merge.
- Distinctive: line 160
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 …
- Distinctive: line 163
If the merge is possible but the generated code changed for these specific components (new props, changed types, updated JSDoc), inform the …
- Very specific: line 225
Check the UI5 Web Components release notes for theme additions/removals/consolidations.
- Very specific: line 227
If themes changed, follow references/theme-and-storybook-checklist.md.
- Very specific: line 255
Add a new story EXPORT to the parent component's existing .stories.tsx
- Very specific: line 256
Add the subcomponent to the parent's .mdx docs (import, Canvas, Description, ArgTypes)
- Distinctive: line 257
Do NOT create a separate story file
- Very specific: line 261
Create <ComponentDir>/<Name>.stories.tsx and <ComponentDir>/<Name>.mdx
- Distinctive: line 262
Follow the pattern of a similar existing component
- Distinctive: line 264
If no new components, skip this step.
- Distinctive: line 293
If none: "No breaking changes detected in generated wrappers."
- Very specific: line 309
If lint fails, try adding --fix first.
- Very specific: line 319
If new components were added, check that their exports are in correct alphabetical order in the package.json exports map.
- Distinctive: line 323
If new components were added (Step 6), update the category mapping:
- Distinctive: line 333
Verify it completes without "missing category definitions" errors.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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
- Parse the target version from the argument (e.g.
2.25.0or2.25.1). - Derive two peerDependency ranges:
- Upstream range:
~TARGET_VERSION(e.g.~2.25.1) for@ui5/webcomponents*packages. - React wrapper range:
~TARGET_MAJOR.TARGET_MINOR.0(e.g.~2.25.0) for the@ui5/webcomponents-reactpeer in the compat package. The wrapper release version is aligned to the UI5 Web Components minor, but it does not necessarily share the upstream patch version.
- Upstream range:
- Read the current version from root
package.json→dependencies["@ui5/webcomponents"]. - Check if Renovate already updated root deps — if
dependencies["@ui5/webcomponents"]already matches target, note that Step 1a can be skipped. Do not skip Step 1b: Renovate updating the root does not prove that package peerDependencies are correct. - If the whole upgrade may already have been applied, still reconcile and verify Step 1b before deciding whether wrapper generation needs to be re-run.
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-baseis NOT a direct root dependency — only update it in peerDependencies.
1b. Package peerDependencies
Update the upstream tilde ranges to ~TARGET_VERSION and the compat package's internal React
wrapper peer to ~TARGET_MAJOR.TARGET_MINOR.0. 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 → upstream range; @ui5/webcomponents-react → React wrapper range |
packages/cypress-commands/package.json | @ui5/webcomponents, -base |
Note:
packages/charts/package.jsonkeeps its established^2.21.0compatibility floor and does not need updating for minor version bumps. The validator confirms that it was not accidentally narrowed.
1c. Install
yarn installVerify
Run the exact-value validator (replace the example with the real target):
node skills/maintainer/ui5wc-upgrade/scripts/verify-peer-deps.mjs 2.25.1It verifies every mapped key against the correct range. Checking only for the old range is not
sufficient, because it cannot detect an incorrect upstream patch applied to the internal React peer.
For target 2.25.1, these values must coexist in compat:
"@ui5/webcomponents-compat": "~2.25.1",
"@ui5/webcomponents-react": "~2.25.0"Also confirm that no old minor range remains:
grep -r "~OLD_MINOR" packages/*/package.jsonThe validator and the old-range check must both pass before continuing.
Step 2: Compile CLI & Generate Wrappers
Run in sequence:
yarn create-webcomponents-wrapper
yarn create-webcomponents-wrapper-ai
yarn create-webcomponents-wrapper-compatEach 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:
- Read the current generated file for each component above.
- Read the reference in
references/custom-wrapper-code.mdfor the custom code to merge. - 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.
- 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.
- If the merge is possible but the generated code changed for these specific components (new props, changed types, updated JSDoc), inform the user that these components had generated changes that were merged with existing custom code.
Verify
git diff packages/compat/src/components/Table/index.tsx
git diff packages/compat/src/components/TableCell/index.tsx
git diff packages/compat/src/components/TableColumn/index.tsx
git diff packages/compat/src/components/TableGroupRow/index.tsx
git diff packages/compat/src/components/TableRow/index.tsx
git diff packages/main/src/webComponents/ExpandableText/index.tsxEach file should show ONLY the expected generated changes (updated props, JSDoc, etc.) while retaining all custom code blocks.
Step 3: Sync ThemingParameters
yarn create-theming-parametersVerify
git diff packages/base/src/styling/ThemingParameters.tsNote added/removed CSS variable mappings for the PR description.
Step 4: Update version-info.json
Edit config/version-info.json — add a new entry before the closing }:
"X.Y.0": "TARGET_VERSION"The key is the React wrapper minor version (X.Y.0), the value is the upstream @ui5/webcomponents target version from the argument. The React wrapper version itself is bumped by lerna during the release.
Verify
node -e "JSON.parse(require('fs').readFileSync('config/version-info.json','utf8'));console.log('OK')"Step 5: Check for Theme Changes
ls packages/main/src/themes/*.cssCompare against the Theme enum in packages/main/src/enums/Theme.ts.
Check the UI5 Web Components release notes for theme additions/removals/consolidations.
If themes changed, follow references/theme-and-storybook-checklist.md. If not, skip.
Step 6: Check for New Components (BEFORE build)
6a. Identify new components
From the git status --short ... | grep "^?" output in Step 2, look for new untracked directories under:
packages/main/src/webComponents/packages/ai/src/components/packages/compat/src/components/
6b. Update barrel exports
The wrapper generator does NOT update barrel index.ts files. For each new component, add an export line in alphabetical order:
packages/main/src/webComponents/index.ts→export * from './<Name>/index.js';packages/ai/src/components/index.ts(if AI component)packages/compat/src/components/index.ts(if compat component)
This must happen BEFORE yarn build — otherwise tsc won't compile new components into dist/, and create-exports will miss them.
6c. Stories and docs (can be done after build)
For abstract components (@abstract in JSDoc) or subcomponents (items/options that slot into a parent):
- Add a new story EXPORT to the parent component's existing
.stories.tsx - Add the subcomponent to the parent's
.mdxdocs (import, Canvas, Description, ArgTypes) - Do NOT create a separate story file
For standalone new components:
- Create
<ComponentDir>/<Name>.stories.tsxand<ComponentDir>/<Name>.mdx - Follow the pattern of a similar existing component
If no new components, skip this step.
Step 7: Check for Breaking Changes
From the wrapper diff, check:
7a. Removed or renamed props — deleted lines in interface *Attributes blocks.
7b. Changed event signatures — changes in event detail type imports.
7c. Removed components — entire component directories deleted.
7d. Impact on custom components:
grep -r "ChangedTypeName\|RemovedPropName" packages/main/src/components/Present findings prominently:
## BREAKING CHANGES DETECTED
### <ComponentName>
- Removed prop: `oldProp`
- Renamed: `oldName` → `newName`If none: "No breaking changes detected in generated wrappers."
Step 8: Build & Verify
yarn buildThen lint the changed wrapper files (full yarn lint may OOM on this repo):
node --max-old-space-size=8192 ./node_modules/.bin/eslint packages/main/src/webComponents/*/index.tsx packages/compat/src/components/*/index.tsx packages/ai/src/components/*/index.tsxIf lint fails, try adding --fix first.
8b. Generate export maps (requires dist/ from build)
yarn create-exportsThis reads dist/ directories to update package.json exports maps for new components.
If new components were added, check that their exports are in correct alphabetical order in the package.json exports map. create-exports may append them at the end — move them to the correct position manually.
8c. Update and rebuild MCP server
If new components were added (Step 6), update the category mapping:
packages/mcp-server/src/utils/component-config.ts— Add new components to the appropriate category array
Then rebuild:
yarn build:mcpVerify it completes without "missing category definitions" errors.
Verify
Build, lint, and create-exports all exit 0. Check if create-exports modified any package.json files:
git diff packages/*/package.jsonStep 9: Update Docs
Renovate handles examples, templates, and patterns — skip those.
Only update:
docs/Welcome.mdx— if theme list or version table changed- Component stories — if breaking changes affected story props
Step 10: Commit & PR
Commit
Review git status before staging. Only stage upgrade-related files — avoid sweeping git add -A if unrelated changes are present.
git add package.json yarn.lock config/version-info.json \
packages/*/package.json \
packages/main/src/webComponents/ \
packages/ai/src/components/ \
packages/compat/src/components/ \
packages/base/src/styling/ThemingParameters.ts \
.storybook/custom-element-manifests/
git commit -m "feat: update to UI5 Web Components X.Y.0"PR description template
## Summary
- Update `@ui5/webcomponents` family from A.B.C to X.Y.0
- Regenerated wrapper components for main, fiori, AI, and compat packages
- Synced ThemingParameters
## New Components
<!-- List or "None" -->
## Breaking Changes
<!-- List or "None detected" -->
## Theme Changes
<!-- List or "None" -->
## ThemingParameters Changes
<!-- Added/removed CSS variables or "None" -->Push & create PR
git push -u origin feat/ui5wc-X.Y.0
gh pr create --title "feat: update to UI5 Web Components X.Y.0" --body "<body>"Quick Reference: Scripts
| Script | Purpose |
yarn install | Install after version bumps |
yarn create-webcomponents-wrapper | Main + fiori wrappers + prettier + eslint + CEM |
yarn create-webcomponents-wrapper-ai | AI wrappers |
yarn create-webcomponents-wrapper-compat | Compat wrappers |
yarn create-theming-parameters | Regenerate ThemingParameters.ts |
yarn create-exports | Regenerate package.json exports maps (needs dist/) |
yarn build | Full monorepo build |
yarn build:mcp | Rebuild MCP server (after new components) |
yarn lint | ESLint (may OOM — use targeted lint instead) |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

