cumulocity-iot/migration

Cumulocity Web SDK Migration Skill

Overview

This skill guides you through a full migration of a Cumulocity Web SDK application from one version to another. It combines three tools into a single repeatable workflow:

1. ui-breaking-changes-cli — detect every breaking change between the two SDK versions
2. new-app skill — scaffold a clean reference project at the target version
3. code-quality-analysis skill — verify the migrated code meets quality standards

---

Prerequisites

Before starting, identify:

| Variable | Description | Example | |---|---|---| | FROM_VERSION | Your current @c8y/ngx-components version | y2025-lts, 1021.22.50 | | TO_VERSION | The target SDK version | y2026-lts, cd | | PROJECT_ROOT | Absolute path to the app you are migrating | /home/user/my-c8y-app |

To find your current version:

cat package.json | grep '@c8y/ngx-components'

---

Step 1 — Detect Breaking Changes

Use the ui-breaking-changes-cli to get a full report of everything that changed between your current and target versions.

Install the CLI

Download the latest .tgz from the GitHub Releases page, then extract and run it directly — no global install required:

tar -xzf c8y-breaking-changes-cli-v*.*.*.tgz

Alternatively, build from source:

git clone https://github.com/Cumulocity-IoT/ui-breaking-changes-cli.git
cd ui-breaking-changes-cli
pnpm install
pnpm build

Run the report

The CLI accepts several version alias formats for --from and --to:

| Format | Examples | |---|---| | LTS alias | y2025-lts, y2026-lts | | Year alias | y2025, y2026 | | Minor / stable line | 1021, 1023, 1021.22 | | Full patch version | 1021.22.145, 1023.13.2 | | Continuous delivery | cd — resolves to the current latest tag on npm |

Version format: use the y-prefixed dist-tag form (y2026-lts) — this is what npm dist-tags @c8y/websdk will show and what the breaking-changes-cli resolves against. The un-prefixed form (2026-lts) is also accepted by the CLI but is not a real npm tag.

# Human-readable overview
node index.js --from <FROM_VERSION> --to <TO_VERSION>

# Markdown output — paste into a PR or issue for tracking
node index.js --from <FROM_VERSION> --to <TO_VERSION> --format markdown

# Breaking changes only (suppress NOTABLE / INFO noise)
node index.js --from <FROM_VERSION> --to <TO_VERSION> --breaking-only

# Angular-specific breaking changes only
node index.js --from <FROM_VERSION> --to <TO_VERSION> --breaking-only --category angular

# Generate grep patterns to locate affected symbols in your codebase
node index.js --from <FROM_VERSION> --to <TO_VERSION> --show-grep

Process the report

For each item in the report:

1. Note the severity (BREAKING, NOTABLE, INFO) and category (angular, websdk-ui, rest-api, security, migration).
2. Use the grep patterns from --show-grep to find affected usages in the project:

   grep -rn "<symbol>" <PROJECT_ROOT>/src
   

3. Create a tracking list of all BREAKING items — these must be resolved before the app will compile or run correctly.

---

Step 2 — Scaffold a Reference App at the Target Version

Read and follow the new-app skill (skills/new-app/SKILL.md) to generate a fresh application at TO_VERSION. Use a temporary directory so it does not interfere with the project being migrated:

mkdir /tmp/c8y-reference-app
cd /tmp/c8y-reference-app
# … follow new-app skill steps with ng add @c8y/websdk@<TO_VERSION> (e.g. y2026-lts)

The reference app provides the canonical shape of every generated file at the target version — use it as the ground truth for the comparison in Step 3.

---

Step 3 — Compare Configuration Files

Diff the following files between the reference app (target version) and your project (current version). For each file, apply the changes needed to align your project with the new structure.

Files to compare

| File | What to look for | |---|---| | src/app/app.ts | ApplicationOptions, feature flags, runTime / buildTime changes | | src/bootstrap.ts | Bootstrap function signature, standalone vs. module-based setup | | angular.json | builder targets, styles array, assets paths, budget thresholds | | package.json | @c8y/* package versions, peer dependency constraints, scripts | | src/app/app.module.ts | Module imports, lazy-loaded routes, removed / replaced modules | | src/app/app-routing.module.ts | Route guards, lazy chunk syntax changes | | tsconfig.json / tsconfig.app.json | target, lib, strictTemplates, decorator metadata |

How to diff

Use VS Code's built-in diff, or run:

diff -u <PROJECT_ROOT>/<file> /tmp/c8y-reference-app/<file>

Or with git diff for colour output:

git diff --no-index <PROJECT_ROOT>/<file> /tmp/c8y-reference-app/<file>

Applying changes

For each diffed file:

1. Copy new config keys / builder options that are missing from your project.
2. Remove keys that no longer exist in the reference app (they may have been renamed or deprecated).
3. Cross-reference with the breaking-changes report from Step 1 to confirm each change is intentional.
4. Do not blindly overwrite — preserve any project-specific customisations (app name, branding, custom routes, environment files).

---

Step 4 — Apply Breaking-Change Fixes in Source Code

For each BREAKING item identified in Step 1:

1. Use the grep pattern to find all occurrences in src/.
2. Apply the fix described in the breaking-change entry (rename, API replacement, import path change, removed option, etc.).
3. After each fix, run the TypeScript compiler to catch regressions:

   npx tsc --noEmit
   

4. Optionally run the Angular build to surface template errors:

   ng build --configuration development
   

Repeat until tsc --noEmit and ng build both succeed without errors.

---

Step 5 — Code Quality Review

Read and follow the code-quality-analysis skill (skills/code-quality-analysis/SKILL.md) to run a full quality pass over the migrated source code.

Pay special attention to:

• AP-01 — replace any leftover *ngIf / *ngFor / *ngSwitch with Angular's new control flow syntax (@if, @for, @switch) if the target version supports it.
• AP-02 — excessive logic in components that should be moved to services.
• Any Cumulocity-specific anti-patterns flagged by the mcp_c8y-docs_query-codex queries (MCP server: https://c8y-codex-mcp.schplitt.workers.dev/ — see AGENTS.md for setup).

Address all BREAKING and HIGH severity findings before considering the migration done.

---

Checklist

Use this checklist to track migration progress:

• [ ] FROM_VERSION and TO_VERSION identified
• [ ] Breaking-changes report generated (--format markdown saved for reference)
• [ ] All BREAKING items catalogued
• [ ] Reference app scaffolded at TO_VERSION
• [ ] app.ts compared and updated
• [ ] bootstrap.ts compared and updated
• [ ] angular.json compared and updated
• [ ] package.json @c8y/* versions bumped and peer deps resolved
• [ ] app.module.ts / routing compared and updated
• [ ] tsconfig.json compared and updated
• [ ] All BREAKING source-code fixes applied
• [ ] tsc --noEmit passes
• [ ] ng build passes
• [ ] Code quality analysis completed
• [ ] All HIGH quality findings resolved