This is a follow-up of today’s announcement post "Introducing UI5 Tooling for SAPUI5 Projects".
Since we first released the UI5 Tooling open-source project two years ago, we’ve continuously worked toward enabling every developer to freely choose how they work on their OpenUI5 and SAPUI5 projects.
In this blog post I want to give you a more detailed look into how we realized the consumption of SAPUI5 libraries in the UI5 Tooling. A big leap for SAPUI5 development.
With today’s release of the UI5 Tooling version 2.0, it is now able to fetch all SAPUI5 resources required for your project by itself. No more downloading and unpacking ZIP files from tools.hana.ondemand.com, no more proxy magic to forward requests to an SAP NetWeaver system or the SAP CDN.
While it is the UI5 Tooling that fetches the resources, they are hosted on the public npm registry at registry.npmjs.org. “So,” you might wonder, “why is it the UI5 Tooling and not the npm CLI that fetches the packages?” Well, here’s the story…
The Challenge: Versioning
In general, SAPUI5 follows Semantic Versioning. SAPUI5 version numbers follow the scheme MAJOR.MINOR.PATCH. While patches are mostly bug fixes, minor releases bring new features. And since a new major release is yet to come, older SAPUI5 applications can still work with the latest version of SAPUI5.
However, SAPUI5 consists of more than 50 individual libraries. In every SAPUI5 release, these libraries are arranged in a unique combination of versions. We usually refer to such a collection by calling it a SAPUI5 Distribution.
Example: SAPUI5 Distribution Release 1.71.9
Take a look at https://sapui5.hana.ondemand.com/1.71.9/patchinfo.html
You can see that SAPUI5 1.71.9 contains (among others) the following:
| Library Name | Version |
| sap.fe | 1.71.0 |
| sap.fiori | 1.71.9 |
| sap.gantt | 1.71.3 |
| sap.ui.core | 1.71.8 |
| sap.m | 1.71.8 |
| … | … |
What happened here?
Let’s start with sap.fe. This library did not provide any patch for the 1.71 code line (at least until 1.71.9 was released). That’s why Version 1.71.0 is still used.
sap.gantt created a total of three patches so far: 1.71.1, 1.71.2 and 1.71.3.
sap.ui.core and sap.m are special, because they are OpenUI5 libraries. Currently, OpenUI5 libraries are always released as a whole. This means that whenever there is a change to be released for any of the OpenUI5 libraries, the new patch includes them all. You can see this here (check the change log): https://openui5.hana.ondemand.com/1.71.8/patchinfo.html.
Where does this leave us?
Every SAPUI5 Distribution release combines different versions of libraries. There might be changes in two libraries that depend on each other. This means that you can’t mix and match any version of library X with any other version of library Y. You must use exactly the version combination (including the patch level) contained in a SAPUI5 Distribution release. Semantic Versioning, which is one of the basic concepts that npm facilitates (see their documentation "About semantic versioning"), defines something different. Major and minor releases of any package are meant to be fully compatible. For SAPUI5, this would mean that the library sap.m in Version 1.28.9 worked flawlessly with the library sap.ui.core in Version 1.71.0.
However, this is not the case. In fact, sap.m in Version 1.71.0 might not even be compatible to sap.ui.core in Version 1.71.1.
This means that there is no way for us to correctly define semantic version requirements for dependencies between SAPUI5 libraries. When publishing sap.m in Version 1.71.0 we can’t tell whether it will be compatible to sap.ui.core Version 1.71.1 or any subsequent version.
At the same time, as a UI5 developer, you can only define exact versions and no version ranges for your SAPUI5 dependencies. And installing just one of the libraries in the wrong version can lead to unforeseeable issues at runtime.
As you can see, our starting position conflicts with some fundamental ideas of the npm ecosystem. The alternatives in view do not seem to make up an easy-to-use solution:
There are ongoing discussions on features that could help with our case, like the idea of adding "Singleton Packages" to npm. We also love the increasing support for Monorepos and workspace-like setups by Yarn and npm, as this reflects how many UI5 projects are being developed.
On the other hand, changes like those planned for npm’s handling of peerDependencies made us worry about how future-proof any solution can be that is not completely in line with what npm, Yarn and similar node-based package managers have in mind when thinking of a "node package".
In fact, the use of peerDependencies was part of a possible npm-based solution we’ve been pursuing for a long time. It was one of at least nine different solutions that we weighed against each other on points like "Non-Proprietary", "Minimal download size", "Hard to create inconsistent states" and "Overall ease of use". Let’s introduce the eventual winner of this evaluation process.
The Solution
As it turned out that we cannot use the standard npm-mechanisms to define dependencies, we came up with our own way to overcome this problem.
By integrating the dependency resolution and -version handling into the UI5 Tooling we are not only able to solve the above problems, but also to offer you a better overall development experience.
Instead of providing a package-manager-like CLI interface to install packages, we decided to seamlessly integrate this into the UI5 Tooling. This means there are no additional commands that you need to execute.
The only required addition to an existing SAPUI5 project is to declare the SAPUI5 version and a list of dependencies to use in the ui5.yaml.
This approach will enhance today’s SAPUI5 development setups in many ways.
Starting from today, you will see the following features:
- Based on your ui5.yaml configuration, "ui5 build" and "ui5 serve" will automatically download the correct versions of all required packages.
- A seamless switch between SAPUI5 versions using the CLI parameter "
--framework-version". - A shared local cache for all SAPUI5 resources in the ~/.ui5 directory.
- Consumption of other packages using npm will continue to work as is.
In the future, the UI5 Tooling could also dynamically download pre-built resources depending on your use in order to speed up your project’s build time.
With these changes we are in fact following some of npm’s own recommendations on “Building your own front-end package management using npm” as outlined here: https://blog.npmjs.org/post/101775448305/npm-and-front-end-packaging
How It Works
SAPUI5 libraries are still going to be published at the public npm registry at registry.npmjs.org and will be offered under the SAP Developer License Agreement.
However, we discourage you to install them using the npm or Yarn CLI, as you will likely run into issues caused by incompatible version combinations, as explained above.
Instead, the UI5 Tooling will feature a new configuration section that you will need to add to your SAPUI5 project’s ui5.yaml:
specVersion: "2.0"
# [...]
framework:
name: SAPUI5
version: '1.76.0'
libraries:
- name: sap.ui.core
- name: sap.viz
- name: themelib_sap_belize
- name: themelib_sap_fiori_3
- name: sap.ushell
development: true
Here, you first have to define the framework "SAPUI5" and the version you want to consume in your project. Note that the UI5 Tooling exclusively uses the version configuration of the current root project (e.g. the project "ui5 serve" is being executed in).
What follows next is a list of SAPUI5 libraries (including OpenUI5 libraries) that the project depends on. Some might be for testing and development purposes only and can be flagged as development. This prevents them from being downloaded, unless the current project is the root project.
Note that only SAPUI5 and OpenUI5 libraries can be specified here. Custom libraries and other dependencies are still consumed using a node package manager like npm and defined in the project’s package.json.
You end up with the best of both worlds: You can use state-of-the-art node package managers of your choice to easily integrate third-party packages from various sources, and we can give you an unmatched experience for consuming SAPUI5 libraries, where you don’t have to worry about downloading the correct set of libraries in the correct version combination.
Getting Started
All you need is the UI5 CLI in Version 2.0 or later:
npm install --global @ui5/cli@latestMake sure that you have installed Node.js in Version 10+.
Then set up your project for use with the UI5 Tooling. For an initial setup, follow our Getting Started documentation at
https://sap.github.io/ui5-tooling/pages/GettingStarted.
For detailed information, also on enhancing an existing UI5 Tooling setup, check out our documentation on consuming SAPUI5 libraries at
https://sap.github.io/ui5-tooling/pages/SAPUI5.
One More Thing
From Day One, the UI5 Tooling was more than just a UI5 command line interface. For advanced use cases, we provide a comprehensive JavaScript API that allows you to integrate parts of the UI5 Tooling into your own tools at a lower level.
If you already use the @ui5/project.normalizer#generateDependencyTree API there’s nothing you need to do. Starting with Version 2.0.0 of the @ui5/project module, framework dependencies are automatically retrieved for projects that have a "framework" configuration as described above and have set their "specVersion" to "2.0".
If you want to integrate at an even lower level, you can use the @ui5/project.ui5Framework.Openui5Resolver or @ui5/project.ui5Framework.Sapui5Resolver classes to install framework dependencies manually. They take care of the necessary dependency resolution as well as caching.
Please reach out to us if you run into any problems or limitations when integrating these APIs into your own tools and services.
Feedback
We highly value your feedback on this topic. We think this will define the way SAPUI5 apps are developed for years to come. Please feel free to share your thoughts in the comment section below and on social media.
You’re also welcome to join the discussion in the #tooling channel of the OpenUI5 Community Slack here.
Previous Post: UI5ers Buzz #48
Author
 merlin.beutlberger#about is an architect in the UI5 Core area, always striving to make UI5 applications the best in their field. He loves to travel the world while sleeping in tents and cars.You can also find him on Twitter! |
- SAP Managed Tags:
8 Comments
