ui5-middleware-route-proxy

1.0.10 verified Sat Apr 25 auth: no javascript

A middleware for the SAP UI5 tooling's ui5-server that enables route-based proxying of HTTP requests to backend servers. Version 1.0.10 is the current stable release, with automated publishes via GitHub Actions. It supports flexible configuration via ui5.yaml, including authentication (basic auth or custom Authorization header), path replacement, and changeOrigin option from http-proxy. It integrates with .env files for secrets, and is commonly used in UI5 development to proxy OData or other backend services. Compared to alternatives like ui5-middleware-simpleproxy, it offers per-route configuration and auth header customization.

Common errors

error Error: Cannot find module 'ui5-middleware-route-proxy' ↓

cause Package not installed or not listed in ui5.dependencies in package.json.

fix

Run 'npm install --save-dev ui5-middleware-route-proxy' and add the package to 'ui5.dependencies' array in package.json.

error ENOENT: no such file or directory, open '.env' ↓

cause Missing .env file in project root, or dotenv not installed.

fix

Create a .env file in the project root, or install dotenv: 'npm install dotenv'.

error Invalid configuration: middleware 'ui5-middleware-route-proxy' has unknown property 'afterMiddleware' ↓

cause The 'afterMiddleware' property is placed incorrectly in the configuration object.

fix

Ensure 'afterMiddleware' is at the same level as 'name' and 'configuration', not inside 'configuration'.

error TypeError: Cannot read property 'target' of undefined ↓

cause Misconfigured route object; likely a missing route key or incorrect indentation in YAML.

fix

Check ui5.yaml: each route must be a key under 'configuration' with a 'target' property. Ensure proper YAML indentation.

Warnings

gotcha Package must be listed in both devDependencies and ui5.dependencies in package.json, otherwise UI5 tooling will not load it. ↓

fix Add the package to 'ui5.dependencies' array in package.json, and also include it in 'devDependencies'.

gotcha The 'afterMiddleware' property must be set correctly to avoid middleware execution order issues. Typically 'compression' is used, but if compression middleware is not present, the server may fail. ↓

fix Ensure 'compression' middleware is enabled in your UI5 project, or adjust 'afterMiddleware' to an existing middleware like 'serveIndex'.

gotcha If the auth object contains a 'header' property, 'user' and 'pass' are ignored. Misconfiguration leads to unexpected authentication behavior. ↓

fix Either use 'header' or 'user'/'pass', not both in the same path configuration. If using 'header', ensure it's a valid Authorization header value.

gotcha The route key (e.g., '/sap') must include a leading slash. Omitting it will cause the route to not match. ↓

fix Always start the route key with '/' (e.g., '/sap', '/odata').

gotcha When using .env variables, the variable name must be exactly as in .env file. Any mismatch results in the literal string being used. ↓

fix Double-check .env variable names and ensure they match the values in ui5.yaml. Enclose in quotes if necessary.

deprecated The 'replacePath' option when set to true removes the route prefix from the forwarded path. This behavior may change in future versions. ↓

fix Explicitly set 'replacePath' to a string path if you need custom replacement, or set to true for current behavior.

Install

npm install ui5-middleware-route-proxy

yarn add ui5-middleware-route-proxy

pnpm add ui5-middleware-route-proxy

Imports

ui5-middleware-route-proxy
wrong
```
const proxy = require('ui5-middleware-route-proxy'); // not used directly in code
```
correct
```
No JavaScript import; configured in ui5.yaml under server.customMiddleware
```
The package is used as a UI5 tooling middleware, not imported in application code. It is listed in package.json under ui5.dependencies and configured in ui5.yaml.

Quickstart

Shows minimal configuration to proxy /sap requests to a backend with authentication and path replacement.

// .env file
PROXY_TARGET=https://mybackend.example.com
PROXY_USERNAME=myuser
PROXY_PASSWORD=mypassword

// ui5.yaml
server:
  customMiddleware:
  - name: ui5-middleware-route-proxy
    afterMiddleware: compression
    configuration:
      debug: true
      /sap:
        target: PROXY_TARGET
        auth:
          user: PROXY_USERNAME
          pass: PROXY_PASSWORD
        replacePath: true
        changeOrigin: true

// package.json (devDependencies)
{
  "devDependencies": {
    "ui5-middleware-route-proxy": "*"
  },
  "ui5": {
    "dependencies": [
      "ui5-middleware-route-proxy"
    ]
  }
}

// Install dependencies
npm install --save-dev ui5-middleware-route-proxy dotenv

// Start UI5 server
ui5 serve --config ui5.yaml