From 4ad72939bcf2238f345744c3d938c00ba5f2fee8 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 30 Aug 2026 09:07:12 +0000 Subject: [PATCH 1/2] Document the production build, and correct the /resources story MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The deployment page said `npm run build` and stopped there. What that actually has to run is `npm ci` + `npm run build:production` — `cds build --production` plus `scripts/vendor-core.js` — because the CDS build stages gen/srv with the app's `"abap2UI5": "file:./core"` dependency and does not stage the folder it names. Without the second half the archive builds, `cf deploy` succeeds, and the instance crash-loops on `Cannot find module 'abap2UI5/engine'`; that was the state of the shipped app until cap2UI5/builder-cap2UI5 fixed it. Readers vendoring a `file:` dependency in their own CAP project hit the same thing, so the section also names the CAP-supported alternative (npm workspaces + `cds build --ws-pack`). Also records that openui5-dist is not deployed — on BTP `/resources` comes from the `ui5` destination — and adds abap2UI5-db-deployer to the mta.yaml module list, which the page had omitted. Troubleshooting claimed the server "fails at startup with an explicit message" when openui5-dist is missing. It does not: srv/cap/activate.js warns once and carries on, so the symptom is a blank page and a log line, not a failed boot. Corrected, with the actual message and a separate entry for the BTP case, where a /resources 404 means the destination is wrong rather than a missing dependency. verify-refs --require-checkout passes against a cap2UI5 checkout; site builds. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01R2ofjmLGtR9pKxi3m2KvMq --- docs/guide/troubleshooting.md | 11 +++++++++-- docs/reference/deployment.md | 25 +++++++++++++++++++++++++ 2 files changed, 34 insertions(+), 2 deletions(-) diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.md index 2b678c8..db668e3 100644 --- a/docs/guide/troubleshooting.md +++ b/docs/guide/troubleshooting.md @@ -47,8 +47,15 @@ The bootstrap HTML arrived but UI5 never started. - **Open the browser console first** — a CSP violation or a 404 on `/resources/sap-ui-core.js` shows there immediately. - **`/resources` 404s.** The local UI5 runtime comes from the `openui5-dist` - dependency. Run `npm ci`. The server now fails at startup with an explicit - message when it cannot resolve it. + dependency. Run `npm ci`. Its absence is not fatal — the server logs + `[z2ui5] openui5-dist not resolvable — /resources not served; bootstrap + from a CDN instead` once at startup and keeps going, so check the server + log for that line before hunting elsewhere. +- **`/resources` 404s on BTP.** Different cause: there the runtime is not + served by the CAP module at all. The approuter routes `/resources` to the + `ui5` destination (`https://ui5.sap.com`) and the production build leaves + `openui5-dist` out of the pushed module, so a 404 means the destination is + missing or misconfigured, not a missing dependency. - **The app uses commercial SAPUI5 controls.** `openui5-dist` ships only the open-source libraries. Anything under `sap.suite.*`, `sap.gantt`, `sap.ui.comp` needs the SAPUI5 CDN — point `s_config.src` at it in your diff --git a/docs/reference/deployment.md b/docs/reference/deployment.md index 2d2ea9d..cb7b14c 100644 --- a/docs/reference/deployment.md +++ b/docs/reference/deployment.md @@ -31,6 +31,7 @@ The reference project contains an `mta.yaml` with all standard modules: ```yaml modules: - name: abap2UI5-srv # CAP service +- name: abap2UI5-db-deployer # HDI container (the draft table) - name: abap2UI5 # HTML5 module with the frontend - name: abap2UI5-app-deployer # HTML5 repo push - name: abap2UI5-destinations # FLP destinations @@ -48,6 +49,30 @@ npm run build # → mbt build, produces mta_archives/archive.mtar npm run deploy # → cf deploy mta_archives/archive.mtar ``` +### What the production build has to do + +`mbt build` runs the project's `before-all`, which is `npm ci` followed by +`npm run build:production` — **not** a bare `cds build --production`. The CDS +build stages the server module into `gen/srv` and copies the app's dependency +on the vendored framework (`"abap2UI5": "file:./core"`) along with it, but not +the folder that specifier points at. `scripts/vendor-core.js` is the second +half: it puts the vendored core into `gen/srv/core`, so the pushed module can +resolve `abap2UI5/engine`. Skip it and the archive still builds, `cf deploy` +still succeeds, and the instance crash-loops on +`Cannot find module 'abap2UI5/engine'`. + +The same step drops `openui5-dist` from what is pushed. It is the UI5 runtime +`cds watch` serves at `/resources` locally; on BTP the approuter routes +`/resources` to the `ui5` destination, so the CAP module never serves it — +and the package is a deprecated 611 MB tree of release tooling. The staged +module is 19 MB without it. + +If you build your own CAP project around the core package rather than +deploying this one, the same rule applies to any `file:` dependency you vendor: +`cds build` will not stage it for you. The alternative CAP supports is npm +workspaces plus `cds build --ws-pack`, which packs the workspace dependency +into a tarball and rewrites the specifier. + Prerequisites: - **Multi-Target Build Tool**: `npm i -g mbt` From 34fdda1703d7bd909e7142ab9e557d29a4ad6cf2 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 30 Aug 2026 09:30:45 +0000 Subject: [PATCH 2/2] Record that the UI5 runtime is an optional peer dependency MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Follows builder-abap2UI5-js@815593e. openui5-dist is no longer a dependency of the framework package, so a project using the core installs it itself if it wants the local /resources runtime — the docs said nothing about that and would have left readers with a 404 they could not explain. Deployment gains the numbers behind the decision (611 MB, 43 advisories, 3 critical, none of it code the app loads) and states that the staged module leaves it out via `npm ci --omit=dev` rather than only via the vendor step's prune. Troubleshooting names the install to run when a project never declared it. verify-refs --require-checkout passes against a cap2UI5 checkout; site builds. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01R2ofjmLGtR9pKxi3m2KvMq --- docs/guide/troubleshooting.md | 7 +++++-- docs/reference/deployment.md | 13 ++++++++----- 2 files changed, 13 insertions(+), 7 deletions(-) diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.md index db668e3..a7883ed 100644 --- a/docs/guide/troubleshooting.md +++ b/docs/guide/troubleshooting.md @@ -46,8 +46,11 @@ The bootstrap HTML arrived but UI5 never started. - **Open the browser console first** — a CSP violation or a 404 on `/resources/sap-ui-core.js` shows there immediately. -- **`/resources` 404s.** The local UI5 runtime comes from the `openui5-dist` - dependency. Run `npm ci`. Its absence is not fatal — the server logs +- **`/resources` 404s.** The local UI5 runtime comes from `openui5-dist`, + which the framework declares as an *optional peer* dependency — in your own + project you install it yourself (cap2UI5 carries it as a devDependency). Run + `npm ci`, or `npm i -D openui5-dist@1.113.0` if your project never declared + it. Its absence is not fatal — the server logs `[z2ui5] openui5-dist not resolvable — /resources not served; bootstrap from a CDN instead` once at startup and keeps going, so check the server log for that line before hunting elsewhere. diff --git a/docs/reference/deployment.md b/docs/reference/deployment.md index cb7b14c..18c3833 100644 --- a/docs/reference/deployment.md +++ b/docs/reference/deployment.md @@ -61,11 +61,14 @@ resolve `abap2UI5/engine`. Skip it and the archive still builds, `cf deploy` still succeeds, and the instance crash-loops on `Cannot find module 'abap2UI5/engine'`. -The same step drops `openui5-dist` from what is pushed. It is the UI5 runtime -`cds watch` serves at `/resources` locally; on BTP the approuter routes -`/resources` to the `ui5` destination, so the CAP module never serves it — -and the package is a deprecated 611 MB tree of release tooling. The staged -module is 19 MB without it. +`openui5-dist` is not pushed either. It is the UI5 runtime `cds watch` serves +at `/resources` locally; on BTP the approuter routes `/resources` to the `ui5` +destination, so the CAP module never serves it — and the package is a +deprecated 611 MB tree of release tooling that carried 43 advisories, 3 of +them critical. The framework declares it as an *optional peer* dependency and +cap2UI5 carries it as a devDependency, so `npm ci --omit=dev` in the staged +module leaves it out: 19 MB, no advisories. (The vendor step also prunes it +defensively, for a framework version that still declares it.) If you build your own CAP project around the core package rather than deploying this one, the same rule applies to any `file:` dependency you vendor: