diff --git a/internal/documentation/.vitepress/config.ts b/internal/documentation/.vitepress/config.ts index d7b22d09ecb..ab2c702f67f 100644 --- a/internal/documentation/.vitepress/config.ts +++ b/internal/documentation/.vitepress/config.ts @@ -233,6 +233,10 @@ function guide() { text: "Upgrade Guides", collapsed: false, items: [ + { + text: "Migrate to v5", + link: "/updates/migrate-v5", + }, { text: "Migrate to v4", link: "/updates/migrate-v4", diff --git a/internal/documentation/docs/pages/Project.md b/internal/documentation/docs/pages/Project.md index a3f5108842c..e4fe1843eb6 100644 --- a/internal/documentation/docs/pages/Project.md +++ b/internal/documentation/docs/pages/Project.md @@ -34,7 +34,7 @@ Unlike `application`-type projects, component projects typically don't have dedi Component projects support all [output styles](#build-output-style) that library projects currently support. This allows a deployment where you can omit the namespace from the final directory structure using the output style: `flat`. -For more details, see also [RFC 0018 Component Type](https://github.com/UI5/cli/blob/rfc-component-type/rfcs/0018-component-type.md#rfc-0018-component-type). +For more details, see also [RFC 0018 Component Type](https://github.com/UI5/cli/blob/-/rfcs/0018-component-type.md). ### application Projects of the `application` type typically serve as the main or root project. In a project's dependency tree, there shouldn't be more than one project of this type. If the system detects additional application projects, it ignores those that are further away from the root. diff --git a/internal/documentation/docs/updates/migrate-v5.md b/internal/documentation/docs/updates/migrate-v5.md new file mode 100644 index 00000000000..b4de575af10 --- /dev/null +++ b/internal/documentation/docs/updates/migrate-v5.md @@ -0,0 +1,205 @@ +# Migrate to v5 + +::: tip Alpha Release Available +**UI5 CLI 5.0 Alpha is now available for testing! 🎉** + +Try the alpha release in your projects via: `npm i --save-dev @ui5/cli@next` +Or update your global install via: `npm i --global @ui5/cli@next` + +**Note:** This is a pre-release version. +::: + +## Breaking Changes + +- **All UI5 CLI Modules require Node.js ^22.20.0 || >=24.0.0** + +- **@ui5/cli: `ui5 init` defaults to Specification Version 5.0** + + +## Node.js and npm Version Support + +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. +Support for older Node.js releases has been dropped; their use will cause an error. + +## Specification Versions Support + +UI5 CLI 5.x introduces **Specification Version 5.0**, which enables the new Component Type and brings improved project structure conventions. + +Projects using older **Specification Versions** are expected to be **fully compatible with UI5 CLI v5**. + +## UI5 CLI Init Command + +The `ui5 init` command now generates projects with Specification Version 5.0 by default. + +## Component Type + +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. + +This feature will allow developers to serve and build multiple UI5 application components concurrently, enhancing the local development environment for integration scenarios. + +**Note:** A component type project must contain both a `Component.js` and a `manifest.json` file in the source directory. + +More details about the Component Type can be found in the [Project: Type `component`](../pages/Project#component) documentation. + +### Migrating from Application to Component Type + +If you have an existing application that you'd like to migrate to the Component Type, there are several steps to follow. +The migration involves updating your project configuration and restructuring your project directories to align with the Component Type conventions. + +**Main changes**: +1. Source directories `src` and `test` instead of `webapp` and `webapp/test` +1. Files are served under `/resources//` and `/test-resources//` paths (instead of `/` and `/test/`) + - This affects (relative)-paths in HTML files, test suite configuration, and test runner setups + +#### 1. Update `ui5.yaml` Configuration + +Update your `ui5.yaml` file to use the Component Type and Specification Version 5.0: + +```diff +- specVersion: "4.0" +- type: application ++ specVersion: "5.0" ++ type: component + metadata: + name: my.sample.app +``` + +#### 2. Restructure Project Directories + +Component Type follows a standardized directory structure: + +- **Move `webapp/test` to `test`** - Test folder is now at the project root level +- **Move `webapp` to `src`** - The source directory is now named `src` instead of `webapp` + +::: code-group +```text [Before (Application)] +my-app/ +├── ui5.yaml +├── package.json +└── webapp/ + ├── Component.js + ├── manifest.json + ├── index.html + ├── controller/ + ├── view/ + └── test/ + ├── integration/ + └── unit/ +``` + +```text [After (Component)] +my-app/ +├── ui5.yaml +├── package.json +├── src/ +│ ├── Component.js +│ ├── manifest.json +│ ├── controller/ +│ └── view/ +└── test/ + ├── index.html + ├── integration/ + └── unit/ +``` +::: + +#### 3. Adjust `test/index.html` + +The `index.html` file is typically moved from `/webapp` to `/test` since it's primarily used for testing the component. + +::: tip Note +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. +::: + +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: + +```diff + +``` + +::: tip Alternative: Using `` Tag +Instead of updating the bootstrap script path, you can add a `` tag in the `` section of your HTML file. This allows you to keep the original path references. + +**Important:** The `` 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 `` tag, check whether they were using relative paths that are now being resolved differently than intended. +::: + +#### 4. Adjust `test/testsuite.qunit.html` + +Simplify the test suite HTML by removing obsolete bootstrap attributes: + +```diff + + + + + QUnit test suite for Todo App + + + + + +``` + +**Changes:** +- Remove the `data-sap-ui-testsuite` attribute +- Remove the `data-sap-ui-resource-roots` attribute +- Update the `src` path to the correct relative location + +#### 5. Adjust `test/testsuite.qunit.js` + +Update the test suite configuration to remove obsolete path mappings: + +```diff + sap.ui.define(function () { + return { + name: "QUnit test suite for Todo App", + defaults: { +- page: "ui5://test-resources/sap/ui/demo/todo/Test.qunit.html?testsuite={suite}&test={name}", + qunit: { + version: 2 +- }, +- loader: { +- paths: { +- "sap/ui/demo/todo": "../" +- } + } + }, + tests: { + // ... test definitions + } + }; + }); +``` + +#### 6. Delete Obsolete Test Files + +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. + +#### 7. Update Additional Paths + +Depending on your project setup, you might need to update additional paths in configuration files or test runners to reflect the new structure. +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`). + +## Learn More + +- [Project: Type `component`](../pages/Project#component) +- [Configuration: Specification Version 5.0](../pages/Configuration#specification-version-5-0) +- [RFC 0018: Component Type](https://github.com/UI5/cli/blob/-/rfcs/0018-component-type.md)