Getting Started with TypeScript for UI5 Application Development
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.
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.