My first experience with TypeScript in UI5 - Introduction

[WouterLemaire]

Around April SAP announced for the first time TypeScript Support for UI5. Since then, I’ve tried to use this in every new UI5 project where possible. Now it is time to share what my experience with TypeScript in UI5 in this blog post series:

• Introduction (current) 


• Project setup


• Adding a BaseController


• OData Model Service wrapper


• Using Classes and State/Model Manager


• Final part

The first community call about TypeScript support:

 

You can view the following video:



Or if you prefer reading, continue reading the blog post:

What is typescript in UI5

Let me start from the beginning, what is Typescript? Most of you have probably already heard about TypeScript before. TypeScript exists already for a while and is nothing new in the JavaScript world. Nevertheless, the framework or library that you use must support TypeScript, which was not to case for UI5 until the beginning of this year.

TypeScript is a superset of JavaScript which adds optional static typing to the language. It comes with a compiler to convert TypeScript code to JavaScript and run it everywhere JavaScript runs, browser, NodeJS, … . The biggest change is that TypeScript comes with Types. When you are new to JavaScript or UI5, this will be closer to other languages like Java, C# and somehow even ABAP 😊 . At the same time this makes it harder to develop generic code like you might be used to in JavaScript because it is untyped.

The goal of TypeScript is to provider better integration in your IDE to help you catch errors earlier.

If this doesn’t make sense to you, it is already explained on many places before:

• Official website: https://www.typescriptlang.org/


• Wikipedia: https://en.wikipedia.org/wiki/TypeScript


• stack overflow: https://stackoverflow.com/questions/12694530/what-is-typescript-and-why-would-i-use-it-in-place-of-j...

You can also give it a try yourself: https://www.typescriptlang.org/play

 

What is TypeScript in UI5? UI5 is a framework/SDK which we use to create UI5 apps, also named as Fiori apps. When you are using a framework, library or SDK for building apps, this should be built in TypeScript or provide definition files (d.ts) to support TypeScript. Since April this year, SAP provides TypeScript definition files for UI5. Those files allow us to use TypeScript in UI5!

UI5 is using the JSDoc information to generate the TS definition files. More details on TypeScript in UI5 is already explained very well by Peter Muessig: https://blogs.sap.com/2021/07/01/getting-started-with-typescript-for-ui5-application-development/

Peter also explained TypeScript support for UI5 in this community call: https://www.youtube.com/watch?v=OuNMb9kPhTg&list=PLpQebylHrdh5XQts8bKoMUKexpun_YPvU

And it also at UI5ers live: https://www.youtube.com/watch?v=0notj9PPTho

 

How to get started

For really getting started with your first TypeScript in UI5 project it is recommended to learn TypeScript. TypeScript in general is not complex and easy to learn, the basics are very common to any other language. Writing more complex code the way you are used to in JavaScript might be harder in TypeScript because it requires to use types all the time. The concept of Generic types might help you in that case which I find very important to understand when developing in TypeScript.

For that, it might be good to first follow some tutorials or a course. A great course that I recommend is “Understanding TypeScript - 2021 Edition” on Udemy: https://www.udemy.com/share/1013yQ3@f94FYMaIwd5er1akskrQdHTYpQrDKdDpWvYqWvyqxTEk6SSnbyoxDXlYhBbxxMkI...

You can also learn much from the already provided examples by SAP. When I start on the first project with TypeScript, I only had this repo as a reference: https://github.com/SAP-samples/ui5-cap-event-app/tree/typescript/packages/ui-form

In the meanwhile, you also have this HelloWorld example: https://github.com/SAP-samples/ui5-typescript-helloworld

Peter Muessig already shared a great blog post on how to get started with TypeScript in UI5: https://blogs.sap.com/2021/07/01/getting-started-with-typescript-for-ui5-application-development/

On top of that we have the session from Andreaz Kunz at UI5con who gave a great introduction on how TypeScript can be used in UI5 at UI5con 2021 on AIR. You can find the replay on youtube: https://www.youtube.com/watch?v=5jfHNKQ48w8

With all mentioned resources I was able to start my first UI5 project with TypeScript.

One more thing you need to know before starting, SAP Web IDE is not an option when using TypeScript. It even gets better; you can choose any IDE you like! With the UI5 tooling + Fiori tooling, most of the tooling is made available via NPM which is independent from your IDE. With the Fiori tooling also comes generators/templates as vscode plugins, this is only available for IDE’s that support vscode plugins.

For that reason, I prefer to use VScode for UI5 TypeScript projects. It can happen that it’s not easy to get everything installed on your computer because of company policies. In that case, Business Application Studio is a good alternative. It comes with a preinstalled setup ready for your UI5 developments.

Lena Hammerer already posted a great blog post on how to setup your VSCode environment for UI5: https://blogs.sap.com/2021/10/15/getting-ready-for-ui5-development-with-visual-studio-code/

This tooling topic reminds me of a funny meme I noticed on twitter:

Credits to: https://twitter.com/mianbsp

 

When I started, there was no TypeScript template available yet. Because of this I had to convert the generated template to a TypeScript version. In the meanwhile, there is not yet an official generator/template for UI5 Typescript but you have a typescript template in the easy UI5 yeoman generator: https://github.com/SAP/generator-easy-ui5 (This is based on the HelloWorld example)

 

Challenges

Starting with TypeScript in UI5 came with some challenges:

• We have a template available thanks to easy UI5 but it’s still quite empty. It comes with the required configuration for TypeScript which is already great! Still, we don’t have templates for master-detail, worklist and so on. We also miss some basic objects like a BaseController or formatters. Maybe we have been spoiled in the past with the available templates 😊


• Missing some best-practices/documentation. We have the examples and all other resources I mentioned above, but no official documentation.


• Not all UI5 objects have a Type in the definition files. Many objects are simply returned as any. You will have to create a type for it and cast it.


• Integration of third-party libraries was not yet possible in the beginning. Thanks to Volker I noticed the example of Peter Muessig for this: https://github.com/ui5-community/ui5-ts-shim-showcase


• Integration of UI5 libraries, your library must be in TypeScript or provide TS definition files. We did not really have a tool in the beginning so reusing our libraries with reusable code was not really an option. In the meanwhile, Maricio mad a UI5 task to generate TS definition files for UI5 libraries: https://www.npmjs.com/package/ui5-task-dts-generator


• How to work with types? How to get the most out of TypeScript and not just simply make everything of type any?


• How can we adapt our project structure and way of developing in JavaScript with TypeScript?

With lack of examples and recommendation it was not easy.

In the end I had to convert many of my reusable code to make it TypeScript compatible. It also forced us to do things slightly different compared we are used to do.

In the next coming blog posts, I will share code snippets and how to setup your project to fully benefit from typescript!