refactor: Support of referencing legacy middlewares in UI5 CLI middleware configuration (#1367)

JIRA: CPOUI5FOUNDATION-1206

---------

Co-authored-by: Copilot <copilot@github.com>

Author: d3xter666

internal/documentation/docs/pages/Server.md

@@ -25,6 +25,12 @@ Please be aware of the following risks when using the server:
 
 ## Standard Middleware
 
+::: info Removed Middleware
+The `serveThemes` middleware has been removed in UI5 CLI v5. Theme compilation is now handled by the `buildThemes` build task during the incremental build, which pre-compiles all theme CSS files. The resulting CSS files (including `library.css`, `library-RTL.css`, `library-parameters.json`, and CSS Variables resources) are served via the `serveResources` middleware, providing the same functionality with better performance through build-time compilation and caching.
+
+Custom middleware previously referencing `serveThemes` via `beforeMiddleware` or `afterMiddleware` will continue to work with automatic remapping and a deprecation warning. See the [v5 migration guide](../updates/migrate-v5.md) for details.
+:::
+
 All available standard middleware are listed below in the order of their execution.
 
 A project can also add custom middleware to the server by using the [Custom Server Middleware Extensibility](./extensibility/CustomServerMiddleware.md).
@@ -37,7 +43,6 @@ A project can also add custom middleware to the server by using the [Custom Serv
 | `discovery` |  See chapter [discovery](#discovery) |
 | `serveResources` | See chapter [serveResources](#serveresources) |
 | `testRunner` | See chapter [testRunner](#testrunner) |
-| `serveThemes` | See chapter [serveThemes](#servethemes)  |
 | `versionInfo` | See chapter [versionInfo](#versioninfo)  |
 | `nonReadRequests` | See chapter [nonReadRequests](#nonreadrequests)  |
 | `serveIndex` | See chapter [serveIndex](#serveindex)  |
@@ -73,11 +78,6 @@ The following file content transformations are executed:
 ### testRunner
 Serves a static version of the UI5 QUnit TestRunner at `/test-resources/sap/ui/qunit/testrunner.html`.
 
-### serveThemes
-Compiles CSS files for themes on-the-fly from the source `*.less` files.
-
-Changes made to these `*.less` files while the server is running will automatically lead to the re-compilation of the relevant CSS files when requested again.
-
 ### versionInfo
 Generates and serves the version info file `/resources/sap-ui-version.json`, which is required for several framework functionalities.
 

internal/documentation/docs/updates/migrate-v5.md

@@ -198,6 +198,27 @@ Delete the custom `test/Test.qunit.html` file from your test directory. This fil
 Depending on your project setup, you might need to update additional paths in configuration files or test runners to reflect the new structure.
 The test suite is now served under the standard `/test-resources/` path with the component's full namespace (e.g. `/test-resources/sap/ui/demo/todo/testsuite.qunit.html`).
 
+## Removal of Standard Server Middleware
+
+The following middleware has been removed from the [standard middlewares list](../pages/Server.md#standard-middleware):
+
+* `serveThemes` — Theme compilation (LESS to CSS) is now handled by the `buildThemes` build task during the incremental build, rather than on-demand during runtime. The resulting CSS files are served via the `serveResources` middleware. This change improves performance through build-time compilation and caching while maintaining the same functionality.
+
+**Backward Compatibility:**
+If your project or any custom middleware references a removed middleware via `beforeMiddleware` or `afterMiddleware`, UI5 CLI will automatically remap the reference to the nearest remaining middleware and log a deprecation warning. Your custom middleware will still be executed in the expected order.
+
+**What Changed:**
+- Theme CSS files (`library.css`, `library-RTL.css`, etc.) are now **pre-built** during the incremental build
+- Files are served via `serveResources` instead of being compiled on-demand
+- The same CSS files are available at the same URLs as before
+
+**Recommended Action:**
+Update your `ui5.yaml` configuration to reference an existing middleware instead.
+
+| Removed Middleware | Replacement Behavior | Recommended `afterMiddleware` |
+| ------------------ | -------------------- | ----------------------------- |
+| `serveThemes`      | CSS files pre-built by `buildThemes` task and served via `serveResources` | `testRunner` |
+
 ## Learn More
 
 - [Project: Type `component`](../pages/Project#component)

packages/server/lib/middleware/MiddlewareManager.js

@@ -2,6 +2,16 @@ import middlewareRepository from "./middlewareRepository.js";
 import MiddlewareUtil from "./MiddlewareUtil.js";
 import {getLogger} from "@ui5/logger";
 const hasOwn = Function.prototype.call.bind(Object.prototype.hasOwnProperty);
+const log = getLogger("server:MiddlewareManager");
+
+/**
+ * Mapping of removed standard middleware names to their predecessor and successor
+ * in the original execution order. Used to remap custom middleware references
+ * to the nearest remaining middleware when a removed middleware is referenced.
+ */
+const LEGACY_MIDDLEWARE_MAPPING = {
+	serveThemes: {before: "testRunner", after: "versionInfo"}
+};
 
 /**
  * @private
@@ -25,7 +35,7 @@ class MiddlewareManager {
 		sendSAPTargetCSP: false,
 		serveCSPReports: false
 	}}) {
-		if (!graph || !rootProject || !sources || !resources || !resources.all ||
+		if (!graph || !rootProject || !resources || !resources.all ||
 			!resources.rootProject || !resources.dependencies) {
 			throw new Error("[MiddlewareManager]: One or more mandatory parameters not provided");
 		}
@@ -96,7 +106,8 @@ class MiddlewareManager {
 		}
 
 		if (beforeMiddleware || afterMiddleware) {
-			const refMiddlewareName = beforeMiddleware || afterMiddleware;
+			let refMiddlewareName = beforeMiddleware || afterMiddleware;
+			const originalRefMiddlewareName = refMiddlewareName; // Store original before any remapping
 			let refMiddlewareIdx = this.middlewareExecutionOrder.indexOf(refMiddlewareName);
 
 			if (refMiddlewareName === "connectUi5Proxy") {
@@ -106,9 +117,34 @@ class MiddlewareManager {
 					`has been removed in this version of UI5 CLI and can't be referenced anymore. ` +
 					`Please see the migration guide at https://ui5.github.io/cli/updates/migrate-v3/`);
 			}
+
+			// Handle legacy middleware with graceful fallback
+			const legacyMapping = LEGACY_MIDDLEWARE_MAPPING[refMiddlewareName];
+			if (legacyMapping) {
+				// Replace with the appropriate fallback based on reference type
+				refMiddlewareName = afterMiddleware ? legacyMapping.before : legacyMapping.after;
+
+				log.warn(
+					`Standard middleware "${originalRefMiddlewareName}" has been removed. ` +
+					`Custom middleware "${middlewareName}" defined in project ` +
+					`"${this.middlewareUtil.getProject()}" references it and ` +
+					`is now placed ${afterMiddleware ? "after" : "before"} ` +
+					`"${refMiddlewareName}" instead. ` +
+					`For details, see the migration guide at ` +
+					`https://ui5.github.io/cli/next/updates/migrate-v5`);
+			}
+
+			refMiddlewareIdx = this.middlewareExecutionOrder.indexOf(refMiddlewareName);
+
 			if (refMiddlewareIdx === -1) {
-				throw new Error(`Could not find middleware ${refMiddlewareName}, referenced by custom ` +
-					`middleware ${middlewareName}`);
+				// Provide clear error message, including remapping context if applicable
+				const errorMsg = legacyMapping ?
+					`Could not find fallback middleware "${refMiddlewareName}" ` +
+					`(mapped from removed middleware "${originalRefMiddlewareName}"), ` +
+					`referenced by custom middleware "${middlewareName}"` :
+					`Could not find middleware ${refMiddlewareName}, referenced by custom ` +
+					`middleware ${middlewareName}`;
+				throw new Error(errorMsg);
 			}
 			if (afterMiddleware) {
 				// Insert after index of referenced middleware
@@ -220,8 +256,6 @@ class MiddlewareManager {
 		});
 		await this.addMiddleware("serveResources");
 		await this.addMiddleware("testRunner");
-		// TODO: Allow to still reference 'serveThemes' middleware in custom middleware
-		// await this.addMiddleware("serveThemes");
 		await this.addMiddleware("versionInfo", {
 			mountPath: "/resources/sap-ui-version.json"
 		});

packages/server/lib/middleware/middlewareRepository.js

@@ -6,7 +6,6 @@ const middlewareInfos = {
 	serveIndex: {path: "./serveIndex.js"},
 	discovery: {path: "./discovery.js"},
 	versionInfo: {path: "./versionInfo.js"},
-	serveThemes: {path: "./serveThemes.js"},
 	testRunner: {path: "./testRunner.js"},
 	nonReadRequests: {path: "./nonReadRequests.js"}
 };