UI5 Simple Proxy Middleware

3.7.0 verified Thu Apr 23 auth: no javascript

ui5-middleware-simpleproxy is a middleware for the UI5 Tooling ecosystem, specifically designed to integrate with `@ui5/server`. It provides a simple HTTP and WebSocket proxying capability for UI5 applications during development. Currently at stable version 3.7.0, it follows the UI5 CLI's major versioning for compatibility, requiring `@ui5/cli@3.0.0` or higher for its 3.x releases. The package allows developers to configure a base URI, handle SSL certificates, manage HTTP headers and query parameters, and define exclusion patterns directly within their `ui5.yaml` file. A key differentiator is its straightforward configuration via YAML and environment variables, providing a flexible solution for connecting local UI5 development servers to backend services, including support for basic authentication and optional ETag removal. It's a fundamental tool for managing backend communication in UI5 local development setups.

Common errors

error Error: unable to verify the first certificate ↓

cause The proxy is attempting to connect to an HTTPS `baseUri` that uses a self-signed or otherwise untrusted SSL certificate, and `strictSSL` is enabled (default behavior).

fix

In your ui5.yaml configuration, set strictSSL: false under the middleware's configuration block to disable certificate validation.

error Custom middleware 'ui5-middleware-simpleproxy' not found ↓

cause The `ui5-middleware-simpleproxy` package is either not installed in your project's `devDependencies`, or your `@ui5/cli` version is incompatible (e.g., using middleware v3 with `@ui5/cli` v2).

fix

Run npm install ui5-middleware-simpleproxy --save-dev and verify that your @ui5/cli version meets the minimum requirement (e.g., ^3.0.0 for middleware v3).

error Missing mandatory configuration parameter 'baseUri' ↓

cause The `baseUri` property is a mandatory configuration option and was not provided in the `ui5.yaml` configuration for the middleware, nor via an environment variable.

fix

Add the baseUri property to the configuration section of ui5-middleware-simpleproxy in your ui5.yaml with the target backend URL: configuration:\n baseUri: "https://your.backend.service".

Warnings

breaking Major version 3 of `ui5-middleware-simpleproxy` requires `@ui5/cli` version 3.0.0 or higher. Using it with older versions of `@ui5/cli` will lead to compatibility issues or prevent the middleware from loading. ↓

fix Update your `@ui5/cli` dependency to `^3.0.0` or higher: `npm install @ui5/cli@^3.0.0 --save-dev`.

gotcha The `strictSSL` configuration option defaults to `true`. If your `baseUri` points to an HTTPS service with a self-signed or untrusted SSL certificate, you will encounter `Error: unable to verify the first certificate`. ↓

fix To bypass SSL certificate validation for development purposes, set `strictSSL: false` in your `ui5.yaml` configuration under the middleware's `configuration` block.

gotcha Configuration parameters defined in `ui5.yaml` can be overridden by corresponding environment variables (e.g., `UI5_MIDDLEWARE_SIMPLE_PROXY_BASEURI` for `baseUri`) or values parsed from a `.env` file in the project root. ↓

fix If your `ui5.yaml` settings are not taking effect, check your shell's environment variables and any `.env` files for conflicting `UI5_MIDDLEWARE_SIMPLE_PROXY_...` variables.

gotcha The `mountPath` configured for the middleware (e.g., `/odata`) is separate from the `baseUri`. The `baseUri` should always be the complete, absolute URL of the backend service and is used as-is, without considering the `mountPath`. ↓

fix Ensure `baseUri` specifies the full target URL (e.g., `https://services.odata.org`), even if `mountPath` is `/odata`. The proxy handles the path mapping internally.

Install

npm install ui5-middleware-simpleproxy

yarn add ui5-middleware-simpleproxy

pnpm add ui5-middleware-simpleproxy

Imports

ui5-middleware-simpleproxy
wrong
```
import { ui5MiddlewareSimpleproxy } from 'ui5-middleware-simpleproxy';
```
correct
```
server:
  customMiddleware:
  - name: ui5-middleware-simpleproxy
```
This package is a UI5 Tooling middleware and does not expose JavaScript exports for direct `import` or `require`. It is 'integrated' into your UI5 project by configuring its name under `server.customMiddleware` in your `ui5.yaml` file.
baseUri
wrong
```
configuration:
        uri: "https://services.odata.org"
```
correct
```
configuration:
        baseUri: "https://services.odata.org"
```
The primary configuration option for specifying the target backend service URL is `baseUri`. Ensure it is correctly spelled within the `configuration` block. It can also be overridden by the `UI5_MIDDLEWARE_SIMPLE_PROXY_BASEURI` environment variable.
strictSSL
wrong
```
configuration:
        ignoreSSL: true
```
correct
```
configuration:
        strictSSL: false
```
The `strictSSL` option controls whether the proxy validates SSL certificates of the target `baseUri`. Set to `false` to ignore self-signed or untrusted certificates. The default value is `true`. This can also be overridden by `UI5_MIDDLEWARE_SIMPLE_PROXY_STRICT_SSL` environment variable.

Quickstart

This quickstart illustrates the installation process and the typical `ui5.yaml` configuration for `ui5-middleware-simpleproxy`, demonstrating how to set up proxying to a backend service with authentication, custom headers, query parameters, and SSL handling.

// Step 1: Install the middleware as a development dependency.
// npm install ui5-middleware-simpleproxy --save-dev

// Step 2: Configure the middleware in your UI5 project's `ui5.yaml` file.
// This is an example of the YAML configuration required, shown here commented out
// as it is not direct JavaScript code but rather a configuration file entry.

/*
# ui5.yaml content:
server:
  customMiddleware:
  - name: ui5-middleware-simpleproxy
    # The middleware will process requests that start with this path
    mountPath: /odata
    # Specify to run this middleware after the 'compression' middleware
    afterMiddleware: compression
    configuration:
      # The target URI to proxy requests to
      baseUri: "https://services.odata.org"
      # Optional: Username for Basic Authentication
      username: "myUsername"
      # Optional: Password for Basic Authentication
      password: "myPassword"
      # Optional: Custom HTTP headers to be sent with the proxied request
      httpHeaders:
        Any-Header: AnyHeaderValue
      # Optional: Query parameters to be appended to the proxied request
      query:
        sap-client: '206'
      # Optional: Array of glob patterns for paths to exclude from proxying
      excludePatterns:
      - "/local/**"
      # Optional: Enable WebSocket proxying (experimental, defaults to false)
      enableWebSocket: false
      # Optional: Set to 'false' to ignore strict SSL checks (default is true)
      strictSSL: false
*/

// Note: Configuration values in ui5.yaml can be overridden by environment variables.
// Example using process.env (for demonstration, actual usage would be shell variables):
// process.env.UI5_MIDDLEWARE_SIMPLE_PROXY_BASEURI = 'https://some.other.backend.com/sap';
// process.env.UI5_MIDDLEWARE_SIMPLE_PROXY_STRICT_SSL = 'false';

// After configuration, run your UI5 application with `ui5 serve` to activate the proxy.