Getting Started with TypeScript for UI5 Application Development
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.
From UI5con 2020 to UI5con 2021 we had two big challenges:
- Where do we get the proper TypeScript type definitions from?
- 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 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.
Every UI5 developer can now make his own experience with TypeScript and now it’s your time to do so.
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:
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
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:
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.
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.
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.
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!
Hi Carsten Kasper ,
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 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?
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...
Awesome!! Time to implement this in our team! Thanks Peter Muessig and team!
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).
Waaay later (on button press) I call my getters and setters
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).
Hi Peter !!
very good article, I am going to test typescript and this post will be helpful.
Thanks, Tulio. More is on the way… 😉
Since you asked for a feedback - I love the idea, but it looks like this approach is not allowing you to debug the built version (that you are supposedly suppling to the user) using the typescript code. when you ran npm run build , you are removing (intentionally?) the SRC folder and the maximum you get is the js.dbg file, which is not the original TS file, but translated JS file
yes, this is a known gap of the UI5 Tooling. The problem is that the resources are sanitized during the build process and the source maps are removed. With the next major release of the UI5 Tooling (v3) this should finally work.
i learned to handle TS a bit after your samples.. thanks for that!
Now i wanted to develop a bigger app for a customer with TS.
What can I say, reality has caught up with me.... 😉
It is a complete freestyle app.
After translating the first easier samples from the ui5 library from js to ts, what of cause took me some time. But still in the range. The big Value Help showed me that it is perhaps still too early to go this path.
I would be very interested to hear your point of view to this topic.
Isn't it to early to use TS for bigger customer projects?