{"id":18882,"library":"ui5-middleware-approuter","title":"UI5 Middleware Approuter","description":"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.","status":"active","version":"3.9.0","language":"javascript","source_language":"en","source_url":"https://github.com/ui5-community/ui5-ecosystem-showcase","tags":["javascript"],"install":[{"cmd":"npm install ui5-middleware-approuter","lang":"bash","label":"npm"},{"cmd":"yarn add ui5-middleware-approuter","lang":"bash","label":"yarn"},{"cmd":"pnpm add ui5-middleware-approuter","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core proxy runtime from SAP","package":"@sap/approuter","optional":false},{"reason":"Handles actual HTTP proxying","package":"http-proxy-middleware","optional":false},{"reason":"UI5 server extension interface","package":"@ui5/server","optional":false}],"imports":[{"note":"UI5 middleware uses CommonJS module.exports; ESM exports are not supported by ui5-server.","wrong":"export default function()","symbol":"default","correct":"module.exports = function() { ... }"},{"note":"The package is a ui5-server middleware extension; no JS import needed. Configuration is via ui5.yaml file.","wrong":"Adding as a devDependency only and not configuring ui5.yaml.","symbol":"N/A","correct":"Add to ui5.yaml under middleware section with name 'approuter'"}],"quickstart":{"code":"npm install ui5-middleware-approuter --save-dev\nmkdir -p myapp/webapp\ncat > myapp/ui5.yaml <<EOF\nspecVersion: \"3.0\"\nmetadata:\n  name: myapp\ntype: application\nresources:\n  configuration:\n    paths:\n      webapp: webapp\nserver:\n  customMiddleware:\n    - name: approuter\n      afterMiddleware: compression\n      configuration:\n        port: 5000\n        xsappJson: \"./xs-app.json\"\n        destinations:\n          - name: backend\n            url: \"https://my-backend.example.com\"\nEOF\ncat > myapp/xs-app.json <<EOF\n{\n  \"routes\": [{\n    \"source\": \"^/backend/(.*)$\",\n    \"target\": \"$1\",\n    \"destination\": \"backend\"\n  }]\n}\nEOF\ncd myapp && npx ui5 serve","lang":"bash","description":"Install middleware, configure ui5.yaml with a destination proxy, create minimal xs-app.json, and start ui5 server."},"warnings":[{"fix":"Update @ui5/cli to 3.0.0+ and set specVersion: '3.0' in ui5.yaml","message":"Version 3.x requires UI5 CLI v3 with specVersion 3.0","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Use xsapp_dest = '[{\"name\":\"...\",\"url\":\"...\"}]'","message":"Destinations defined in .env file must be a single JSON string; not parsed automatically as multiple env vars","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use '^/backend/(.*)$' instead of '/backend/'","message":"Regular expression in xs-app.json must match pattern like '^/backend/(.*)$' - leading ^ and trailing $ required","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Ensure extension handler has exactly 3 parameters (req, res, next) unless using parameters map","message":"Extension modules with more than 3 arguments are not called for regular extensions; only for approuter extensions","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Add server.customMiddleware configuration with approuter settings","cause":"ui5.yaml missing or incorrectly configured middleware section","error":"TypeError: Cannot read property 'destinations' of undefined"},{"fix":"Install @ui5/cli@3 and update specVersion in ui5.yaml to '3.0'","cause":"Using UI5 CLI v2 with package v3","error":"Error: UI5 CLI version mismatch - expected specVersion 3.0"},{"fix":"Create xs-app.json in project root or set xsappJson option in ui5.yaml","cause":"xs-app.json file missing or wrong path","error":"Error: Could not find xs-app.json at path ./xs-app.json"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}