Getting Started with TypeScript for UI5 Application Development

[pmuessig]

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 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.

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 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.