{"id":17989,"library":"ui5-middleware-simpleproxy","title":"UI5 Simple Proxy Middleware","description":"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.","status":"active","version":"3.7.0","language":"javascript","source_language":"en","source_url":"https://github.com/ui5-community/ui5-ecosystem-showcase","tags":["javascript"],"install":[{"cmd":"npm install ui5-middleware-simpleproxy","lang":"bash","label":"npm"},{"cmd":"yarn add ui5-middleware-simpleproxy","lang":"bash","label":"yarn"},{"cmd":"pnpm add ui5-middleware-simpleproxy","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is a middleware for the UI5 Tooling. It requires `@ui5/cli` to be installed and available in the project's development environment to function correctly, specifically version `^3.0.0` for middleware major version 3.x.","package":"@ui5/cli","optional":false}],"imports":[{"note":"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.","wrong":"import { ui5MiddlewareSimpleproxy } from 'ui5-middleware-simpleproxy';","symbol":"ui5-middleware-simpleproxy","correct":"server:\n  customMiddleware:\n  - name: ui5-middleware-simpleproxy"},{"note":"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.","wrong":"configuration:\n        uri: \"https://services.odata.org\"","symbol":"baseUri","correct":"configuration:\n        baseUri: \"https://services.odata.org\""},{"note":"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.","wrong":"configuration:\n        ignoreSSL: true","symbol":"strictSSL","correct":"configuration:\n        strictSSL: false"}],"quickstart":{"code":"// Step 1: Install the middleware as a development dependency.\n// npm install ui5-middleware-simpleproxy --save-dev\n\n// Step 2: Configure the middleware in your UI5 project's `ui5.yaml` file.\n// This is an example of the YAML configuration required, shown here commented out\n// as it is not direct JavaScript code but rather a configuration file entry.\n\n/*\n# ui5.yaml content:\nserver:\n  customMiddleware:\n  - name: ui5-middleware-simpleproxy\n    # The middleware will process requests that start with this path\n    mountPath: /odata\n    # Specify to run this middleware after the 'compression' middleware\n    afterMiddleware: compression\n    configuration:\n      # The target URI to proxy requests to\n      baseUri: \"https://services.odata.org\"\n      # Optional: Username for Basic Authentication\n      username: \"myUsername\"\n      # Optional: Password for Basic Authentication\n      password: \"myPassword\"\n      # Optional: Custom HTTP headers to be sent with the proxied request\n      httpHeaders:\n        Any-Header: AnyHeaderValue\n      # Optional: Query parameters to be appended to the proxied request\n      query:\n        sap-client: '206'\n      # Optional: Array of glob patterns for paths to exclude from proxying\n      excludePatterns:\n      - \"/local/**\"\n      # Optional: Enable WebSocket proxying (experimental, defaults to false)\n      enableWebSocket: false\n      # Optional: Set to 'false' to ignore strict SSL checks (default is true)\n      strictSSL: false\n*/\n\n// Note: Configuration values in ui5.yaml can be overridden by environment variables.\n// Example using process.env (for demonstration, actual usage would be shell variables):\n// process.env.UI5_MIDDLEWARE_SIMPLE_PROXY_BASEURI = 'https://some.other.backend.com/sap';\n// process.env.UI5_MIDDLEWARE_SIMPLE_PROXY_STRICT_SSL = 'false';\n\n// After configuration, run your UI5 application with `ui5 serve` to activate the proxy.","lang":"javascript","description":"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."},"warnings":[{"fix":"Update your `@ui5/cli` dependency to `^3.0.0` or higher: `npm install @ui5/cli@^3.0.0 --save-dev`.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"To bypass SSL certificate validation for development purposes, set `strictSSL: false` in your `ui5.yaml` configuration under the middleware's `configuration` block.","message":"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`.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"In your `ui5.yaml` configuration, set `strictSSL: false` under the middleware's `configuration` block to disable certificate validation.","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).","error":"Error: unable to verify the first certificate"},{"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).","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).","error":"Custom middleware 'ui5-middleware-simpleproxy' not found"},{"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\"`.","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.","error":"Missing mandatory configuration parameter 'baseUri'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}