Skip to Content
Technical Articles
Author's profile photo Peter Muessig

Getting Started with TypeScript for UI5 Application Development

Introduction

Last year at the UI5con ON AIR 2020, we promised to enable TypeScript for UI5 application development and demonstrate it at the UI5con ONAIR 2021.

ES6%20and%20TypeScript%20Enablement

ES6 and TypeScript Enablement

From UI5con 2020 to UI5con 2021 we had two big challenges:

  1. Where do we get the proper TypeScript type definitions from?
  2. How do we want to develop our UI5 TypeScript applications in future?

Initially, we created the TypeScript type definitions with the UI5 TypeScript generator to support the code completion for UI5 application development in modern IDEs. The initial version of the generator creates type definitions based on the JSDoc of UI5 as UI5 is not built with TypeScript and this is the best possible source. Over the last year, we invested a lot of time into improving the UI5 JSDoc to create as good as possible TypeScript type definitions and for sure this also improved the quality of our API reference in the Demo Kit.

The other challenge was a bit more complicated to decide on a future direction of the programming model for UI5 TypeScript applications. The first TypeScript type definitions for UI5 are based on the current APIs and thus provide support to work with the UI5 AMD-like syntax and the UI5 classes and even the deprecated synchronous APIs. But we wanted to even go a step further by providing a modern development experience based on top of the latest UI5 APIs and even more ES6+ APIs. Within SAP, several teams in several areas already investigated how to use TypeScript for UI5 development and implemented different solutions. While investigating the different solutions one approach became really interesting: using Babel to transpile the TypeScript code into ES6+ JavaScript code and then generating UI5 code out of it. The big advantage is that the generated code is classic UI5 code and runs on our current APIs but you can write TypeScript UI5 applications with ES modules, ES classes and even more ES6+ features.

The key piece besides the TypeScript type definitions for this solution is the Babel plugin babel-plugin-transform-modules-ui5. It converts ES modules into the UI5 AMD-like syntax and the ES classes into UI5 classes. The benefit of ES modules and ES classes is that they are supported out-of-the-box by most modern editors like VSCode and we can benefit especially from code-completion or refactoring support.

Getting Started with TypeScript

To see the suggested project setup for TypeScript development, please check out the TypeScript Hello World app. It not only can serve as copy template, but also includes a detailed step-by-step guide for creating this setup from scratch.

The TypeScript branch of the “UI5 CAP Event App” sample demonstrates a slightly more complex application, using the same setup. It comes with an explanation of what UI5 TypeScript code usually looks like and what to consider when writing such code.

For quick and easy scaffolding of a new UI5 application written in TypeScript, you can also use the Yeoman generator easy-ui5 with the generator-ui5-ts-app sub-generator.

Generate Your First UI5 TypeScript Application

This blog post will focus on the third option and explain you, how to use this Yeoman generator easy-ui5 to kick-start your TypeScript development experience for UI5. At the keynote for the UI5con ONAIR 2021, I just started my demo with the console. In the console I run the easy-ui5 Yeoman generator which pulls its templates from the UI5 Community GitHub organization. Short before the keynote we published the sub-generator to create UI5 TypeScript application which extends easy-ui5 (thanks to the new easy-ui5 version 3.0). Within the application I could demonstrate how it feels to us the latest OpenUI5 type definitions.

Connecting%20Innovations

UI5con ONAIR 2021 – Connecting Innovations

Every UI5 developer can now make his own experience with TypeScript and now it’s your time to do so.

Prerequisites

To get started, you need to ensure that you have a recent Node.js version 12 or higher installed on your machine.

Install Yeoman And Easy-UI5

As a next step, you should install Yeoman and the easy-ui5 generator:

npm install -g yo generator-easy-ui5

To verify, that the installation was successful, just run the following command:

yo --generators

Make sure you see the “easy-ui5” generator listed.

!! To verify the version of the installed generator-easy-ui5 you can run the following command:

npm info generator-easy-ui5 version

The version should be at least 3.0.1 to be able to consume the templates from the UI5 Community GitHub organization listed here.

Create Your Project

Now, you can start to create your first UI5 TypeScript application project by running the following command:

yo easy-ui5 ts-app

This directly calls the ts-app sub-generator of easy-ui5 which creates the project for the UI5 TypeScript application based on e.g. the following parameters:

? How do you want to name this application? myapp
? Which namespace do you want to use? com.myorg
? Which framework do you want to use? OpenUI5
? Which framework version do you want to use? 1.91.0
? Who is the author of the library? Your Name
? Would you like to create a new directory for the application? Yes

After entering the parameters, easy-ui5 already runs npm install to ensure that you can immediately start working in your new project.

Open Your Project

Switch into new folder com.myorg.myapp and open the editor of your choice (e.g. VSCode). In the project root of the UI5 TypeScript application you will find the well-known package.json and ui5.yaml. Compared to the classic UI5 application projects, the characteristic of the UI5 TypeScript application project is that the sources can be found in the src folder instead of the webapp folder and includes TypeScript instead of JavaScript sources:

project-root
\- src
   \- [...]
   \- Component.ts
   \- manifest.json
   \- index.html
\- [...]
\- package.json
\- README.md
\- ui5.yaml

More details about the project, the project structure and how to use this project can be found in the project root in the README.md. As the project template is based on the ui5-typescript-helloworld project, you can also read the following README.md online.

Running Your Project

To get an impression about the project and what it finally provides, just run your project in the development mode with the following command:

npm start

This runs Babel in watch mode which transpiles and copies the sources from src to webapp folder. On top of the webapp folder, the UI5 tooling is running the development server to serve the project.

Resource%20Processing%20Flow

Resource Processing Flow

Finally, it opens your default browser which runs the application. While the application is running you can now modify the application in your editor and directly see the changes after you saved them.

Bundle Your Project

Once you completed the development of the application, the package.json defines two scripts to bundle the application:

# Build a deployable project
npm run build

# Build an optimized, self-contained deployable project (takes time)
npm run build:opt

More details about building and checking the application can also be found in the included README.md.

Wrap Up

Now, you should be able to create your first UI5 TypeScript project from scratch and gather your first experience with ES modules and ES classes in UI5. The TypeScript support is still in an experimental phase as we still improve the generator, the JSDoc and the type definitions. It may be needed to do  changes in the generator and the type definitions in the near future. If you have feedback around the TypeScript support for UI5, please let us know.

 

Assigned Tags

      9 Comments
      You must be Logged on to comment or reply to a post.
      Author's profile photo Former Member
      Former Member

      Great Blog Peter Muessig !

      Before UI5Con 2021 I fiddled around with the standalone Types definition of the older version of https://github.com/SAP-samples/ui5-cap-event-app/tree/typescript.

      After UI5Con I directly jumped to your presentation. I very much like the new NPM packages 🙂 I already built the first little App using this approach and it is what I always missed from UI5 before.

      As you asked for feedback:

      My setup is rather old school: Local VS Code with UI5 CLI installed hooked up to a Netweaver server. Away from the Internet behind a lot of firewalls and proxys.

      Regarding the Typescript part I am very happy. I configured my build script to directly transpile, build and deploy to the server. Works like a charm!

      Only issue I discovered so far: Documentation seems to be "broken". I wrote more here https://answers.sap.com/questions/13428293/generate-documentation-for-typescript-ui5-project.html

      On thing that kind of bothers me is the performance in general: As I need the UI5 library on my local server (no CDN, no current FIORI package) I usually use the "self-contained" build option with flag "--all" to include themes. Doing the whole build and automatic deployment takes quite long.

      The TS step adds a little more to the build process.

      All in all: Excellent work!

      Author's profile photo Peter Muessig
      Peter Muessig
      Blog Post Author

      Hi Former Member ,

      thanks for your feedback! I'm happy to hear that our effort pays out. 🙂

      Regarding the feedback to generate the type definitions for a UI5 project - we are also working on this. One of our next steps is to merge the changes of the UI5 TypeScript generator with the official OSS repository. We have still some challenges here but this is the goal. Finally, it should be possible to use the UI5 Tooling to generate the JSDoc and also the type definitions (for classic UI5 projects) and for TypeScript projects we should be able to consume this directly (need to investigate this further).

      Regarding the local development performance, just an idea: did you think about using the servestatic middleware from the UI5 Ecosystem Showcase and include the UI5 from a ZIP. With that you have your built UI5 version local instead of the dev-sources via the UI5 Tooling (BTW: this is also one thing we are discussing, to improve the build performance).

      Thanks so much and best regards,

      Peter

      Author's profile photo Pascal Wasem
      Pascal Wasem

      Peter Muessig really nice blog! I am looking forward to use this setup in my next project!

      With all of this being available now, there is only one last piece missing:

      How to include Babel Polyfills in case one want to use e.g. async… await or newer EcmaScript features and one has to target older browsers?

      Many thanks,

      Pascal

       

      Author's profile photo Peter Muessig
      Peter Muessig
      Blog Post Author

      HI Pascal Wasem ,

      thanks for your feedback. Regarding the Babel Polyfills, we still have your issue open: https://github.com/SAP/openui5/issues/3172. Due to the IE11 de-support of UI5 1.88+ this might be not so critical anymore as most of the formerly problematic functionality (like async..await) is available in the latest Browser PAM and no polyfill is needed anymore. Since 1.88 we are also cleaning up our code-base from IE11 specific code/css/polyfills.

      But the question itself stays for the newer/upcoming EcmaScript features. Especially the language features may be critical when they are used and required early in the flow - like the issue with the usage of async..await in a UI5 Component which requires to load the regenerator polyfill earlier than possible. IMO, we need to work on two things here: a new bootstrap (as mentioned at the UI5con keynote) which allows to integrate polyfills into the bootstrap phase early, before the framework boots and a possibility to early include and share polyfills by applications. Here the challenges are the right timing and avoid redundancies!

      We are still thinking about this question, to also tackle this one last, but very hard, missing piece...

      Best regards,

      Peter

      Author's profile photo Lịch 365 Âm Lịch VN
      Lịch 365 Âm Lịch VN

      niceeeeeeeeee

      Author's profile photo Rafael Lopez Martinez
      Rafael Lopez Martinez

      Awesome!! Time to implement this in our team! Thanks Peter Muessig and team!

      Author's profile photo Marc Schleeweiß
      Marc Schleeweiß

      I was trying to implement some small example myself and see how far I get.

      It seems like TypeScript getters and setters are broken.

      I created some private property and a corresponding getter/setter (and also a traditional getter and setter because they work).

      private _contentClass = "content";
      
      get contentClass(): string {
      	return this._contentClass;
      }
      set contentClass(cls: string) {
      	this._contentClass = cls;
      }
      getContentClass(): string {
      	return this._contentClass;
      }
      
      setContentClass(cls: string): void {
      	this._contentClass = cls;
      }

       

      Waaay later (on button press) I call my getters and setters

      console.log(this.getOwnerComponent().contentClass); // undefined
      console.log(this.getOwnerComponent().getContentClass()); // "content"
      this.getOwnerComponent().contentClass = "direct";
      this.getOwnerComponent().setContentClass("indirect");
      console.log(this.getOwnerComponent().contentClass); // "direct"
      console.log(this.getOwnerComponent().getContentClass()); // "indirect"

       

      Seems like the TypeScript getter is called immediately (even before the constructor) where `this` isn't properly defined. After that it's called never (probably gets transpiled in some kind of object property?)

       

      This is an open issue since April 2019 (https://github.com/r-murphy/babel-plugin-transform-modules-ui5/issues/25). Is this in your roadmap? Or will there be some kind of official babel plugin (the current preset seems kind of unsupported, there are no answers from the author to any issues).

      Author's profile photo Tulio Vargas
      Tulio Vargas

      Hi Peter !!
      very good article, I am going to test typescript and this post will be helpful.

      Congrats

      Author's profile photo Peter Muessig
      Peter Muessig
      Blog Post Author

      Thanks, Tulio. More is on the way… 😉