Admin App breaking changes

Overview

PREREQUISITES: The described breaking changes are introduced in version Sitefinity CMS 15.4.8640.

Sitefinity CMS 15.4.8640 upgrades the Admin App from Angular 19 to Angular 21, and from Kendo UI for Angular 18.5 to Kendo UI for Angular 23.2. This article explains how these upgrades affect your Admin App extensions and custom styling, and how to rebuild your extensions. It applies when you upgrade from a Sitefinity CMS version earlier than 15.4.8640.

Admin App extensions are webpack bundles. At runtime, the Admin App provides @angular/*, rxjs, tslib, and the Admin App extensibility API to your extensions, and the import.plugin.ts plugin in the build folder of the extensions project replaces the imports of these packages with references to the copies in the Admin App. For this reason, the Angular major version that you use to build your extensions must match the Angular major version of the Admin App.

IMPORTANT: Extensions that are built on Angular 19 are not guaranteed to work with Sitefinity CMS 15.4.8640 and later. After you upgrade, rebuild your extensions on Angular 21.

The public Admin App extensibility API in @progress/sitefinity-adminapp-sdk is not changed. You use classes such as ExtensionBase, the command, field, and grid extension points, and the dependency injection tokens the same way as before.

Who is affected

Summary of changes

Rebuild your extensions

Prerequisites

PREREQUISITES: Before you rebuild your extensions, ensure the following:

• You have installed Node.js ^20.19.0, ^22.12.0, or >=24.0.0. Angular 21, Angular CLI 21, and ESLint 10 do not support earlier Node.js versions, including Node.js 16, Node.js 18, and Node.js 20 versions earlier than 20.19.
• You use TypeScript 5.9.x. Angular 21 does not support earlier TypeScript versions.

Get the extensions project for your Sitefinity CMS version

If you started your extensions project from a copy of the Sitefinity Admin App extensions repository, the simplest way to migrate is to take the Angular 21 version of the build files from the repository and reapply your own code and customizations. If you maintain your own project structure, perform the procedures in the following sections.

1. Clone the Sitefinity GitHub repository » Sitefinity Admin App extensions, or open your existing copy.

2. Check out the tag that matches your Sitefinity CMS version and update the samples submodule.
   For example, for Sitefinity CMS 15.4.8640, run the following commands:

   bash

   git checkout 15.4.8640.0
   git submodule update --init --recursive

   To find your Sitefinity CMS version, in the main menu, click Administration » Version and Licensing.

Update the dependencies

The following table lists the dev dependency versions that the extensions repository uses:

The linting packages are consolidated as follows:

For the authoritative list of versions, see the package.json file at the repository tag that matches your Sitefinity CMS version.

To update the dependencies, perform the following:

1. In your package.json file, update the dev dependencies to the versions listed above.

2. Delete the node_modules folder and the package-lock.json file.

   • On Windows, run the following command in PowerShell:

     powershell

     Remove-Item -Recurse -Force node_modules, package-lock.json

   • On macOS and Linux, run the following command:

     bash

     rm -rf node_modules package-lock.json

3. Install the packages:

   bash

   npm install

NOTE: @progress/sitefinity-adminapp-sdk declares Angular peer dependencies <=19.2.x. As a result, npm install might stop with an ERESOLVE error. In this case, run npm install --legacy-peer-deps or npm install -f. If you install the packages from the lock file of the extensions repository with npm ci, this error does not occur.

Update the tsconfig.json file

In the compilerOptions section of the tsconfig.json file, perform the following:

1. Change the value of moduleResolution from node to bundler.
2. Remove the lib option.
   TypeScript then uses the default libraries for the ES2022 target, including the DOM. If your code relies on specific lib entries, keep them.

The following example shows the relevant compiler options after the change:

{
  "compilerOptions": {
    "module": "es2020",
    "moduleResolution": "bundler",
    "target": "ES2022"
  }
}

Update the angular.json file

By default, Angular CLI 20 and later generate files without type suffixes, such as .component, .service, and .directive. To keep the file naming of the samples, for example, foo.component.ts and foo.service.ts, add the following schematics section at the end of the angular.json file:

"schematics": {
  "@schematics/angular:component": { "type": "component" },
  "@schematics/angular:directive": { "type": "directive" },
  "@schematics/angular:service": { "type": "service" },
  "@schematics/angular:guard": { "typeSeparator": "." },
  "@schematics/angular:interceptor": { "typeSeparator": "." },
  "@schematics/angular:module": { "typeSeparator": "." },
  "@schematics/angular:pipe": { "typeSeparator": "." },
  "@schematics/angular:resolver": { "typeSeparator": "." }
}

This setting affects only the files that you generate with ng generate. If you do not need this file naming, skip this step.

Update the build folder

The build folder of the extensions repository contains the custom webpack configuration and the import plugin. These files work with Angular 21 with only one typing change in import.plugin.ts. If you copied the build folder to your project, replace it with the latest version from the repository.

If you keep your own build folder, in the import.plugin.ts file, change the declaration of delegatedModuleId from let delegatedModuleId = null; to let delegatedModuleId;.

Migrate to the ESLint flat config

ESLint 10 supports only the flat config format. To migrate, perform the following:

1. Delete the .eslintrc.json, .eslintignore, and .eslintcache files.
2. Copy the eslint.config.mjs file from the extensions repository to the root of your project.
3. Add .eslintcache to your .gitignore file.

You run npm run lint and ng lint the same way as before.

Update your extension code

Build your extensions against Angular 21 and TypeScript 5.9 and fix the reported errors. Use the official Angular update guide and select the upgrade from version 19 to 20, and then from version 20 to 21.

For the changes that are most relevant to Admin App extensions, see Angular changes that affect extension code.

Build and deploy your extensions

1. Start the development server:

   bash

   npm start

   The Admin App is served on http://localhost:3000.

2. Verify that your extensions load and work against your Sitefinity CMS instance.
   For more information about configuring Sitefinity CMS for extension development, see Sitefinity GitHub repository » Configure Sitefinity CMS for development of custom extensions.

3. Build the extensions bundle:

   bash

   npm run build

   To build a minified bundle, run npm run build:prod.

4. From the dist folder, copy the generated *.extensions.bundle.js file.

5. In the adminapp folder of your Sitefinity CMS web application, replace the old bundle with the new one.

6. Restart Sitefinity CMS.

Angular changes that affect extension code

Angular 21 and TypeScript 5.9 are stricter than Angular 19 and TypeScript 5.5. Review your extension code against the changes below. For the complete list of changes, see the Angular release notes for 20.0.0 and 21.0.0.

Removed and changed APIs

• InjectFlags is removed. inject(), Injector.get(), and TestBed.inject() no longer accept it.
• TestBed.get() and TestBed.flushEffects() are removed. Use TestBed.inject() and TestBed.tick() instead.
• NgModuleFactory is removed, together with the moduleId and interpolation component options.
• Injector.get() no longer has the overload that accepts and returns any.
• afterRender is renamed to afterEveryRender.
• provideExperimentalZonelessChangeDetection is renamed to provideZonelessChangeDetection, and provideExperimentalCheckNoChangesForDebug is renamed to provideCheckNoChangesConfig.
• UpgradeAdapter is removed.
• Import ApplicationConfig from @angular/core instead of from @angular/platform-browser.
• In templates, in and void are reserved operators. To reference a member named void, use this.void.
• Type checking of host bindings (typeCheckHostBindings) is enabled by default. Existing type errors in host bindings can fail the build.
• In development mode, ng-reflect-* attributes are no longer emitted by default. Tests or CSS selectors that depend on these attributes stop working.
• The new FormArray directive can conflict with custom directives or inputs named FormArray.
• In the Router, lastSuccessfulNavigation is now a signal, and navigation can take more asynchronous steps to complete. This can change the timing in your tests.
• AsyncPipe now reports errors to ErrorHandler. In tests, uncaught listener errors are thrown again.

Deprecated APIs

The following APIs are deprecated, but are still available in Angular 21. You do not need to change them now.

• *ngIf, *ngFor, and *ngSwitch
  The recommended replacements are the built-in @if, @for, and @switch blocks. To migrate your templates automatically, run ng generate @angular/core:control-flow.
• ComponentFactoryResolver
• HammerJS
• @angular/platform-browser-dynamic

For example, in the print-preview.component.html file of the print preview sample, the following template:

<h1 *ngIf="dataItem" [textContent]="dataItem.Title"></h1>
<h1 *ngIf="!dataItem">Loading..</h1>

is replaced with the following template:

@if (dataItem) {
  <h1 [textContent]="dataItem.Title"></h1>
}
@if (!dataItem) {
  <h1>Loading..</h1>
}

TypeScript and third-party packages

• TypeScript 5.9 has stricter type checking. Expect to fix implicit any and type inference errors in your custom code.
• Any additional npm packages that your extensions use must be compatible with Angular 21 and with the supported Node.js versions.

Kendo UI changes

All Kendo UI for Angular packages in the Admin App are upgraded from 18.5.2 to 23.2.2, and the Kendo default theme is upgraded from 10.2.0 to 13.1.1. Kendo UI for jQuery, which the HTML editor uses, is upgraded from 2025.4.1321 to 2026.2.520.

The Admin App uses Kendo UI in the date and time pickers, the tree views in selectors, the pager, the splitter, charts, tooltips, icons, and the HTML field editor.

NOTE: Extensions do not inherit Kendo UI from the Admin App. The Admin App shares only @angular/*, rxjs, tslib, and the Admin App extensibility API with your extensions.

Breaking changes in Kendo UI

The following changes are relevant if you use custom CSS in the Admin App, or if your extensions bundle Kendo UI for Angular:

For more information, see the following Telerik resources:

• Kendo UI for Angular changelog
• Kendo UI for Angular rendering changes
• Kendo UI for Angular system requirements
• Kendo theme breaking changes in version 11, version 12, and version 13

Visual and markup changes in the Admin App

The following changes are visible in the Admin App. They indicate what you might see if you use custom styling:

• Date and time pickers
  The layout of the calendar and clock toggle buttons is changed, and Kendo UI uses its own font icons. The .k-widget class is no longer rendered. The .k-input and .k-picker elements have a border and overflow: hidden.
• Calendar
  The day cells have a different default shape and hover style.
• HTML editor toolbar
  The k-toolbar-solid, k-toolbar-md, and k-button-solid modifier classes are no longer applied. As a result, standalone toolbar buttons use the default outline appearance.
• MVC pages in the frontend
  The Telerik.Web.UI stylesheet loads after the Admin App styles and overrides some .k-input styles. The Admin App compensates for this. However, custom stylesheets that reset .k-* classes can still interfere with the Admin App.

Verify your custom styling and extensions

• If you override Kendo UI .k-* selectors or Kendo theme variables in the Admin App, verify the appearance after the upgrade. Pay particular attention to tree views, buttons, date and time pickers, and the HTML editor toolbar.
• If your extensions bundle their own Kendo UI for Angular components, use a version that supports Angular 21 and verify your extensions against the new theme. Kendo UI for Angular 23.2.2 supports Angular 19 to 21.

Other changes in the Admin App

The Admin App also updates third-party libraries that it uses internally. These libraries are not shared with extensions. The following updates might affect your users:

• oidc-client-ts is upgraded to 3.5.0, which adds validation of the ID token nonce. If your users sign in with external identity providers, test the sign-in after the upgrade.
• dompurify is upgraded to 3.4.0, which includes upstream security fixes. The sanitizer is stricter against attack payloads. The allowed lists of elements and attributes are not changed.

Troubleshooting