UI5 Tooling 3.0

[merlin_beutlberger]

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.

Build Improvements

Let’s start with some highlights on the build side:

• General support for ECMAScript 2022 language features 🎉
  
  
  
  • *Some limitations might apply
  
  
  
  


• 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

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.

Other Changes

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.

Upgrade Today

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.