UI5 Express Utilities

Common errors

• Error: Cannot find module 'ui5-utils-express'

  cause The package `ui5-utils-express` has not been installed or is not correctly linked in your project's `node_modules`.
  fix Run `npm install ui5-utils-express` or `yarn add ui5-utils-express` to install the package.

• TypeError: ui5ExpressUtils.someFunction is not a function

  cause You are attempting to call a function from `ui5-utils-express` that either does not exist, or you are importing it incorrectly (e.g., trying to access a named export as a property of a default import, or vice-versa).
  fix Consult the `ui5-utils-express` documentation or source code to verify the available exports and their correct import syntax (named vs. default export). Adjust your `import` or `require` statement accordingly.

• Access to XMLHttpRequest at 'http://localhost:XXXX/...' from origin 'http://localhost:YYYY' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

  cause Your UI5 application is running on one origin (e.g., `http://localhost:YYYY`) and trying to fetch resources or data from a different origin (e.g., `http://localhost:XXXX`) served by your Express server or a proxied backend, but the server is not sending the necessary `Access-Control-Allow-Origin` header.
  fix Configure your Express server to include appropriate CORS headers using middleware like `cors`, or use a proxy setup to ensure all requests appear to originate from the same domain as your UI5 app. Example: `app.use(cors());`

Warnings

• gotcha When using ui5-utils-express in conjunction with the UI5 CLI development server, be aware that the UI5 server itself is intended for development purposes only and should not be exposed to untrusted parties or used in production environments. It lacks safeguards against various network-based attacks.
  Fix: Ensure that any Express server leveraging ui5-utils-express is not deployed to production without robust security measures appropriate for a public-facing server. Consider using a dedicated application router for production deployments.
• gotcha Custom middleware or utilities, including those from ui5-utils-express, can execute arbitrary code on your system. Integrating third-party components without proper vetting may introduce security vulnerabilities, especially when the server is exposed to a network.
  Fix: Thoroughly review the source code and dependencies of any custom utilities or middleware before integration. Limit network exposure of development servers.
• breaking While ui5-utils-express itself does not specify UI5 CLI version dependencies, other packages within the ui5-ecosystem-showcase (which it is part of) state that latest releases of UI5 CLI extensions require `@ui5/cli@3.0.0` or higher for `specVersion: '3.0'`. Mismatched UI5 CLI versions can lead to unexpected behavior or build failures.
  Fix: Always align your project's `@ui5/cli` version with the recommendations for the `ui5-ecosystem-showcase` components you are using. Update Node.js to a supported LTS version.
• gotcha CORS issues are common when serving UI5 applications with a custom Express server, especially when proxying backend services or loading resources from different origins during local development.
  Fix: Implement appropriate CORS headers in your Express server or use proxy middleware (e.g., `http-proxy-middleware`) to handle cross-origin requests. Tools like the `approuter` can also simplify CORS handling for UI5 apps connecting to Cloud Foundry or XS Advanced destinations.

Install

• npm install ui5-utils-express npm
• yarn add ui5-utils-express yarn
• pnpm add ui5-utils-express pnpm

Imports

• createUI5Router
  wrong:

  const createUI5Router = require('ui5-utils-express').createUI5Router;

  correct:

  import { createUI5Router } from 'ui5-utils-express';

  Assumed named export for a common utility pattern.
• resolveUI5ResourcePath
  wrong:

  const { resolveUI5ResourcePath } = require('ui5-utils-express');

  correct:

  import { resolveUI5ResourcePath } from 'ui5-utils-express';

  Assumed named export for path resolution utilities.
• default
  wrong:

  import { ui5ExpressUtils } from 'ui5-utils-express';

  correct:

  import ui5ExpressUtils from 'ui5-utils-express';

  If the package exports a default object containing all utilities, this would be the import.

Quickstart

Sets up a basic Express server to serve a UI5 application's static files and demonstrates how UI5 resources might be handled or proxied, simulating a common use case for UI5-specific Express utilities.

import express from 'express';
import path from 'path';
// In a real scenario, ui5-utils-express would provide specific helpers.
// For demonstration, we'll simulate a common UI5 serving pattern.
// A typical utility might help configure static serving or proxying for UI5 resources.

const app = express();
const PORT = process.env.PORT || 8080;

// Imagine ui5ExpressUtils helps determine the correct path for UI5 framework resources
// or application resources based on UI5 tooling configuration.
// For this example, we'll serve a hypothetical 'webapp' folder and UI5 CDN.

// Serve application static files
const appRoot = path.join(__dirname, 'webapp');
app.use('/', express.static(appRoot));
console.log(`Serving UI5 application from: ${appRoot}`);

// Example: If ui5-utils-express provided a way to proxy UI5 CDN resources
// This is a placeholder; a real utility would handle UI5 versioning and caching.
app.use('/resources', (req, res, next) => {
  const ui5Version = process.env.UI5_VERSION || '1.120.0'; // Example UI5 version
  const cdnUrl = `https://ui5.sap.com/${ui5Version}/resources${req.url}`;
  console.log(`Proxying UI5 resource: ${cdnUrl}`);
  // In a real scenario, use a proxy middleware like http-proxy-middleware
  // For simplicity, we just log and pass to next. You'd replace this with actual proxy logic.
  // For a basic setup, you might just serve directly from CDN or local cache.
  res.redirect(cdnUrl);
});

app.listen(PORT, () => {
  console.log(`UI5 Express server running on http://localhost:${PORT}`);
  console.log('Access your UI5 application at /index.html');
});