Skip to content

Server.md

Latest commit

 

History

History
244 lines (159 loc) · 14.6 KB

Server.md

File metadata and controls

244 lines (159 loc) · 14.6 KB
Raw

UI5 Server

The UI5 Server module provides server capabilities for local development of UI5 projects.

<script setup> import VPButton from "vitepress/dist/client/theme-default/components/VPButton.vue" </script>

::: tip Browse the API reference for each Server API by navigating in the sidebar menu to API -> @ui5/server. :::

::: warning Development Use Only The UI5 Server is intended for local development purposes only. It must not be exposed to untrusted parties or used as a public-facing web server.

The server does not implement safeguards against various network-based attacks — this is by design, as it is not meant to serve production traffic.

Please be aware of the following risks when using the server:

  • Custom middleware from third parties can execute arbitrary code on your system and may introduce additional security vulnerabilities when the server is exposed to a network.
  • Proxy middleware configured with credentials may enable unauthorized access to the target system for other parties on the same network.
  • Using --accept-remote-connections makes the server reachable from all hosts on your network, which significantly increases the attack surface.

:::

Live Status Banner

When started in an interactive terminal, ui5 serve renders a live status banner that shows the server URLs, the root project's name/type/version, the configured UI5 framework, and a single status line that reflects what the server is doing:

  • ready — the server is idle. Once source files change, a N projects stale count appears here until the next request rebuilds them.
  • building — a build cycle is running; the project counter, current project, and current task update in place.
  • validating cache / settling — the server is checking dependency caches or waiting for a burst of file changes to settle before rebuilding.
  • error — the last build failed. The error message is logged above the banner.

The status line stays pinned at the bottom of the terminal; log messages scroll above it and remain in your terminal scrollback. Log lines duplicating what the banner already shows are suppressed. The banner repaints in place as more information becomes known (project graph resolved, server bound), so early frames may show dim placeholders for sections that have not been populated yet.

The banner is automatically disabled and ui5 serve falls back to plain log output when:

  • stderr is not a TTY (e.g. output is piped to a file or another process).
  • The log level is set to --silent or --silly.

Plain Output (Non-TTY)

When the banner is disabled, ui5 serve prints the following to stdout once the server is ready:

Server started
URL: <url>

The remote-connections warning (when --accept-remote-connections is used) is written to stderr. Tools and scripts that capture the URL by parsing ui5 serve output should run the command in a non-TTY context (for example, with stderr redirected, or in CI), or set UI5_CLI_NO_INTERACTIVE=1 to force plain output in an interactive terminal.

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, which pre-compiles all theme CSS files. The resulting CSS files (including library.css, library-RTL.css, library-parameters.json) are served via the serveResources middleware, providing the same functionality with better performance through build-time compilation and caching.

The testRunner middleware has also been removed in UI5 CLI v5. The QUnit TestRunner (testrunner.html, testrunner.css, TestRunner.js) is now provided by the UI5 framework (sap.ui.core) and is served via the serveResources middleware.

Custom middleware previously referencing serveThemes or testRunner via beforeMiddleware or afterMiddleware will continue to work with automatic remapping and a deprecation warning. See the v5 migration guide 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.

Middleware Description
csp See chapter csp
compression Standard Express compression middleware
cors Standard Express cors middleware
liveReloadClient See chapter liveReload
discovery See chapter discovery
versionInfo See chapter versionInfo
serveResources See chapter serveResources
nonReadRequests See chapter nonReadRequests
serveIndex See chapter serveIndex

csp

The Content Security Policy (CSP) middleware is active by default.

The header content-security-policy can be set by adding URL parameter sap-ui-xx-csp-policy to the request with the policy name as value.

To set the policy to report-only, append :report-only or :ro to the policy name. E.g. /index.html?sap-ui-xx-csp-policy=sap-target-level-1:report-only

sendSAPTargetCSP parameter

The default CSP policies can be modified using parameter sendSAPTargetCSP (--sap-csp-policies when using the CLI). With sendSAPTargetCSP set to true the policies sap-target-level-1 and sap-target-level-3 policies are activated and send as report-only.

Serve CSP Reports

Serving of CSP reports can be activated with parameter serveCSPReports (--serve-csp-reports when using the CLI). With serveCSPReports set to true, the CSP reports are collected and can be downloaded from the server path /.ui5/csp/csp-reports.json.

discovery

This middleware lists project files with URLs under several /discovery endpoints. This is exclusively used by the OpenUI5 test suite application.

liveReload

Live reload automatically refreshes the browser whenever you change a source file in your project — no manual reload needed. This shortens the edit/test cycle during development.

Usage

Live reload is enabled by default with ui5 serve. Open your app in the browser, edit a source file, save — the page reloads.

To control it:

  • CLI flag: ui5 serve --live-reload / --no-live-reload
  • Project configuration (specVersion 5.0+): server.settings.liveReload in ui5.yaml. See Configuration.

When the dev server is restarted, the browser automatically reconnects and reloads once the server is back. Saving multiple files at once triggers a single reload, not one per file.

Technical Details

The following describes how the middleware works internally. This is relevant for advanced users and custom middleware developers — not required for regular usage.

When live reload is active, the UI5 server opens a WebSocket connection that notifies the browser of source changes and triggers a page reload.

Reloads are driven by the BuildServer, which emits a debounced sourcesChanged event whenever watched source files change. A burst of changes therefore results in a single reload notification.

The liveReloadClient middleware serves the client script at /.ui5/liveReload/client.js. The script tag is automatically injected into HTML responses by the serveResources middleware.

To prevent intermediate proxies from idle-closing the WebSocket, the client sends a keepalive message every 30 seconds while the connection is open. The server echoes the same message back.

When the WebSocket connection is lost (e.g. because the server was restarted), the client polls the WebSocket endpoint every second and reloads the page once the server accepts connections again. While the browser tab is hidden, polling pauses until it becomes visible again.

versionInfo

Generates and serves the version info file /resources/sap-ui-version.json, which is required for several framework functionalities.

serveResources

This middleware resolves requests using the ui5-fs-file system abstraction.

The following file content transformations are executed:

  • Escaping non-ASCII characters in .properties translation files based on a project's configuration
  • Enhancing the manifest.json with supported locales determined by available .properties translation files

nonReadRequests

Answers all non-read requests (POST, PUT, DELETE, etc.) that have not been answered by any other middleware with the 404 "Not Found" status code . This signals the client that these operations are not supported by the server.

serveIndex

In case a directory has been requested, this middleware renders an HTML with a list of the directory's content.

Standard Tasks

As with the UI5 Builder, a set of standard tasks is being executed during a server build. Individual tasks can be included or excluded using the respective CLI options --include-task and --exclude-task.

::: info Exception For the server, the generateVersionInfo task is not executed, because the corresponding versionInfo middleware creates an identical sap-ui-version.json output file. :::

::: info See Builder Standard Tasks for more explanation about each task. :::

Build Cache Control

The UI5 Server performs a build of the projects by utilizing build caches.

You can control the build cache behavior using the --cache option:

  • --cache Default (default): Use the cache if available, create it if missing
  • --cache Force: Only use the cache; fail if the cache is unavailable or invalid
  • --cache ReadOnly: Use existing cache but don't update it (useful for CI/CD)
  • --cache Off: Disable caching entirely and always perform a full rebuild

Example:

ui5 serve --cache Off

In this scenario, when a source file changes and a request comes in, the server always performs a full rebuild, even if this source version existed previously.

::: info By default, build caches created by ui5 build and ui5 serve are separate and cannot be mixed. Each command executes a distinct set of tasks, resulting in separate caches tailored to its specific use case. For more details on builder caching, see the UI5 Builder documentation. :::

Watch Mode Behavior

Once started with ui5 serve, the server monitors your project sources throughout the session. When a request arrives, it checks for cached results first and only rebuilds the affected resources and tasks if no cache is available. Saving multiple files at once triggers a single rebuild, not one per file.

  • Monitored: All files in your project's source directories (src/, webapp/, test/, etc.)
  • Not monitored: Custom task and middleware implementation code

Project Definition Changes

The server also watches the project definition files: ui5.yaml, package.json, the workspace configuration, and any file passed via --config or --dependency-definition. When one of these changes, the server re-resolves the project graph and re-creates itself behind the same URL and port. Connected browsers stay connected and reload once the server is ready.

This covers configuration changes (for example adding a framework library or changing the project type) as well as switching branches with git checkout. While the graph is being re-resolved, requests are held with a page that reloads automatically once the server is ready.

::: info Changes to custom task or middleware implementation code still require a server restart to take effect. :::

Integrating into an Existing Node.js Server

Beyond starting its own HTTP server via serve, @ui5/server exposes a serveMiddleware API for integrating UI5 Server functionality into an existing Express or Connect application. This is the supported entry point for tools that embed a UI5 Server — for example test runners or framework plugins — instead of running ui5 serve as a standalone process.

serveMiddleware(graph[, options][, error]) takes a project graph and resolves with:

  • middleware — a single Connect/Express-compatible request handler; mount it on your own app with app.use(middleware).
  • close() — an async teardown function that releases the BuildServer's source watcher and build-cache handle. Call it when shutting down.

Unlike serve, serveMiddleware does not bind a port, attach the live reload WebSocket server, or install the terminal HTML error handler — those remain the responsibility of the HTTP server you own. Error handling and the listener are yours to provide.

import express from "express";
import {graphFromPackageDependencies} from "@ui5/project/graph";
import {serveMiddleware} from "@ui5/server";

const graph = await graphFromPackageDependencies({cwd: process.cwd()});
const {middleware, close} = await serveMiddleware(graph);

const app = express();
app.use(middleware);
const listener = app.listen(8080);

// On teardown, stop the listener and release the BuildServer's watcher and cache handle:
listener.close();
await close();

Connect works the same way — connect().use(middleware).

options accepts the serving-related subset of serve's options. See the API Reference for the full signature.

::: warning Serve a graph only once A project graph can be served only once. Do not call both serveMiddleware and serve for the same graph. :::

SSL Certificates

When starting the UI5 Server in HTTPS- or HTTP/2 mode, for example by using UI5 CLI parameter --h2, you will be prompted for the automatic generation of a local SSL certificate if necessary.

Follow the given instructions and enter your password to install the generated certificate as trusted. You can find the generated certificate and corresponding private key under .ui5/server in your user's home directory.

::: tip If Chrome unintentionally redirects an HTTP-URL to HTTPS, you need to delete the HSTS mapping in chrome://net-internals/#hsts by entering the domain name (e.g. localhost) and pressing "delete".

:::

<style> .no-decoration { text-decoration: inherit; } </style>