UI5 Tooling 3.0
We are very happy to announce the release of UI5 Tooling 3.0. This is the largest release to date, and we are looking forward to getting your feedback on it!
Since 2018, the UI5 Tooling open-source project aims to provide a comprehensive and extensible toolkit for UI5 developers. Being developed right in the core of the UI5 framework, this is the first version that is also used in production to build and release the framework itself.
In this blog post, we would like to give you an overview of the new features UI5 Tooling 3.0 has in store for you and which changes you should be aware of when using it in your UI5 projects.
We are happy to say, this release is fully compatible with existing projects, custom tasks and custom middleware defining Specification Version 2 and later.
Let’s start with some highlights on the build side:
- General support for ECMAScript 2022 language features 🎉
- Generated module bundles now come with source maps 🗺️ for easier debugging
- Significantly faster build times ⏱️
- Building the openui5-sample-app with all its dependencies is about two times faster compared to UI5 Tooling v2
UI5 Workspaces is a new feature in UI5 Tooling 3.0.
They allow you to create flexible local development environments across multiple projects. For example, if you are working on a UI5 application that is making use of a dedicated UI5 library, a UI5 Workspace configuration can bring those together, allowing you to work on the library and see the effect in the application immediately. Without the need for npm links.
UI5 Workspaces are represented by YAML files. They are easy to share, so that your whole team can use the same development environment.
A workspace configuration may look like this:
specVersion: workspace/1.0 metadata: name: default dependencyManagement: resolutions: - path: ../light.library
You can use this workspace configuration in any UI5 project that depends on “light.library”. The library will be resolved from the specified path, relative to the workspace configuration file.
This file is typically named ui5-workspace.yaml. Good to know: If you place such a file next to your project’s ui5.yaml, and if it contains a configuration named “default” (as in the example above), that workspace will be used automatically by the UI5 CLI.
Otherwise, the “workspace” CLI parameter allows you to choose a workspace, since a configuration file can contain multiple workspace configurations.
The UI5 Workspace concept has also been discussed in an RFC.
Always Building Required Dependencies
In the past, UI5 Tooling only built those dependencies requested by the user. For instance, “ui5 build” would only build the current project, whereas “ui5 build -a” would also build all its dependencies.
This could lead to inconsistent build results. If your current project creates bundles containing sources of dependencies for example, those bundles will look different depending on whether the dependencies have been built or not.
UI5 Tooling v3 fixes this by automatically building all dependencies that might influence the build result of a project, before building the project itself.
Specification Version 3.0
UI5 Tooling 3.0 introduces a new Specification Version 3.0. Besides small changes for projects, it’s mainly used to express their incompatibility with previous versions of UI5 Tooling.
For example, if a project uses the latest ECMAScript features in its code, we recommend changing the Specification Version to 3.0, since the project likely can’t be built correctly by UI5 Tooling 2.x.
Enhanced Extension API
The API for UI5 Tooling extensions, such as custom tasks and custom middleware has been enhanced based on community feedback. To access the new API, extensions need to define Specification Version 3.0.
Extensions can now access project metadata and dependency information. Moreover, custom tasks can define which dependencies they require access to.
Our goal was to inject all required UI5 Tooling APIs directly into the extensions at runtime.
This should allow extensions to remove any @ui5/* dependencies from their package.json, making them more lightweight and future-proof.
For example, currently various custom tasks rely on the @ui5/fs module to create resources. With Specification Version 3.0, they can access the required resource factory method “createResource” directly on the TaskUtil instance supplied to them. Future UI5 Tooling versions aim to keep this API compatible to the specification version defined by the extension.
For details, refer to the respective extension documentation for Custom Tasks and Custom Middleware.
These extensibility improvements have also been discussed in an RFC.
Internally, UI5 Tooling now features a graph representation for your project’s dependencies. This allowed for many optimizations. Most prominently, the “ui5.dependencies” section in the package.json is now obsolete and ignored. Once you’ve switched to UI5 Tooling v3, you can safely remove it.
UI5 Tooling 3.0 also includes many bug fixes and optimizations, especially for bundle generation and other build tasks. Find a full list of all improvements and changes in the change log.
It’s as simple as executing the following command in your project:
npm install @ui5/cli@latest
Please ensure that your development environment uses the latest version of Node.js (at least v16.18.0 or v18.12.0). SAP Business Application Studio may be used once it fulfills the new requirements.
Typically, there’s no need to upgrade any specification versions in your projects.
If you run into any trouble, head over to our Migration Guide. If you don’t find your answer there, we invite you to raise an issue on GitHub.
Awesome news. Congratulations to you and the team for making this possible! 🥳
I appreciate the note on SAP BAS as I was looking into that just today. 😁
I guess it is related to the implicit dependencies analysis,
but it seems that the build process takes much more time now:
For example, in one of my projects it takes about 100 seconds (instead of a few seconds previously).
Thank you for your comment. Yes, it's possible that your build will take longer now. Especially if your project is a library or if you added additional tasks to the build. UI5 Tooling might need to build all of your project's dependencies, whereas only the project itself was built before.
However, if you think this might be incorrect behavior, or if you want us to have a look into possibly optimizing your build, feel free to share the output of the following two commands in order for us to analyze this further:
To get a number on how long the dependency analysis takes: "ui5 tree --perf" (should print "Dependency graph generation took xx" at the end)
You can share the logs either here or in a new GItHub issue: https://github.com/SAP/ui5-tooling/issues/new
Any other information on your project will be helpful to us as well. Thanks!
The issue seems to result from a custom task (ui5-task-nwabap-deployer in my case):
and solved in the meanwhile by Florian Pfeffer .
Awesome news! thanks for the blog.
That may not be true depending on your setup. @email@example.com requires node to be ^16.18.0 || >=18.12.0
You are right. It just mentions the fact that you don't need to change code or configuration.