|
| 1 | +# Migrate to v5 |
| 2 | + |
| 3 | +::: tip Alpha Release Available |
| 4 | +**UI5 CLI 5.0 Alpha is now available for testing! 🎉** |
| 5 | + |
| 6 | +Try the alpha release in your projects via: `npm i --save-dev @ui5/cli@next` |
| 7 | +Or update your global install via: `npm i --global @ui5/cli@next` |
| 8 | + |
| 9 | +**Note:** This is a pre-release version. |
| 10 | +::: |
| 11 | + |
| 12 | +## Breaking Changes |
| 13 | + |
| 14 | +- **All UI5 CLI Modules require Node.js ^22.20.0 || >=24.0.0** |
| 15 | + |
| 16 | +- **@ui5/cli: `ui5 init` defaults to Specification Version 5.0** |
| 17 | + |
| 18 | + |
| 19 | +## Node.js and npm Version Support |
| 20 | + |
| 21 | +This release requires **Node.js version v22.20.0 and higher or v24.0.0 and higher (v23 is not supported)** as well as npm v8 or higher. |
| 22 | +Support for older Node.js releases has been dropped; their use will cause an error. |
| 23 | + |
| 24 | +## Specification Versions Support |
| 25 | + |
| 26 | +UI5 CLI 5.x introduces **Specification Version 5.0**, which enables the new Component Type and brings improved project structure conventions. |
| 27 | + |
| 28 | +Projects using older **Specification Versions** are expected to be **fully compatible with UI5 CLI v5**. |
| 29 | + |
| 30 | +## UI5 CLI Init Command |
| 31 | + |
| 32 | +The `ui5 init` command now generates projects with Specification Version 5.0 by default. |
| 33 | + |
| 34 | +## Component Type |
| 35 | + |
| 36 | +The `component` type feature aims to introduce a new project type within the UI5 CLI ecosystem to support the development of UI5 component-like applications intended to run in container apps such as the Fiori Launchpad (FLP) Sandbox or testsuite environments. |
| 37 | + |
| 38 | +This feature will allow developers to serve and build multiple UI5 application components concurrently, enhancing the local development environment for integration scenarios. |
| 39 | + |
| 40 | +**Note:** A component type project must contain both a `Component.js` and a `manifest.json` file in the source directory. |
| 41 | + |
| 42 | +More details about the Component Type can be found in the [Project: Type `component`](../pages/Project#component) documentation. |
| 43 | + |
| 44 | +### Migrating from Application to Component Type |
| 45 | + |
| 46 | +If you have an existing application that you'd like to migrate to the Component Type, there are several steps to follow. |
| 47 | +The migration involves updating your project configuration and restructuring your project directories to align with the Component Type conventions. |
| 48 | + |
| 49 | +**Main changes**: |
| 50 | +1. Source directories `src` and `test` instead of `webapp` and `webapp/test` |
| 51 | +1. Files are served under `/resources/<namespace>/` and `/test-resources/<namespace>/` paths (instead of `/` and `/test/`) |
| 52 | + - This affects (relative)-paths in HTML files, test suite configuration, and test runner setups |
| 53 | + |
| 54 | +#### 1. Update `ui5.yaml` Configuration |
| 55 | + |
| 56 | +Update your `ui5.yaml` file to use the Component Type and Specification Version 5.0: |
| 57 | + |
| 58 | +```diff |
| 59 | +- specVersion: "4.0" |
| 60 | +- type: application |
| 61 | ++ specVersion: "5.0" |
| 62 | ++ type: component |
| 63 | + metadata: |
| 64 | + name: my.sample.app |
| 65 | +``` |
| 66 | + |
| 67 | +#### 2. Restructure Project Directories |
| 68 | + |
| 69 | +Component Type follows a standardized directory structure: |
| 70 | + |
| 71 | +- **Move `webapp/test` to `test`** - Test folder is now at the project root level |
| 72 | +- **Move `webapp` to `src`** - The source directory is now named `src` instead of `webapp` |
| 73 | + |
| 74 | +::: code-group |
| 75 | +```text [Before (Application)] |
| 76 | +my-app/ |
| 77 | +├── ui5.yaml |
| 78 | +├── package.json |
| 79 | +└── webapp/ |
| 80 | + ├── Component.js |
| 81 | + ├── manifest.json |
| 82 | + ├── index.html |
| 83 | + ├── controller/ |
| 84 | + ├── view/ |
| 85 | + └── test/ |
| 86 | + ├── integration/ |
| 87 | + └── unit/ |
| 88 | +``` |
| 89 | + |
| 90 | +```text [After (Component)] |
| 91 | +my-app/ |
| 92 | +├── ui5.yaml |
| 93 | +├── package.json |
| 94 | +├── src/ |
| 95 | +│ ├── Component.js |
| 96 | +│ ├── manifest.json |
| 97 | +│ ├── controller/ |
| 98 | +│ └── view/ |
| 99 | +└── test/ |
| 100 | + ├── index.html |
| 101 | + ├── integration/ |
| 102 | + └── unit/ |
| 103 | +``` |
| 104 | +::: |
| 105 | + |
| 106 | +#### 3. Adjust `test/index.html` |
| 107 | + |
| 108 | +The `index.html` file is typically moved from `/webapp` to `/test` since it's primarily used for testing the component. |
| 109 | + |
| 110 | +::: tip Note |
| 111 | +If your application needs an HTML page for purposes other than testing, this might be an indicator that the project should continue to use the **application type** instead of migrating to the component type. |
| 112 | +::: |
| 113 | + |
| 114 | +Update the bootstrap script path to the correct relative location (taking the project's namespace into account) and remove the obsolete `data-sap-ui-resource-roots` configuration: |
| 115 | + |
| 116 | +```diff |
| 117 | + <script |
| 118 | + id="sap-ui-bootstrap" |
| 119 | +- src="resources/sap-ui-core.js" |
| 120 | ++ src="../../../../../resources/sap-ui-core.js" |
| 121 | + data-sap-ui-libs="sap.m" |
| 122 | + data-sap-ui-theme="sap_horizon" |
| 123 | +- data-sap-ui-resource-roots='{ |
| 124 | +- "sap.ui.demo.todo": "./" |
| 125 | +- }' |
| 126 | + data-sap-ui-on-init="module:sap/ui/core/ComponentSupport" |
| 127 | + data-sap-ui-async="true"> |
| 128 | + </script> |
| 129 | +``` |
| 130 | + |
| 131 | +::: tip Alternative: Using `<base>` Tag |
| 132 | +Instead of updating the bootstrap script path, you can add a `<base href="../../../../../">` tag in the `<head>` section of your HTML file. This allows you to keep the original path references. |
| 133 | + |
| 134 | +**Important:** The `<base>` tag affects **all relative URLs** in the document (including images, stylesheets, links, scripts, and even in-page anchors like `#some-id`). If certain resources are not loading correctly after adding the `<base>` tag, check whether they were using relative paths that are now being resolved differently than intended. |
| 135 | +::: |
| 136 | + |
| 137 | +#### 4. Adjust `test/testsuite.qunit.html` |
| 138 | + |
| 139 | +Simplify the test suite HTML by removing obsolete bootstrap attributes: |
| 140 | + |
| 141 | +```diff |
| 142 | + <!DOCTYPE html> |
| 143 | + <html> |
| 144 | + <head> |
| 145 | + <meta charset="utf-8"> |
| 146 | + <title>QUnit test suite for Todo App</title> |
| 147 | + <script |
| 148 | +- src="../resources/sap/ui/test/starter/createSuite.js" |
| 149 | ++ src="../../../../../resources/sap/ui/test/starter/createSuite.js" |
| 150 | +- data-sap-ui-testsuite="test-resources/sap/ui/demo/todo/testsuite.qunit" |
| 151 | +- data-sap-ui-resource-roots='{ |
| 152 | +- "test-resources.sap.ui.demo.todo": "./" |
| 153 | +- }' |
| 154 | + ></script> |
| 155 | + </head> |
| 156 | + <body> |
| 157 | + </body> |
| 158 | + </html> |
| 159 | +``` |
| 160 | + |
| 161 | +**Changes:** |
| 162 | +- Remove the `data-sap-ui-testsuite` attribute |
| 163 | +- Remove the `data-sap-ui-resource-roots` attribute |
| 164 | +- Update the `src` path to the correct relative location |
| 165 | + |
| 166 | +#### 5. Adjust `test/testsuite.qunit.js` |
| 167 | + |
| 168 | +Update the test suite configuration to remove obsolete path mappings: |
| 169 | + |
| 170 | +```diff |
| 171 | + sap.ui.define(function () { |
| 172 | + return { |
| 173 | + name: "QUnit test suite for Todo App", |
| 174 | + defaults: { |
| 175 | +- page: "ui5://test-resources/sap/ui/demo/todo/Test.qunit.html?testsuite={suite}&test={name}", |
| 176 | + qunit: { |
| 177 | + version: 2 |
| 178 | +- }, |
| 179 | +- loader: { |
| 180 | +- paths: { |
| 181 | +- "sap/ui/demo/todo": "../" |
| 182 | +- } |
| 183 | + } |
| 184 | + }, |
| 185 | + tests: { |
| 186 | + // ... test definitions |
| 187 | + } |
| 188 | + }; |
| 189 | + }); |
| 190 | +``` |
| 191 | + |
| 192 | +#### 6. Delete Obsolete Test Files |
| 193 | + |
| 194 | +Delete the custom `test/Test.qunit.html` file from your test directory. This file is no longer needed. The framework-provided test page can now be used directly. |
| 195 | + |
| 196 | +#### 7. Update Additional Paths |
| 197 | + |
| 198 | +Depending on your project setup, you might need to update additional paths in configuration files or test runners to reflect the new structure. |
| 199 | +The test suite is now served under the standard `/test-resources/` path with the component's full namespace (e.g. `/test-resources/sap/ui/demo/todo/testsuite.qunit.html`). |
| 200 | + |
| 201 | +## Learn More |
| 202 | + |
| 203 | +- [Project: Type `component`](../pages/Project#component) |
| 204 | +- [Configuration: Specification Version 5.0](../pages/Configuration#specification-version-5-0) |
| 205 | +- [RFC 0018: Component Type](https://github.com/UI5/cli/blob/-/rfcs/0018-component-type.md) |
0 commit comments