A lot has changed and improved during the past months in TypeScript support for UI5. But let us – peter.muessig and andreas.kunz, the authors of this blog post – start with the recent big announcement:
In case you missed the announcement during the UI5con Keynote: starting with version 1.116.0, the types are ready for productive use. 🎉
We encourage you to use UI5 with TypeScript for an improved development efficiency and experience. TypeScript itself keeps evolving and we try to further improve the UI5 type definitions, so there could still be potential incompatible changes between versions of the type definitions. However, such incompatibilities would only affect the compilation of your code but will not cause runtime issues in your application. Plus, there are various ways to easily deal with them: you can, for example, simply keep using the previous version of the UI5 type definitions together with an updated UI5 runtime.
To keep track of any significant changes, observe the Release Notes.
The best way to get started with a TypeScript setup and basic app is still using the Easy UI5 „ts-app” template. Just do:
- and you get a complete app set up. Actually, the first line is not even needed if you already have installed Yeoman and Easy UI5 (but you might have to update Easy UI5).
While this template has been available for quite some time, it has recently been updated to the latest changes and features. While many others are described below, let's highlight one right here: it now uses the new package name of the type definitions: @openui5/types. If you still use the @openui5/ts-types-esm package make sure to switch over, both for the @sapui5 and @openui5 types, as the old ones will not be updated much longer. And if for some reason you still use a ts-types package with the deprecated globals, by all means please switch!
The @types/openui5 package released via DefinitelyTyped is unaffected and still fine to use.
To improve the development experience, the project setup has been simplified. The TypeScript sources have been moved back into the webapp folder.
Instead of using Babel directly to convert the TypeScript sources to classic UI5 runtime code out of the src folder into the webapp folder, the tooling extension ui5-tooling-transpile handles this tightly integrated into the UI5 development server via its custom middleware or during the build via its custom task.
By default, ui5-tooling-transpile uses a standard configuration for the projects by deriving from the project whether it is a TypeScript project or not. For a TypeScript project it uses the following presets by default: @babel/preset-typescript, babel-preset-transform-ui5, and @babel/preset-env. Custom configuration for the TypeScript or the UI5 preset can be provided via the configuration options: transformTypeScript or transformModulesToUI5 in the ui5.yaml. Instead of a Boolean value you can pass an Object which will be forwarded as configuration to the respective preset.
If you need more control over the Babel configuration, just put e.g. the .babelrc into your project. It will be used over the inline configuration in the ui5.yaml.
To complete the end-2-end experience, all TypeScript UI5 templates now contain a proper setup for QUnit and OPA testing. The entry point for the testing is the webapp/test/testsuite.qunit.html. It loads testsuite.qunit.js which lists all QUnit and OPA testsuites. The central testsuite is also used for the automation of the test execution via Karma (although Karma is deprecated, we continue to support this setup until we come up with a new testing solution).
For the test execution the package.json contains the contains the following scripts:
The coverage results fully supports TypeScript and shows the coverage directly in the TypeScript sources and the setup for the coverage is straight forward. More details about the testing can be found in the UI5 TypeScript tutorial: https://github.com/SAP-samples/ui5-typescript-tutorial/tree/main/exercises/ex6.
Regarding the test implementation, some parts are unchanged in TypeScript compared to JavaScript, some others slightly adapted due to the ES module syntax, and some others changed substantially:
Since version 1.115 handing events in TypeScript has become a lot easier: for all the events and their parameters there are now specific types. These events are named “<controlname>$<eventname>Event”. The significant control name is the one where the event was actually defined, which can sometimes be a control from which the actually used one inherits. The “change” event of the “sap.m.Input” is actually defined on the “InputBase” control, so the type is called InputBase$ChangeEvent. Using this type will now give you type safety for the event-specific parameters.
There have been many more changes and more will come, so it is a good idea to continue having an eye on the UI5 TypeScript Release Notes.
A last one to mention here because it required adaptation and is often used is one regarding sap.ui.Device. This API is often used in the app’s Component to set the content density class depending on the device’s touch support.
Prior to version 1.115 it had to be used like this with named imports for the API’s parts:
Now the parts are available as properties of the default export, which means it needs to be used like this:
Next to the TypeScript UI5 application template, you can also find a TypeScript UI5 library template. Just get started via:
Custom UI5 libraries can be easily consumed in your UI5 application by adding a simple dependency to the library.
For UI5 libraries built with TypeScript, the type definitions are now properly created and referenced from a generated index.d.ts file to get code completion support in your application. More infos about UI5 library development can be found here: https://github.com/SAP-samples/ui5-typescript-control-library.
We hope this round-up motivates you to finally look into TypeScript as UI5 programming language if you haven’t done so before – or confirms your motivation if you have already!
In case a 100-minute UI5 TypeScript tutorial is just what you need to get started, we got you covered with this one here. It's brand-new and covers all those latest changes as well as the full setup from scratch, up to advanced topics like using third-party npm packages and control development as well as testing.
Why hesitate?
The TypeScript type definitions for UI5 are no longer “in experimental beta”
In case you missed the announcement during the UI5con Keynote: starting with version 1.116.0, the types are ready for productive use. 🎉
We encourage you to use UI5 with TypeScript for an improved development efficiency and experience. TypeScript itself keeps evolving and we try to further improve the UI5 type definitions, so there could still be potential incompatible changes between versions of the type definitions. However, such incompatibilities would only affect the compilation of your code but will not cause runtime issues in your application. Plus, there are various ways to easily deal with them: you can, for example, simply keep using the previous version of the UI5 type definitions together with an updated UI5 runtime.
To keep track of any significant changes, observe the Release Notes.
Get started quickly - what changed?
The best way to get started with a TypeScript setup and basic app is still using the Easy UI5 „ts-app” template. Just do:
npm install -g yo generator-easy-ui5
yo easy-ui5 ts-app- and you get a complete app set up. Actually, the first line is not even needed if you already have installed Yeoman and Easy UI5 (but you might have to update Easy UI5).
While this template has been available for quite some time, it has recently been updated to the latest changes and features. While many others are described below, let's highlight one right here: it now uses the new package name of the type definitions: @openui5/types. If you still use the @openui5/ts-types-esm package make sure to switch over, both for the @sapui5 and @openui5 types, as the old ones will not be updated much longer. And if for some reason you still use a ts-types package with the deprecated globals, by all means please switch!
The @types/openui5 package released via DefinitelyTyped is unaffected and still fine to use.
Simplified Project Setup
To improve the development experience, the project setup has been simplified. The TypeScript sources have been moved back into the webapp folder.
 |  |
Instead of using Babel directly to convert the TypeScript sources to classic UI5 runtime code out of the src folder into the webapp folder, the tooling extension ui5-tooling-transpile handles this tightly integrated into the UI5 development server via its custom middleware or during the build via its custom task.
specVersion: "3.0"
[…]
builder:
customTasks:
- name: ui5-tooling-transpile-task
afterTask: replaceVersion
server:
customMiddleware:
- name: ui5-tooling-transpile-middleware
afterMiddleware: compression
[…]By default, ui5-tooling-transpile uses a standard configuration for the projects by deriving from the project whether it is a TypeScript project or not. For a TypeScript project it uses the following presets by default: @babel/preset-typescript, babel-preset-transform-ui5, and @babel/preset-env. Custom configuration for the TypeScript or the UI5 preset can be provided via the configuration options: transformTypeScript or transformModulesToUI5 in the ui5.yaml. Instead of a Boolean value you can pass an Object which will be forwarded as configuration to the respective preset.
customTasks:
- name: ui5-tooling-transpile-task
afterTask: replaceVersion
configuration:
transformModulesToUI5:
overridesToOverride: trueIf you need more control over the Babel configuration, just put e.g. the .babelrc into your project. It will be used over the inline configuration in the ui5.yaml.
TypeScript-based QUnit/OPA Testing completes End-2-End Experience
Karma Setup
To complete the end-2-end experience, all TypeScript UI5 templates now contain a proper setup for QUnit and OPA testing. The entry point for the testing is the webapp/test/testsuite.qunit.html. It loads testsuite.qunit.js which lists all QUnit and OPA testsuites. The central testsuite is also used for the automation of the test execution via Karma (although Karma is deprecated, we continue to support this setup until we come up with a new testing solution).
For the test execution the package.json contains the contains the following scripts:
- karma: Test-driven development by running Karma in parallel watching to file changes to run tests
- karma-ci: Headless automated testing during build execution
- karma-ci-cov: Headless automated testing during build execution + collecting coverage results
The coverage results fully supports TypeScript and shows the coverage directly in the TypeScript sources and the setup for the coverage is straight forward. More details about the testing can be found in the UI5 TypeScript tutorial: https://github.com/SAP-samples/ui5-typescript-tutorial/tree/main/exercises/ex6.
Test Implementation
Regarding the test implementation, some parts are unchanged in TypeScript compared to JavaScript, some others slightly adapted due to the ES module syntax, and some others changed substantially:
- Unchanged is how the unit tests are implemented: it’s a straight-forward port of the JavaScript code without changes.
- Adapted to ES module syntax is how the test suites import the tests: both in the unit tests as well as the OPA test journeys, the QUnit autostart is first paused, then the test modules are loaded (and asynchronously) using dynamic ES module imports, then QUnit.start() is called to launch the tests.
- Changed substantially is the OPA test implementation. The OPA APIs are not well-suited for a typed world, so we suggest writing integration tests in TypeScript in a different and simplified manner. Journeys do not operate on “Given”, “When” and “Then” passed in by OPA (which in the past also required to register the actions and assertions with OPA in the first place). Instead, the journeys simply call action and assertion methods on an imported module or class instance.
The OPA Pages, on the other hand, are simply classes inheriting from Opa5 and having the actions and assertions.
Events are Typed
Since version 1.115 handing events in TypeScript has become a lot easier: for all the events and their parameters there are now specific types. These events are named “<controlname>$<eventname>Event”. The significant control name is the one where the event was actually defined, which can sometimes be a control from which the actually used one inherits. The “change” event of the “sap.m.Input” is actually defined on the “InputBase” control, so the type is called InputBase$ChangeEvent. Using this type will now give you type safety for the event-specific parameters.
More Changes
There have been many more changes and more will come, so it is a good idea to continue having an eye on the UI5 TypeScript Release Notes.
A last one to mention here because it required adaptation and is often used is one regarding sap.ui.Device. This API is often used in the app’s Component to set the content density class depending on the device’s touch support.
Prior to version 1.115 it had to be used like this with named imports for the API’s parts:
import { support } from "sap/ui/Device";
if (support.touch) {Now the parts are available as properties of the default export, which means it needs to be used like this:
import Device from "sap/ui/Device";
if (Device.support.touch) {App Development is not enough? You can also develop Libraries with TypeScript!
Next to the TypeScript UI5 application template, you can also find a TypeScript UI5 library template. Just get started via:
yo easy-ui5 ts-libraryCustom UI5 libraries can be easily consumed in your UI5 application by adding a simple dependency to the library.
For UI5 libraries built with TypeScript, the type definitions are now properly created and referenced from a generated index.d.ts file to get code completion support in your application. More infos about UI5 library development can be found here: https://github.com/SAP-samples/ui5-typescript-control-library.
Enjoy TypeScript! And check out the new Tutorial!
We hope this round-up motivates you to finally look into TypeScript as UI5 programming language if you haven’t done so before – or confirms your motivation if you have already!
In case a 100-minute UI5 TypeScript tutorial is just what you need to get started, we got you covered with this one here. It's brand-new and covers all those latest changes as well as the full setup from scratch, up to advanced topics like using third-party npm packages and control development as well as testing.
Why hesitate?
Authors
 peter.muessig is initial member of the UI5 team, stumbled into the role of the Chief Architect for SAPUI5, driving the evolution of the UI5 framework, the tooling, and the programming model to the next level. |
 andreas.kunz is software developer and architect at SAP since 2005, focusing on web-based user interfaces. Member of the UI5 development team since its inception and a main driver behind open-sourcing it as OpenUI5. |
- SAP Managed Tags:
3 Comments
