| name | kendo-react-version-upgrade |
| description | Guides KendoReact version upgrades, including breaking changes and safe migration paths. Use when a developer asks whether an upgrade is safe, what changed between versions, how to plan a multi-version upgrade path, or how to prepare before running migration tools. This skill provides guidance and reasoning about upgrades; it does not execute migrations. For execution, it bridges to the Kendo CLI (`kendo migrate`) and the MCP server. Do NOT use for first-time install (route to kendo-react-getting-started) or for licensing failures unrelated to version coverage (route to kendo-react-product-licensing). Trigger on "Should I upgrade KendoReact?", "Is it safe to go from v12 to v15?", "What broke in v15?", "How do I upgrade KendoReact?", "kendo migrate", "breaking changes between versions", "my components broke after npm update", "themeColor dark light removed", "ref returns Handle instead of class", "icon names changed", "TKL102 version not covered", "perpetual license upgrade", "what changed in the latest release", "should I skip versions", "upgrade path", "codemod migration", "npm-check-updates kendo". |
KendoReact Version Upgrade Skill
Purpose
This skill teaches agents how to reason about KendoReact version upgrades — what changed, what to watch out for, and how to approach upgrades safely.
It helps agents explain why an upgrade might be risky or beneficial and what preparation is needed, rather than executing migrations directly. The skill provides guidance, not execution: actual code changes are handled by the Kendo CLI (kendo migrate) and the MCP server's Component Assistant.
This skill does not replace release notes, migration guides, or the official breaking changes documentation. It teaches agents how to interpret and apply that information in context.
Reference files
references/breaking-changes-by-version.md — Per-version summaries of breaking changes for v9 through v15. Read when the developer asks about a specific version or a specific version-to-version upgrade path.references/response-templates.md — Ready-made response text for common upgrade scenarios.
Scope Boundaries
This skill covers:
- Explaining the KendoReact versioning model (semver, co-released packages, theme alignment)
- Helping developers decide whether to upgrade, when, and how aggressively
- Identifying which versions introduce breaking changes and what kind
- Recommending safe upgrade paths (consecutive majors vs. version skipping)
- Flagging common upgrade pitfalls that lead to support tickets
- Explaining license implications of upgrading (perpetual coverage windows, TKL102)
- Bridging to the Kendo CLI and MCP for execution once the decision is made
This skill does not cover:
- First-time install or onboarding — route to
kendo-react-getting-started
- Licensing failures unrelated to version coverage — route to
kendo-react-product-licensing
- MCP entitlement failures — route to
kendo-react-mcp-licensing
- Executing code changes — defer to
kendo migrate or the MCP Component Assistant
- Detailed component API changes — defer to the official breaking changes docs
KendoReact Versioning Model
Agents must understand these rules before giving upgrade advice.
versioning_rules:
co_release: >
All @progress/kendo-react-* packages are released together and share
the same version number. You cannot mix v14 Grid with v15 DateInputs.
semver:
major: Breaking changes in the API. Application code may need updates.
minor: New features. Existing code continues to work.
patch: Bug fixes only. No code changes needed.
theme_alignment: >
When upgrading KendoReact packages, you MUST also update the
@progress/kendo-theme-* packages to the latest compatible version.
Mismatched theme versions cause styling regressions.
package_json_range: >
The default caret range (^14.0.0) allows minor and patch updates
but blocks major version bumps. Running 'npm update' within a major
is safe. Crossing a major requires explicit version changes.
Theme Compatibility
The @progress/kendo-theme-* packages (Default, Bootstrap, Material, Fluent) are decoupled from the KendoReact component packages and follow their own version numbering. KendoReact and theme major versions do not track each other (e.g., KendoReact v9 uses themes v10). The changelog is the authoritative source. All four themes always require the same version for any given KendoReact release.
KendoReact-to-Theme Compatibility Matrix
Extracted from the KendoReact changelog (https://www.telerik.com/kendo-react-ui/components/changelogs/ui-for-react).
theme_matrix:
v14.3.0_to_v14.4.x: '^13.1.1'
v14.2.0_to_v14.2.1: '^13.0.1'
v14.0.0_to_v14.1.1: '^13.0.0'
v13.0.0_to_v13.3.0: '^12.2.3'
v12.0.0_to_v12.2.0: '^12.0.0'
v11.0.0_to_v11.4.0: '11.0.2 to 11.3.2'
v10.0.0_to_v10.2.0: '^10.3.1 to ^10.4.0'
v9.0.0_to_v9.5.0: '^10.0.1 to ^10.2.0'
theme_compatibility_rules:
version_mismatch_warning: >
KendoReact and theme major versions DO NOT track each other.
Do not assume KendoReact v14 uses themes v14 — it uses themes v13.
Always check the matrix or the changelog's "Supported Themes" block.
upgrade_rule: >
After every KendoReact upgrade, check the "Supported Themes" block in the
changelog for your target version and upgrade themes to match.
Command: npx npm-check-updates --upgrade --filter "/@progress/kendo-theme.*/"
downgrade_risk: >
Do NOT upgrade themes without also upgrading KendoReact packages —
newer themes may expect rendering changes from newer component versions.
cdn_rule: >
If using a CDN link for themes, pin the theme version explicitly.
Never use an unpinned CDN URL in production.
theme_breaking_changes:
themes_v13:
era: February 2026
impact: high
Version History Map
Versions with documented breaking changes. Agent should consult references/breaking-changes-by-version.md for the specific changes in each version.
breaking_change_versions:
v9:
release_era: 2023
risk_level: moderate
summary: Early major with API standardization changes.
v10:
release_era: 2024
risk_level: moderate
summary: Component API refinements.
v11:
release_era: 2024
risk_level: moderate
summary: Grid, DateInputs, Dialogs, TreeList changes. First version with codemod support.
codemods_available: true
v12:
release_era: 2024
risk_level: low
summary: Chat component changes only. Codemod available.
codemods_available: true
v14:
Upgrade Decision Framework
When a developer asks "should I upgrade?", the agent should work through this checklist rather than defaulting to "always upgrade to latest."
upgrade_decision:
1_why_upgrade:
questions:
- What motivates the upgrade? (new feature, bug fix, security, policy, React version)
- Is there a specific component fix or feature in the target version?
- Is the team being asked to stay current for compliance or support reasons?
guidance: >
If the motivation is a specific bug fix available in a patch or minor,
upgrade within the current major first — that's zero-risk under semver.
2_what_version_are_they_on:
questions:
- What is their current @progress/kendo-react-* version?
Safe Upgrade Path Logic
upgrade_path_rules:
within_same_major:
risk: none
action: 'npm update (within caret range) or npx npm-check-updates --upgrade --filter "/@progress/kendo-react.*/"'
notes: No breaking changes. Always safe.
one_major_ahead:
risk: low to moderate
action: >
1. Read the breaking changes for the target version (references/breaking-changes-by-version.md).
2. Run 'kendo migrate' if codemods are available for that boundary.
3. Review any code comments added by the codemod.
4. Update theme packages to match.
5. Test.
notes: This is the recommended upgrade unit.
multiple_majors_ahead:
risk: high
action: >
Do NOT jump directly. Walk through each major boundary one at a time.
For example, v10 → v11 → v12 → v13 → v14 → v15.
At each step, run 'kendo migrate' and resolve breaking changes before
proceeding to the next.
notes: >
The Kendo CLI's 'kendo migrate --from X --to Y' handles this
sequentially, but the developer should review and test at each step.
skipping_versions:
risk: very high
do_not_recommend: true
notes: >
Skipping versions (e.g., v10 straight to v15) compounds breaking
changes and makes it impossible to isolate which change broke what.
The only exception is if the project uses very few components with
no ref access, no themeColor customization, and no icon usage.
Assisted Migration Tooling
The Kendo CLI provides automated codemods for major version migrations.
kendo_migrate:
command: 'kendo migrate'
alternative: 'npx @progress/kendo-cli migrate'
available_since: KendoReact 11 + Kendo CLI 1.9.0
what_it_does:
- Checks for available updates (including peer dependencies)
- Applies codemods that transform JSX, imports, props, and event handlers
- Adds code comments where manual review is needed
codemods_available:
v10_to_v11: Grid, DateInputs, Dialogs, TreeList
v11_to_v12: Chat
v13_to_v14: Dropdowns (groupMode removal), Chat (sendButton,
MCP Bridge
Once the developer has decided to upgrade and understands the scope, the MCP server can assist with execution.
mcp_upgrade_assistance:
kendo_component_assistant:
use_for: >
Help updating specific component usage after a major version upgrade.
The Component Assistant knows the current API and can suggest correct
prop names, event handlers, and import paths for the target version.
handle: '#kendo_component_assistant'
kendo_ui_generator:
use_for: >
Regenerating a page or component from scratch using the latest API
when the upgrade delta is too large to patch incrementally.
handle: '#kendo_ui_generator'
kendo_getting_started_assistant:
use_for: >
Setting up the MCP server if the developer doesn't have it configured.
Available to all license types including free.
handle: '#kendo_getting_started_assistant'
requirement: >
MCP tools require an active Trial or Subscription license.
Perpetual licenses do not include MCP tools.
Common Upgrade Pitfalls
pitfalls:
theme_version_mismatch:
symptom: Components look broken or unstyled after upgrade.
cause: KendoReact packages upgraded but @progress/kendo-theme-* left on the old version.
resolution: Always upgrade theme packages alongside component packages.
frequency: Very common — the
custom_css_selectors_broken_by_theme_upgrade:
symptom: Custom styles stop applying after theme upgrade.
cause: >
Themes R1 2026 restructured class names — fill mode and theme color are
now separate classes (k-button-solid k-button-primary instead of
k-button-solid-primary). Custom CSS targeting the old combined names breaks.
resolution: >
Audit custom CSS for combined Kendo class selectors. Update to the new
two-class pattern. See the Design System docs for the full mapping.
Routing Rules
route_to_kendo_react_getting_started_when:
- Developer is installing KendoReact for the first time (not upgrading)
- Developer asks about tiers, trials, or onboarding
route_to_kendo_react_product_licensing_when:
- TKL102 appears (version not covered by perpetual license)
- Any licensing issue unrelated to version coverage
route_to_kendo_mcp_licensing_when:
- MCP tools return PERMISSION_DENIED (entitlement, not version)
stay_in_this_skill_when:
- Developer asks "should I upgrade?"
- Developer asks what
Security
This skill is a static, read-only knowledge layer. It does not execute commands, modify code, or access the developer's file system. All migration execution is deferred to the Kendo CLI and the developer's own terminal.
security_model:
skill_is_read_only: true
skill_does_not_execute: true
skill_does_not_phone_home: true
skill_does_not_access_code: true
skill_does_not_modify_package_json: true
For distribution integrity and threat-surface analysis, see the security section in kendo-react-getting-started.
Anti-Patterns
avoid:
- Recommending "always upgrade to latest" without assessing the developer's situation.
- Recommending a multi-major jump (e.g., v10 → v15) without sequential migration.
- Listing all breaking changes from all versions when the developer only needs one boundary.
- Running or suggesting 'npm update' when a major version boundary is involved.
- Treating TKL102 as a setup bug — it is
