dev-approuter 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# 0.1.0 (2023-08-25)
+
+
+### Features
+
+* **dev-approuter:** initial commit ([#801](https://github.com/ui5-community/ui5-ecosystem-showcase/issues/801)) ([324890f](https://github.com/ui5-community/ui5-ecosystem-showcase/commit/324890f9916e6a3379685e353007c1ee6e73ca4c))

package/LICENSE

@@ -0,0 +1,253 @@
+/*
+ * ----------------------------------------------------------------------------
+ * "THE DERIVED BEER-WARE LICENSE" (Revision 1):
+ * You can do whatever you want with this stuff. When you like it, just buy
+ * Volker Buzek (@vobu) a beer or buy Peter Muessig (@pmuessig) a coke when
+ * you see one of them.
+ *
+ * Inspired by the official: https://fedoraproject.org/wiki/Licensing/Beerware
+ *
+ * "THE BEER-WARE LICENSE" (Revision 42):
+ * <phk@FreeBSD.ORG> wrote this file. As long as you retain this notice you
+ * can do whatever you want with this stuff. If we meet some day, and you think
+ * this stuff is worth it, you can buy me a beer in return Poul-Henning Kamp
+ * ----------------------------------------------------------------------------
+ */
+
+---
+
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+------------------------------------------------------------------------------
+APIs
+
+This project may include APIs to SAP or third party products or services. The use of these APIs, products and services may be subject to additional agreements. In no event shall the application of the Apache Software License, v.2 to this project grant any rights in or to these APIs, products or services that would alter, expand, be inconsistent with, or supersede any terms of these additional agreements. “API” means application programming interfaces, as well as their respective specifications and implementing code that allows other software products to communicate with or call on SAP or third party products or services (for example, SAP Enterprise Services, BAPIs, Idocs, RFCs and ABAP calls or other user exits) and may be made available through SAP or third party products, SDKs, documentation or other media.
+
+------------------------------------------------------------------------------
+SUBCOMPONENTS
+
+This project includes the following subcomponents that are subject to separate license terms.
+Your use of these subcomponents is subject to the separate license terms applicable to
+each subcomponent.
+
+Component: deploy.sh
+Licensor: Domenic Denicola
+Website: https://gist.github.com/domenic/ec8b0fc8ab45f39403dd/e445116166c79d7ac35eb38a5d348d546f3d1620
+License: MIT License
+<year> = 2018
+<copyright holders> = Domenic Denicola
+
+------------------------------------------------------------------------------
+
+The MIT License (MIT)
+
+Copyright <YEAR> <COPYRIGHT HOLDER>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+------------------------------------------------------------------------------

package/README.md

@@ -0,0 +1,179 @@
+# dev-approuter
+
+> :wave: This is a **community project** and there is no official support for this package! Feel free to use it, open issues, contribute, and help answering questions.
+
+The `dev-approuter` is a dev time wrapper for the [SAP Application Router](https://www.npmjs.com/package/@sap/approuter) that can serve [UI5](https://ui5.sap.com/) and [SAP CAP](https://cap.cloud.sap/docs/) apps that are added as (dev)dependencies to the approuter's `package.json`. A few key notes to begin with:
+- The `dev-approuter` utilizes the [SAP Application Router's extension API](https://help.sap.com/docs/btp/sap-business-technology-platform/extension-api-of-application-router) by adding UI5 servers as extensions - providing the full [UI5 Tooling](https://sap.github.io/ui5-tooling/v3/) experience.
+- A linked SAP CAP app is started on a different port - this is to mimic a deployed architecture. The corresponding destination is automatically created for you.
+- In order to safely separate development configuration from productive code, the `dev-approuter` introduces the concept of the `xs-dev.json` - think of it as an extension to the [`xs-app.json`](https://help.sap.com/docs/btp/sap-business-technology-platform/routing-configuration-file).
+- As the name suggests, the `dev-approuter` is for development only and not meant to be used in production.
+
+---
+
+1. [Prerequisites](#prerequisites)
+2. [Starting the `dev-approuter`](#starting-the-dev-approuter)
+3. [Adding and serving apps](#adding-and-serving-apps)
+    - [UI5 apps](#ui5-apps)
+    - [SAP CAP apps](#sap-cap-apps)
+4. [The `xs-dev.json` file](#the-xs-devjson-file)
+5. [Using the `dev-approuter` and SAP Application Router simultaneously](#using-the-dev-approuter-and-sap-approuter-simultaneously)
+6. [Extending the `dev-approuter`](#extending-the-dev-approuter)
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/en) version 18 or higher.
+
+## Starting the `dev-approuter`
+
+The `dev-approuter` is a wrapper for the SAP Application Router, meaning your current (productive) approuter configuration will also work with the `dev-approuter`, with the option to add dev time configuration to it (see [xs-dev.json](#the-xs-devjson-file)).
+
+1. Install the `dev-approuter` as a dev dependency: 
+    ```bash
+    npm install dev-approuter --save-dev
+    ```
+
+2. Add the following script to the `scripts` section of your approuter's `package.json` file:
+    ```json
+    {
+        ...
+        "scripts": {
+            ...
+            "dev": "node node_modules/dev-approuter"
+        }
+    }
+    ```
+
+3. Start the `dev-approuter`:
+    ```bash
+    npm run dev
+    ```
+
+4. The `dev-approuter` starts on port 5000 by default, just like the SAP Application Router. If that port is already in use on your machine (hello Mac users :wave:), you can set another port via the `default-env.json` file:
+    ```json
+    {
+        "PORT": 5001,
+        ...
+    }
+    ```
+
+## Adding and serving apps
+
+To add a UI5 or SAP CAP app to the `dev-approuter`, add it to the `devDependencies` section of your approuter's `package.json` file:
+
+```json
+{
+    ...
+    "devDependencies": {
+        ...
+        "my-ui5-app": "path/to/ui5-app",
+        "my-cap-app": "path/to/cap-app"
+    }
+}
+```
+
+### UI5 apps
+
+For UI5 apps the `metadata.name` (as defined in the `ui5.yaml`) is used as the mount path by default. This can be overwritten with via a `customConfiguration.mountPath` in the `ui5.yaml`:
+
+```yaml
+specVersion: "3.0"
+metadata:
+  name: ui5-app  # default mount path would be /ui5-app 
+type: application
+customConfiguration:
+  mountPath: /my-custom-mount-path # overwrites the default mount path
+```
+
+The above configuration result in the UI5 app being available at `http://localhost:5000/my-custom-mount-path`.
+
+### SAP CAP apps
+
+SAP CAP apps are started on a separate port (4004 by default, can be overwritten via `CAP_PORT`). The `dev-approuter` automatically creates a route and destination behind the scenes, so that you (and your UI5 apps) can reach your SAP CAP services directly at their service path, but through the `dev-approuter`, e.g. `http://localhost:5000/my-cap-service`.
+
+There is no need manually create a destination for you SAP CAP app, unless you want to overwrite the [default destination configuration](./lib/helpers.js#L81-L85). In this case, create a new destination in a `default-env.json`. The destination's name has to match the module name as declared in the approuter's `devDependencies`:
+
+```json
+{
+    "CAP_PORT": 4005,
+    "destinations": [
+        {
+            "Name": "my-cap-app",
+            "Authentication": "NoAuthentication",
+            "ProxyType": "Internet",
+            "Type": "HTTP",
+            "URL": "http://localhost:4005",
+            "forwardAuthToken": true
+        }
+    ],
+    ...
+}
+```
+
+## The `xs-dev.json` file
+
+The `dev-approuter` introduces the concept of an `xs-dev.json` file, which works like a regular [`xs-app.json`](https://help.sap.com/docs/btp/sap-business-technology-platform/routing-configuration-file) file, but is used by the `dev-approuter` exclusively (meaning it's ignored by the SAP Application Router). The idea behind this concept is to safely separate dev time configuration from productive code.
+
+The `xs-dev.json` follows the same logic and syntax as the [`xs-app.json`](https://help.sap.com/docs/btp/sap-business-technology-platform/routing-configuration-file) file, but has one additional key feature: You can add a `dependency` to a `route`, which links it to a UI5 or SAP CAP app.
+
+Look at the following example `xs-dev.json` that defines different `authenticationType`s for different UI5 apps:
+
+```json
+{
+    "welcomeFile": "index.html",
+    "authenticationMethod": "route",
+    "routes": [
+        {
+            "dependency": "my-ui5-app1",
+            "authenticationType": "none"
+        },
+        {
+            "dependency": "my-ui5-app2",
+            "authenticationType": "xsuaa"
+        }
+    ]
+}
+```
+
+Behind the scenes, the `dev-approuter` will resolve these "dependency routes" by adding the `source`, `target`, and `destination` properties to them. Be aware that exactly these properties might get overwritten by the `dev-approuter` in case you use them together with `dependency`.
+
+## Using the `dev-approuter` and SAP Application Router simultaneously
+
+If you choose to place your `dev-approuter` in the same directory as an SAP Application Router, which you will eventually deploy, you will have to remove the `devDependencies` section of the `package.json` before deployment. This is required because the SAP Application Router will not be able to install local dev dependencies (your UI5 and SAP CAP apps) in the cloud. To achieve this, you could introduce a build step for the approuter, moving required files to a `dist/` folder and removing dev dependencies:
+
+```json
+"build": "mkdir -p dist && jq 'del(.devDependencies)' package.json > dist/package.json && cp xs-app.json dist/xs-app.json"
+```
+
+## Extending the `dev-approuter`
+
+The `dev-approuter` offers an extension point to pass middleware to the SAP Application Router, that gets started by the `dev-approuter` (behind the scenes) and has an extension point of its own (see the [documentation](https://help.sap.com/docs/btp/sap-business-technology-platform/extension-api-of-application-router) for more info). You can use this extension point by passing extensions to the `dev-approuter`'s `start()` method:
+
+```js
+const devApprouter = require("dev-approuter/lib/devApprouter");
+devApprouter.start([
+    {
+        insertMiddleware: {
+            first: [
+                {
+                    path: "/my-ext",
+                    handler: (req, res, next) => {
+                        res.end("Request handled by my extension!")
+                    }
+                }
+            ]
+        }
+    }
+]);
+```
+
+## Support
+
+Please use the GitHub bug tracking system to post questions, bug reports or to create pull requests.
+
+## Contributing
+
+Any type of contribution (code contributions, pull requests, issues) to this set of tooling extensions will be equally appreciated.
+
+## License
+
+This work is [dual-licensed](../../LICENSE) under Apache 2.0 and the Derived Beer-ware License. The official license will be Apache 2.0 but finally you can choose between one of them if you use this work.

package/index.js

@@ -0,0 +1,2 @@
+const devApprouter = require("./lib/devApprouter");
+devApprouter.start();

package/lib/devApprouter.js

@@ -0,0 +1,147 @@
+const approuter = require("@sap/approuter");
+const express = require("express");
+const xsenv = require('@sap/xsenv')
+
+const findUI5Modules = require("cds-plugin-ui5/lib/findUI5Modules");
+const createPatchedRouter = require("cds-plugin-ui5/lib/createPatchedRouter");
+const applyUI5Middleware = require("cds-plugin-ui5/lib/applyUI5Middleware");
+
+const findCAPModules = require("ui5-middleware-cap/lib/findCAPModules");
+const applyCAPMiddleware = require("ui5-middleware-cap/lib/applyCAPMiddleware");
+
+const {
+    parseConfig,
+    applyDependencyConfig,
+    addDestination,
+    configureCAPRoute,
+    configureUI5Route
+} = require("./helpers");
+
+
+class DevApprouter {
+
+    constructor() {}
+
+    /**
+     * Starts the dev approuter.
+     * Extensions passed as argument are handed to the SAP Approuter without modifications.
+     * We suggest to check the documentation (link below) for an extensive read on how the dev approuter works.
+     * Here is a shorter summary:
+     * UI5 modules declared as (dev)dependencies are added as extensions
+     * using the extension API of the SAP Approuter.
+     * CAP modules declared as (dev)dependencies are started on a different port.
+     * Corresponding routes and destinations are automatically created.
+     * A custom `xs-dev.json` can be used to configure the dev approuter,
+     * so the productive configuration can be kept in the `xs-app.json`.
+     * @param {Object[]} [extensions] - an optional array of extensions that are handed to the SAP Approuter without modification.
+     * @param {Object} extensions[].insertMiddleware - an object containing the middlewares.
+     * @param {Object[]} extensions[].insertMiddleware.first - an array of middlewares to be inserted in the `first` slot.
+     * @param {String} extensions[].insertMiddleware.first[].path - a string representing the path to handle requests for.
+     * @param {Function} extensions[].insertMiddleware.first[].handler - a function handling `(req, res, next)`.
+     * @param {Object[]} extensions[].insertMiddleware.beforeRequestHandler - an array of middlewares to be inserted in the `beforeRequestHandler` slot.
+     * @param {String} extensions[].insertMiddleware.beforeRequestHandler[].path - a string representing the path to handle requests for.
+     * @param {Function} extensions[].insertMiddleware.beforeRequestHandler[].handler - a function handling `(req, res, next)`.
+     * @param {Object[]} extensions[].insertMiddleware.beforeErrorHandler - an array of middlewares to be inserted in the `beforeErrorHandler` slot.
+     * @param {String} extensions[].insertMiddleware.beforeErrorHandler[].path - a string representing the path to handle requests for.
+     * @param {Function} extensions[].insertMiddleware.beforeErrorHandler[].handler - a function handling `(req, res, next)`.
+     * @see https://github.com/ui5-community/ui5-ecosystem-showcase/tree/main/packages/dev-approuter
+     */
+    async start(extensions = []) {
+        // loads env from default-env.json
+        xsenv.loadEnv();
+
+        const config = parseConfig();
+        const cwd = process.cwd();
+
+        // lookup the CAP server root
+        let capServerConfig;
+        const capModules = await findCAPModules({ cwd });
+        if (capModules.length > 1) {
+            throw new Error(`Multiple CAP modules found. The package dev-approuter can only handle one CAP module as dependency.`);
+        } else if (capModules.length === 1) {
+            capServerConfig = capModules[0];
+        }
+
+        // find all UI5 modules from the CAP server root and dependencies from the approuter
+        const ui5Modules = [...(await findUI5Modules({ cwd, skipLocalApps: true }))];
+        if (capServerConfig) {
+            ui5Modules.push(...(await findUI5Modules({ cwd: capServerConfig.modulePath, skipDeps: true })))
+        }
+
+        // collect UI5 middlewares
+        const ui5Middlewares = [];
+        for await (const ui5Module of ui5Modules) {
+            const { moduleId, modulePath, mountPath } = ui5Module;
+
+            // create a patched router
+            const router = await createPatchedRouter();
+
+            // apply the UI5 middlewares to the router
+            await applyUI5Middleware(router, {
+                basePath: modulePath,
+                configPath: modulePath,
+            });
+
+            // mounting the router for the UI5 application to the CAP server
+            console.log(`Mounting ${mountPath} to UI5 app ${modulePath}`);
+
+            let middlewareMountPath
+            // define middlewareMountPath as `/_${mountPath}` if ui5 module is referenced as "dependency" in xs-dev.json or xs-app.json
+            if (config.dependencyRoutes && config.dependencyRoutes[moduleId]) {
+                // configure UI5 route
+                config.dependencyRoutes[moduleId] = configureUI5Route(moduleId, mountPath, config.dependencyRoutes[moduleId]);
+
+                middlewareMountPath = "/_" + mountPath;
+
+                // add destination for newly configured route
+                addDestination(moduleId, process.env.PORT, middlewareMountPath);
+            } else {
+                middlewareMountPath = mountPath;
+            }
+
+            // store the router for later registration
+            ui5Middlewares.push({
+                path: middlewareMountPath,
+                handler: router
+            });
+
+        }
+
+        // start CAP server on different port
+        if (capServerConfig) {
+            const { modulePath, moduleId } = capServerConfig;
+
+            // start CAP server on different port
+            const app = express();
+            const { servicesPaths } = await applyCAPMiddleware(app, { root: modulePath, cwd });
+            app.listen(process.env.CAP_PORT || 4004, () => {
+                console.log(`CAP server started at: http://localhost:${process.env.CAP_PORT || 4004}`);
+            });
+
+            // configure CAP route if referenced as "dependency" in xs-dev.json/xs-app.json
+            if (config.dependencyRoutes && config.dependencyRoutes[moduleId]) {
+                config.dependencyRoutes[moduleId] = configureCAPRoute(moduleId, servicesPaths, config.dependencyRoutes[moduleId]);
+            }
+
+            // add destination for newly configured route
+            addDestination(moduleId, process.env.CAP_PORT || 4004);
+        }
+
+        // create and start the SAP Approuter
+        // https://help.sap.com/docs/btp/sap-business-technology-platform/extension-api-of-application-router
+        approuter().start({
+            port: process.env.PORT || 5001,
+            xsappConfig: applyDependencyConfig(config),
+            extensions: [
+                {
+                    insertMiddleware: {
+                        first: ui5Middlewares
+                    }
+                }
+            ].concat(extensions)
+        });
+        console.log(`Approuter started at: http://localhost:${process.env.PORT || 5001}`);
+    };
+}
+
+module.exports = new DevApprouter();

package/lib/helpers.js

@@ -0,0 +1,136 @@
+const path = require("path");
+
+/**
+ * Parses the approuter configuration from an `xs-dev.json` file.
+ * If that file doesn't exist, it looks for an `xs-app.json` file.
+ * Also scans the routes of the config file and checks for the `dependency` property
+ * and stores those in `config.dependencyRoutes`, which is where the dev approuter will do its magic.
+ * @returns {Object} the approuter configuration including all `dependencyRoutes`.
+ */
+const parseConfig = () => {
+    let config;
+    let configFile;
+    let configFiles = ["xs-dev.json", "xs-app.json"];
+    for (const file of configFiles) {
+        if (fs.existsSync(path.join(process.cwd(), file))) {
+            config = JSON.parse(
+                fs.readFileSync(
+                    path.join(process.cwd(), file),
+                    { encoding: "utf8" }
+                )
+            );
+            configFile = file;
+            break;
+        }
+    }
+    config.dependencyRoutes = {};
+    config.routes?.forEach(route => {
+        if (route.dependency) {
+            if (config.dependencyRoutes[`${route.dependency}`]) {
+                throw new Error(`Duplicate dependency "${route.dependency}" found in file ${path.join(process.cwd(), configFile)}.`);
+            } else {
+                config.dependencyRoutes[`${route.dependency}`] = route;
+            }
+        }
+    });
+    return config;
+};
+
+/**
+ * Applies the `config.dependencyRoutes` to the `config.routes` and removes them.
+ * @param {Object} config - the approuter configuration including all `dependencyRoutes`.
+ * @returns {Object} config - the approuter configuration that can be used to start the approuter.
+ */
+const applyDependencyConfig = (config) => {
+    config.routes?.forEach(route => {
+        if (route.dependency) {
+            route = config.dependencyRoutes[route.dependency];
+        }
+    });
+    delete config.dependencyRoutes;
+    return config;
+};
+
+/**
+ * Adds a destination to `process.env.destinations` for a given module.
+ * If a destination with this `name === moduleId` already exists, no new destination will be created.
+ * @param {String} moduleId - the id of the module that a destination is created for.
+ * @param {Number} port - the port of the localhost that the destination should point to.
+ * @param {String} mountPath - the path the module was mounted to and the destination should point to.
+ */
+const addDestination = (moduleId, port, mountPath) => {
+    let destinations = [];
+    if (process.env.destinations) {
+        destinations = JSON.parse(process.env.destinations);
+    }
+
+    let url;
+    if (mountPath) {
+        url = `http://localhost:${process.env.PORT || 5000}${mountPath}`;
+    } else {
+        url = `http://localhost:${port}`;
+    }
+
+    // only add new destination if it's not already provided
+    const destinationAlreadyExists = destinations.some(destination => {
+        const lowerCaseDestination = {};
+        Object.keys(destination).forEach(key => {
+            lowerCaseDestination[key.toLowerCase()] = destination[key];
+        })
+        return lowerCaseDestination.name === moduleId
+    })
+    if (!destinationAlreadyExists) {
+        destinations.push({
+            Name: moduleId,
+            Authentication: "NoAuthentication",
+            ProxyType: "Internet",
+            Type: "HTTP",
+            URL: url
+        });
+        process.env.destinations = JSON.stringify(destinations);
+    }
+};
+
+/**
+ * Configures the route for a given CAP module.
+ * @param {String} moduleId - the id of the module that the route should be configured for.
+ * @param {String[]} servicePaths - an array of service paths that the CAP module serves.
+ * @param {Object} route - the route that is to be configured.
+ * @returns {Object} the configured route.
+ */
+const configureCAPRoute = (moduleId, servicesPaths, route) => {
+    route.source = servicesPaths.map(path => { return `${path}(.*)` }).join("|");
+    route.destination = moduleId;
+    delete route.dependency;
+
+    return route;
+};
+
+/**
+ * Configures the route for a given UI5 module.
+ * @param {String} moduleId - the id of the module that the route should be configured for. 
+ * @param {String} sourcePath - the path the approuter should handle the module at.
+ * @param {Object} route - the route that is to be configured.
+ * @returns {Object} the configured route.
+ */
+const configureUI5Route = (moduleId, sourcePath, route) => {
+    if (sourcePath === "/") {
+        // special regex to avoid endless loop
+        route.source = `^(?!.*(/_${sourcePath}))`;
+    } else {
+        route.source = `^${sourcePath}(.*)$`;
+        route.target = "$1";
+    }
+    route.destination = moduleId;
+    delete route.dependency;
+
+    return route;
+};
+
+module.exports = {
+    parseConfig,
+    applyDependencyConfig,
+    addDestination,
+    configureCAPRoute,
+    configureUI5Route
+};

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "dev-approuter",
+  "version": "0.1.0",
+  "description": "A dev time wrapper for the SAP Application Router that can serve UI5 and CAP modules added as dependencies.",
+  "author": "Nico Schoenteich <nicolai.schoenteich@sap.com> (https://github.com/nicoschoenteich)",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ui5-community/ui5-ecosystem-showcase.git",
+    "directory": "packages/dev-approuter"
+  },
+  "dependencies": {
+    "@sap/approuter": ">=14.3.0",
+    "@sap/xsenv": "4.0.0",
+    "cds-plugin-ui5": "^0.4.0",
+    "express": "^4.18.2",
+    "path": "^0.12.7",
+    "ui5-middleware-cap": "^3.1.0"
+  },
+  "gitHead": "4a6a4401cc13120cb5f91bba8c116dce78c3812b"
+}