My first experience with TypeScript in UI5 – Introduction
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
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
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 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)
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?
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!
Thanks for the great roundup, Wouter, and also for your TechEd session, where you explained everything very well!
One hint from UI5 side: on https://sap.github.io/ui5-typescript we have set up the central entry point for all documentation and examples related to TypeScript and UI5. Maybe this will help finding one or the other resource which was missed so far.
Some new tools and samples around support for custom control development in TypeScript (in apps and as libraries) will be published very soon. I can update you here, then. One of the next UI5ers live sessions will also come with an overall TypeScript update.
When I wrote "very soon", I meant it. 🙂
https://sap.github.io/ui5-typescript#how-to-develop-custom-controls-in-typescript has now links to documentation, a sample project and a new tool that helps with control development.
Development of control libraries is planned to be demonstrated at https://github.com/SAP-samples/ui5-typescript-control-library soon. (note how I didn't write "very soon"?) Awaiting an approval, so it could be a matter of days.
Now the control library sample is also public: https://github.com/SAP-samples/ui5-typescript-control-library
Great introduction Wouter, I enjoyed the video version as well! I've been recently exploring TypeScript within UI5 myself, so this is very relatable as I faced the same challenges you describe. Looking forward to the next posts in the series 😊