UI5 Middleware: Serve Local Framework

3.8.0 verified Thu Apr 23 auth: no javascript

This UI5 middleware, `ui5-middleware-serveframework`, integrates with the UI5 tooling to provide a local serving mechanism for the OpenUI5 or SAPUI5 framework. It automatically builds and caches the specified UI5 framework version (as defined in the project's `ui5.yaml`) into a local directory (`~/.ui5/ui5-middleware-serveframework` by default). Subsequent requests for the same UI5 version are then served directly from this local cache, significantly improving development server startup times and ensuring consistent, offline-capable environments by leveraging preload files and direct static file access. The current stable version, 3.7.1 (as of the last search results), indicates a healthy, community-driven project with regular updates. Its key differentiator is the ability to use a fully local, pre-built UI5 framework, offering benefits over relying on remote CDN sources or repeated on-the-fly compilation.

Common errors

error Error: ui5-middleware-serveframework: Could not find @ui5/cli version 3.x in project dependencies. ↓

cause The project is using an older version of `@ui5/cli` (e.g., v2) while `ui5-middleware-serveframework` v3+ requires `@ui5/cli` v3+.

fix

Update your @ui5/cli dependency to ^3.0.0 or higher in package.json and ensure ui5.yaml's specVersion is set to "3.0".

error ERR_CERT_AUTHORITY_INVALID (or similar SSL certificate errors during framework build) ↓

cause The middleware is trying to download UI5 resources from a CDN over HTTPS but fails due to strict SSL checks against a self-signed or untrusted corporate proxy certificate.

fix

Add strictSSL: false to the ui5-middleware-serveframework configuration in your ui5.yaml file to bypass SSL certificate validation for development purposes.

error UI5 server starts, but UI5 resources (e.g., `sap/m/library.js`) are not found or return 404. ↓

cause The middleware is not correctly configured in `ui5.yaml` or a compatible UI5 framework version cannot be built/found for the project.

fix

Verify that ui5-middleware-serveframework is correctly listed under server.customMiddleware in ui5.yaml with afterMiddleware: compression. Ensure the framework section in ui5.yaml correctly specifies name and version (e.g., OpenUI5 and a valid version like 1.120.0), and that @ui5/builder and @ui5/project are present in devDependencies.

Warnings

breaking All releases of `ui5-middleware-serveframework` with major version `3` require `@ui5/cli@3.0.0` or higher to function correctly. Using incompatible versions will lead to runtime errors during development server startup or framework building. ↓

fix Ensure your project's `package.json` lists `@ui5/cli` with a version range compatible with `^3.0.0`. Also, verify that your `ui5.yaml` `specVersion` is set to `"3.0"`.

gotcha By default, the middleware caches built UI5 framework libraries in the user's home directory (`~/.ui5/ui5-middleware-serveframework`). While this saves disk space by sharing caches across projects, it can lead to longer initial build times for each new UI5 version encountered. ↓

fix To isolate cached libraries per project (useful for CI/CD or dedicated project environments), set `saveLibsLocal: true` in the middleware's configuration in `ui5.yaml`. You can also specify a custom `cachePath` if needed.

gotcha Incorrect `afterMiddleware` placement in your `ui5.yaml` can disrupt the middleware's functionality or interact negatively with other server components. The documentation recommends placing it after the `compression` middleware. ↓

fix Always configure `afterMiddleware: compression` for `ui5-middleware-serveframework` in your `ui5.yaml` to ensure proper integration with the UI5 development server's middleware chain.

gotcha If operating behind a corporate proxy with self-signed SSL certificates, the framework's build process might fail due to strict SSL checks when attempting to download UI5 resources. The `strictSSL` option defaults to `true`. ↓

fix Set `strictSSL: false` in the middleware's configuration within `ui5.yaml` to disable strict SSL validation. Exercise caution as this can reduce security in certain network environments.

gotcha There have been reported issues where `ui5-middleware-serveframework` can interfere with `ui5-test-runner`, causing tests to fail or run prematurely. ↓

fix Check for updates to `ui5-test-runner` as this issue might be resolved in newer versions (e.g., `ui5-test-runner` version 5.3.7 was mentioned as fixing a related issue). If the problem persists, consider temporarily disabling `ui5-middleware-serveframework` or isolating testing environments.

Install

npm install ui5-middleware-serveframework

yarn add ui5-middleware-serveframework

pnpm add ui5-middleware-serveframework

Imports

Package Installation

wrong

npm install ui5-middleware-serveframework (missing --save-dev for a typical development-only middleware)

correct

npm install ui5-middleware-serveframework --save-dev

This middleware is typically installed as a development dependency for UI5 projects.

`package.json` devDependency entry

wrong

Missing the dependency, or an incorrect version range causing compatibility issues.

correct

"devDependencies": {
    "ui5-middleware-serveframework": "^3.0.0"
}

Ensure the middleware is listed in `devDependencies` with a compatible version range.

`ui5.yaml` Custom Middleware configuration
wrong
```
Typo in the `name`, incorrect `afterMiddleware` placement, or misconfigured `configuration` options.
```
correct
```
server:
  customMiddleware:
    - name: ui5-middleware-serveframework
      afterMiddleware: compression
      configuration:
        debug: true
```
The middleware is activated and configured declaratively within the project's `ui5.yaml` file, typically after the `compression` middleware. This package does not expose JavaScript/TypeScript symbols for direct programmatic import in application code.

Quickstart

This quickstart outlines the essential `package.json` and `ui5.yaml` configurations required to integrate and utilize `ui5-middleware-serveframework`. It demonstrates setting up development dependencies and defines a `start` script to launch the UI5 development server, leveraging the middleware to serve a locally built UI5 framework version (e.g., OpenUI5 1.120.0).

// package.json (excerpt)
{
  "name": "my-ui5-app",
  "version": "1.0.0",
  "private": true,
  "description": "A minimal UI5 app using ui5-middleware-serveframework",
  "devDependencies": {
    "@ui5/cli": "^3.0.0",
    "@ui5/builder": "^3.0.0",
    "@ui5/project": "^3.0.0",
    "ui5-middleware-serveframework": "^3.0.0"
  },
  "scripts": {
    "start": "ui5 serve --config ui5.yaml"
  }
}

// ui5.yaml (create this file in your project root)
# For documentation see: https://sap.github.io/ui5-tooling/pages/Configuration/
specVersion: "3.0"
metadata:
  name: my.ui5.app
type: application
framework:
  name: OpenUI5
  version: "1.120.0" # Specify your desired UI5 version here
  libraries:
    - name: sap.m
    - name: sap.ui.core
server:
  customMiddleware:
    - name: ui5-middleware-serveframework
      afterMiddleware: compression
      configuration:
        debug: true
        saveLibsLocal: true
        # ui5VersionEnvVariable: UI5_VERSION # Uncomment to override version via env var
        # strictSSL: false # Uncomment to disable strict SSL checks if behind a proxy