UI5 Middleware Approuter

3.9.0 verified Sat Apr 25 auth: no javascript

Middleware for ui5-server that enables local development against SAP Cloud Foundry or XS Advanced destinations via the @sap/approuter. Version 3.9.0 requires @ui5/cli@3.0.0+ (specVersion 3.0). Community-maintained under the ui5-ecosystem-showcase organization. Provides local proxy to backend services defined in xs-app.json, with support for BTP services, authentication, content rewriting, and custom extensions. Alternatives include direct http-proxy-middleware usage, but this package integrates seamlessly with the UI5 tooling lifecycle.

Common errors

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

cause ui5.yaml missing or incorrectly configured middleware section

fix

Add server.customMiddleware configuration with approuter settings

error Error: UI5 CLI version mismatch - expected specVersion 3.0 ↓

cause Using UI5 CLI v2 with package v3

fix

Install @ui5/cli@3 and update specVersion in ui5.yaml to '3.0'

error Error: Could not find xs-app.json at path ./xs-app.json ↓

cause xs-app.json file missing or wrong path

fix

Create xs-app.json in project root or set xsappJson option in ui5.yaml

Warnings

breaking Version 3.x requires UI5 CLI v3 with specVersion 3.0 ↓

fix Update @ui5/cli to 3.0.0+ and set specVersion: '3.0' in ui5.yaml

gotcha Destinations defined in .env file must be a single JSON string; not parsed automatically as multiple env vars ↓

fix Use xsapp_dest = '[{"name":"...","url":"..."}]'

gotcha Regular expression in xs-app.json must match pattern like '^/backend/(.*)$' - leading ^ and trailing $ required ↓

fix Use '^/backend/(.*)$' instead of '/backend/'

gotcha Extension modules with more than 3 arguments are not called for regular extensions; only for approuter extensions ↓

fix Ensure extension handler has exactly 3 parameters (req, res, next) unless using parameters map

Install

npm install ui5-middleware-approuter

yarn add ui5-middleware-approuter

pnpm add ui5-middleware-approuter

Imports

default
wrong
```
export default function()
```
correct
```
module.exports = function() { ... }
```
UI5 middleware uses CommonJS module.exports; ESM exports are not supported by ui5-server.

N/A

wrong

Adding as a devDependency only and not configuring ui5.yaml.

correct

Add to ui5.yaml under middleware section with name 'approuter'

The package is a ui5-server middleware extension; no JS import needed. Configuration is via ui5.yaml file.

Quickstart

Install middleware, configure ui5.yaml with a destination proxy, create minimal xs-app.json, and start ui5 server.

npm install ui5-middleware-approuter --save-dev
mkdir -p myapp/webapp
cat > myapp/ui5.yaml <<EOF
specVersion: "3.0"
metadata:
  name: myapp
type: application
resources:
  configuration:
    paths:
      webapp: webapp
server:
  customMiddleware:
    - name: approuter
      afterMiddleware: compression
      configuration:
        port: 5000
        xsappJson: "./xs-app.json"
        destinations:
          - name: backend
            url: "https://my-backend.example.com"
EOF
cat > myapp/xs-app.json <<EOF
{
  "routes": [{
    "source": "^/backend/(.*)$",
    "target": "$1",
    "destination": "backend"
  }]
}
EOF
cd myapp && npx ui5 serve