cds-plugin-ui5 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -3,6 +3,28 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [0.5.0](https://github.com/ui5-community/ui5-ecosystem-showcase/compare/cds-plugin-ui5@0.4.0...cds-plugin-ui5@0.5.0) (2023-09-02)
+
+
+### Features
+
+* **cds-plugin-ui5:** alternative ui5.yamls / ignore HTML fragments ([#824](https://github.com/ui5-community/ui5-ecosystem-showcase/issues/824)) ([20bfb51](https://github.com/ui5-community/ui5-ecosystem-showcase/commit/20bfb51fc46de05b000e617eaca6a30c2a7aae6a)), closes [#822](https://github.com/ui5-community/ui5-ecosystem-showcase/issues/822) [#823](https://github.com/ui5-community/ui5-ecosystem-showcase/issues/823)
+
+
+
+
+
+# [0.4.0](https://github.com/ui5-community/ui5-ecosystem-showcase/compare/cds-plugin-ui5@0.3.0...cds-plugin-ui5@0.4.0) (2023-08-21)
+
+
+### Features
+
+* **cds-plugin-ui5:** allow to attach custom app pages to cds server ([#800](https://github.com/ui5-community/ui5-ecosystem-showcase/issues/800)) ([0670b5e](https://github.com/ui5-community/ui5-ecosystem-showcase/commit/0670b5e9d01175ecf9d1f0db332963b8c9fec007)), closes [#785](https://github.com/ui5-community/ui5-ecosystem-showcase/issues/785)
+
+
+
+
+
 # [0.3.0](https://github.com/ui5-community/ui5-ecosystem-showcase/compare/cds-plugin-ui5@0.2.3...cds-plugin-ui5@0.3.0) (2023-08-17)
 
 

package/README.md

@@ -21,6 +21,61 @@ npm add cds-plugin-ui5 -D
 
 That's it!
 
+### Configuration
+
+The plugin can be configured using the `cds-plugin-ui5` section in the `package.json`. To define a custom configFile for any module you can add a configuration object for each module in the `modules` section:
+
+```json
+{
+    "cds-plugin-ui5": {
+      "modules": {
+        "ui5-bookshop": {
+          "configFile": "ui5.yaml"
+        },
+        "cds-ui5-bookshopviewer": {
+          "configFile": "ui5-dist.yaml"
+        }
+      }
+    }
+}
+```
+
+The key is the `moduleId` which is either the directory name for local apps in the `app` directory of the CAP server or for dependencies the `name` from the `package.json`. As value you can specify an alternative `configFile` name.
+
+A second option to override this configuration is the usage of the environment variable `CDS_PLUGIN_UI5_MODULES`. It contains the JSON string from the configuration above, e.g.:
+
+```sh
+CDS_PLUGIN_UI5_MODULES="{ \"ui5-bookshop\": { \"configFile\": \"ui5-dist.yaml\" } }" cds-serve
+```
+
+## Info for UI5 Tooling Extension Developers
+
+Custom middlewares may generate virtual app pages which should also be listed as web applications in the welcome page of the `@sap/cds` server. This is possible by assigning a static `getAppPages` function to the middleware function. The following snippet show-cases how this can be done:
+
+```js
+// the middleware factory function
+module.exports = async ({ log, resources, options }) => {
+  // create the middleware function
+  const mwFn = (req, res, next) => {
+    [...]
+  };
+
+  /**
+   * Returns an array of app pages to be added to the welcome
+   * page of the <code>@sap/cds</code> server.
+   * @returns {undefined|string[]} array of app pages
+   */
+  mwFn.getAppPages = function() {
+    return ["/test.html"];
+  };
+
+  // finally return the middleware function
+  return mwFn;
+};
+```
+
+The returned app pages will be added to the welcome page within the respective mount path.
+
 ## Support
 
 Please use the GitHub bug tracking system to post questions, bug reports or to create pull requests.

package/cds-plugin.js

@@ -32,16 +32,16 @@ cds.on("bootstrap", async function bootstrap(app) {
 
 	const cwd = process.cwd();
 	const ui5Modules = await findUI5Modules({ cwd });
-	const localApps = ui5Modules.localApps;
+	const { localApps, configFiles } = ui5Modules;
 
 	const links = [];
 
 	// register the UI5 modules via their own router/middlewares
 	for await (const ui5Module of ui5Modules) {
-		const { mountPath, modulePath } = ui5Module;
+		const { moduleId, mountPath, modulePath } = ui5Module;
 
 		// mounting the Router for the UI5 application to the CAP server
-		log.info(`Mounting ${mountPath} to UI5 app ${modulePath}`);
+		log.info(`Mounting ${mountPath} to UI5 app ${modulePath} (id=${moduleId})${configFiles[moduleId] ? ` using configFile=${configFiles[moduleId]}` : ""}`);
 
 		// create a patched router
 		const router = await createPatchedRouter();
@@ -51,6 +51,7 @@ cds.on("bootstrap", async function bootstrap(app) {
 		const appInfo = await applyUI5Middleware(router, {
 			basePath: modulePath,
 			configPath: modulePath,
+			configFile: configFiles[moduleId],
 		});
 
 		// register the router to the specified mount path
@@ -59,7 +60,7 @@ cds.on("bootstrap", async function bootstrap(app) {
 		// append the HTML pages to the links
 		appInfo.pages.forEach((page) => {
 			const prefix = mountPath !== "/" ? mountPath : "";
-			links.push(`${prefix}${page.getPath()}`);
+			links.push(`${prefix}${page}`);
 		});
 	}
 

package/lib/applyUI5Middleware.js

@@ -1,5 +1,7 @@
 const path = require("path");
 
+const log = require("./log");
+
 /**
  * @typedef UI5AppInfo
  * @type {object}
@@ -14,16 +16,17 @@ const path = require("path");
  * @param {object} options configuration options
  * @param {string} options.basePath base path of the UI5 application
  * @param {string} [options.configPath] path to the ui5.yaml (defaults to "${basePath}/ui5.yaml")
+ * @param {string} [options.configFile] name of the config file (defaults to "ui5.yaml")
  * @returns {UI5AppInfo} UI5 application information object
  */
-module.exports = async function applyUI5Middleware(router, { basePath, configPath }) {
+module.exports = async function applyUI5Middleware(router, { basePath, configPath, configFile = "ui5.yaml" }) {
 	const { graphFromPackageDependencies } = await import("@ui5/project/graph");
 	const { createReaderCollection } = await import("@ui5/fs/resourceFactory");
 
 	const graph = await graphFromPackageDependencies({
 		workspaceName: process.env["ui5-workspace"],
 		cwd: basePath,
-		rootConfigPath: configPath ? path.resolve(configPath, "ui5.yaml") : undefined,
+		rootConfigPath: configPath ? path.resolve(configPath, configFile) : undefined,
 	});
 
 	const rootProject = graph.getRoot();
@@ -69,7 +72,26 @@ module.exports = async function applyUI5Middleware(router, { basePath, configPat
 	});
 	await middlewareManager.applyMiddleware(router);
 
+	// collect app pages from workspace (glob testing: https://globster.xyz/ and https://codepen.io/mrmlnc/pen/OXQjMe)
+	//   -> but exclude the HTML fragments from the list of app pages!
+	const pages = (await rootReader.byGlob("**/!(*.fragment).{html,htm}")).map((resource) => resource.getPath());
+
+	// collect app pages from middlewares implementing the getAppPages
+	middlewareManager.middlewareExecutionOrder?.map((name) => {
+		const { middleware } = middlewareManager.middleware?.[name] || {};
+		if (typeof middleware?.getAppPages === "function") {
+			const customAppPages = middleware.getAppPages();
+			if (Array.isArray(customAppPages)) {
+				pages.push(...customAppPages);
+			} else {
+				if (customAppPages) {
+					log.warn(`The middleware ${name} returns an unexpected value for "getAppPages". The value must be either undefined or string[]! Ignoring app pages from middleware!`);
+				}
+			}
+		}
+	});
+
 	return {
-		pages: await rootReader.byGlob("**/*.html"),
+		pages,
 	};
 };

package/lib/findUI5Modules.js

@@ -59,8 +59,8 @@ module.exports = async function findUI5Modules({ cwd, skipLocalApps, skipDeps })
 	}
 
 	// lookup the UI5 modules in the project dependencies
+	const pkgJson = require(path.join(cwd, "package.json"));
 	if (!skipDeps) {
-		const pkgJson = require(path.join(cwd, "package.json"));
 		const deps = [];
 		deps.push(...Object.keys(pkgJson.dependencies || {}));
 		deps.push(...Object.keys(pkgJson.devDependencies || {}));
@@ -80,9 +80,23 @@ module.exports = async function findUI5Modules({ cwd, skipLocalApps, skipDeps })
 		);
 	}
 
+	// determine module configuration:
+	//   => env variable: CDS_PLUGIN_UI5_MODULES (JSONObject<string, object>)
+	//   => package.json: cds-plugin-ui5 > modules (JSONObject<string, object>)
+	// JSONObject<string, object>: key = moduleId (folder name, npm package name), object={ configFile: string }
+	let modulesConfig;
+	try {
+		modulesConfig = JSON.parse(process.env.CDS_PLUGIN_UI5_MODULES);
+		log.info(`Using modules configuration from env`);
+	} catch (err) {
+		modulesConfig = pkgJson.cds?.["cds-plugin-ui5"]?.modules;
+	}
+	log.debug(JSON.stringify(modulesConfig, undefined, 2));
+
 	// if apps are available, attach the middlewares of the UI5 apps
 	// to the express of the CAP server via a express router
 	const apps = [];
+	apps.configFiles = {};
 	if (appDirs) {
 		for await (const appDir of appDirs) {
 			// read the ui5.yaml file to extract the configuration
@@ -95,7 +109,7 @@ module.exports = async function findUI5Modules({ cwd, skipLocalApps, skipDeps })
 				ui5Configs = yaml.loadAll(content);
 			} catch (err) {
 				if (err.name === "YAMLException") {
-					log("error", `Failed to read ${ui5YamlPath}!`);
+					log.error(`Failed to read ${ui5YamlPath}!`);
 				}
 				throw err;
 			}
@@ -124,12 +138,19 @@ module.exports = async function findUI5Modules({ cwd, skipLocalApps, skipDeps })
 					const packageJsonContent = fs.readFileSync(packageJsonPath, "utf-8");
 					moduleName = JSON.parse(packageJsonContent).name;
 				}
-				const moduleId = moduleName || appDir;
+				const moduleId = moduleName || path.basename(appDir);
+
+				// store the custom config file
+				if (modulesConfig?.[moduleId]?.configFile) {
+					apps.configFiles[moduleId] = modulesConfig?.[moduleId]?.configFile;
+				}
 
 				apps.push({ moduleId, modulePath, mountPath });
 			}
 		}
 	}
 	apps.localApps = localApps; // necessary for CAP index.html rewrite
+
+	// return the apps
 	return apps;
 };

package/lib/log.js

@@ -16,7 +16,7 @@ function log(type, ...message) {
 		type = "log";
 	}
 	const args = [`\x1b[36m[cds-ui5-plugin]\x1b[0m %s[%s]\x1b[0m %s`, colors[type], type];
-	args.push(message);
+	message && args.push(...message);
 	console[type].apply(console[type], args);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cds-plugin-ui5",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "A CAP server cds-plugin to inject the middlewares of all related UI5 tooling based projects.",
   "author": "Peter Muessig",
   "license": "Apache-2.0",
@@ -24,5 +24,5 @@
     "@sap/cds": ">=6.8.2",
     "express": ">=4.18.2"
   },
-  "gitHead": "67e4ae6ca95c267dbc4472a916b84dd1c3f0ad0b"
+  "gitHead": "9db24d0cd23d691749cd1419f24ec7f6cf7c1f5b"
 }