UI5-TypeScript
This page provides an overview of all official TypeScript-related resources in the UI5 world.
Topics
- What is TypeScript about?
- What is the overall approach for using TypeScript in UI5 applications?
- How can I get an end-to-end hands-on impression of creating and developing an app?
- How to set up a new UI5 app for TypeScript development?
- How to convert an existing UI5 app to TypeScript?
- How to develop custom controls in TypeScript?
- How to test in TypeScript?
- How to use third-party libraries from npm in UI5 apps?
- How to profit from TypeScript even when doing plain JavaScript development?
- What are the TypeScript projects and releases provided by the UI5 development team?
- Where to report issues? What is the support status?
- What does it mean that the type definitions are “in experimental beta state”?
- What is the future roadmap for TypeScript in UI5?
What is TypeScript about?
TypeScript is an extension of JavaScript for providing type information and helps by error detection through type checking and by providing code assist in many supporting code editors (code completion, inline documentation,…). Browsers cannot execute TypeScript directly, a transpilation step is needed.
What is the overall approach for using TypeScript in UI5 applications?
The UI5 team publishes type definition files describing all the UI5 APIs and types. With the help of these definitions, the TypeScript tools can do their job and support writing UI5 apps in TypeScript (and even JavaScript). The “typescript” branch of the “ui5-cap-event-app” project gives an overview on UI5 code written in TypeScript, typical traps and topics like debugging.
How to set up a new UI5 app for TypeScript development?
By adding TypeScript and the UI5 type definitions as dev dependencies and setting up the transpilation step. This can be done in few minutes. The “ui5-typescript-helloworld” project can serve as copy template and provides a detailed step-by-step guide for setting up a TypeScript project.
To get started even faster, there are two Yeoman-/easy-ui5-based TypeScript app templates:
- A plain app template which contains one view and basic routing setup and is explained in this blog post
- A more comprehensive template including a FlexibleColumnLayout and allowing OData service and entity configuration within the wizard.
How can I get an end-to-end hands-on impression of creating and developing a UI5 app in TypeScript?
There is a 1-2-hours tutorial, starting from scratch using an app template, extending the resulting app, and also covering advanced topics later on, like control development and integrating third-party libraries from npm.
How to convert an existing UI5 app to TypeScript?
By doing most of the basic setup for TypeScript projects mentioned in the previous section and then following the four conversion steps briefly explained here. The detailed explanation how to enhance JavaScript applications with type information will also help because the process of tightening the checks and then fixing the resulting issues is the same - just use real TypeScript syntax instead of the JSDoc comments used in that guide!
How to develop custom controls in TypeScript?
There is documentation and sample code in the “custom-controls” branch of the Hello World application which explains how custom controls can be implemented in TypeScript within UI5 applications. It makes use of a tool for generating TypeScript interfaces for the control API which has been released via npm in alpha state. There is also a sample project that demonstrates how flull-fledged control libraries can be developed in TypeScript.
How to use third-party libraries from npm in UI5 apps?
Third-part libraries written for running in a browser environment can be easily used with very natural npm install
and import <moduleName> from 'dependencyName'
, resulting in code completion for those libraries and automatic transpiling into UI5’s own AMD-like module format.
Exercise 8 of the TypeScript tutorial shows how this is done, including the required setup of the ui5-tooling-modules extension for the UI5 tooling.
How to test in TypeScript?
This topic is not covered by samples and documentation yet. While using qunit is straightforward, the OPA APIs cause a few difficulties for which suitable solutions are still being worked on.
How to profit from TypeScript even when doing plain JavaScript development?
The “js-with-typescript-support” branch of the “ui5-cap-event-app” project contains an extensive guide how to add TypeScript-based benefits to an existing JavaScript app without actually switching to TypeScript development.
What are the TypeScript projects and releases provided by the UI5 development team?
Type definitions, samples, and various tools. In detail:
UI5 provides generated type definitions for the UI5 APIs, which let TypeScript understand all the involved types, so it can do its job. These definitions are provided both for OpenUI5 and for SAPUI5, in two different flavors each. The two flavors are:
- the legacy type definitions (“ts-types”) which allow the (discouraged!) usage of global objects like
sap.ui.Button
. They are not in our focus anymore and receive less support, but may still be needed for old application projects. - the new type definitions (“ts-types-esm”) which require the loading of dependencies as ES modules like
import Button from "sap/ui/Button"
, encouraging the use of modern JavaScript language features
Multiplied out, as result, there are four different type definition packages:
@openui5/ts-types-esm
(OpenUI5, new)@openui5/ts-types
(OpenUI5, legacy)@sapui5/ts-types-esm
(SAPUI5, new)@sapui5/ts-types
(SAPUI5, legacy)
The “new OpenUI5” types are additionally provided via npm as @types/openui5
via DefinitelyTyped because that’s the standard package name and place to share type definitions and easier to consume. These definition files are identical to @openui5/ts-types-esm
, but the versioning within a minor release and how the jQuery and QUnit types are referenced are slightly different (this should usually not be noticeable, though).
In addition to the samples, tutorials and template generator mentioned elsewhere in this document, in the “ui5-typescript” repository, the generator is developed, which creates the UI5 type definitions from the JavaScript implementation and JSDoc as well as other tools (NOTE: the generator code in the repository is currently outdated and will NOT produce the type definitions mentioned above!).
For control development in TypeScript, the control interface generator is provided.
Where to report issues?
Note that there is no official support guarantee, as the type definitions and code samples are provided “as-is”. However, it is in our interest to improve them and fix issues, so please report them:
- Issues in sample app code or documentation in the repositories linked above should be reported in the issue tracker of the respective GitHub repository.
- Issues within the type definition files can in general be reported in the issue tracker of the “ui5-typescript” project.
- However, when those issues are clearly coming from missing or wrong API documentation within OpenUI5, they can be reported as OpenUI5 issues. However, not all typing constructs of TypeScript can be expressed as JSDoc and converted to TypeScript by our generator (e.g. adding generics), so this should be mainly done for straightforward cases.
What does it mean that the type definitions are “in experimental beta state”?
It means that we might make changes which require adaptation on your side after consuming updated type definitions. But don’t let this statement make you shy away from using them! The needed adaptations will not be large and there isn’t going to be a lot of difference once the types are no longer called “beta”: there will be no 100% compatibility guarantee either. So basically the type definitions are ready for use.
Find all the details here.
What is the future roadmap for TypeScript in UI5?
The current focus is on working on the unfinished corners, like providing better support and guidance for topics like testing, but also on an overall improvement of the TypeScript usage experience, so we are reacting on feedback and issue reports.
Other Resources
- The UI5con 2021 session on TypeScript (recording available at YouTube) explains and demonstrates the overall approach for TypeScript and UI5
- Blog post by Volker Buzek: How to debug a CAP app with UI5 TypeScript UI component with VS Code
- Blog post series “My first experience with TypeScript in UI5” by Wouter Lemaire:
- Blog post by Lena Hammerer: Full Stack TypeScript App for Cloud Foundry – Sample Repository, including a complete sample app on GitHub, which uses the SAP Cloud Application Programming Model (CAP) for Node.js.
Status
The type definitions provided for UI5 are in an experimental Beta State. Significant changes can occur, including potential breaking changes. See the respective section above for details.
Support
Please open issues on GitHub.
Contributing
See CONTRIBUTING.md.
License
Copyright (c) 2022 SAP SE and ui5-typescript contributors.
This project is licensed under the Apache Software License, version 2.0 except as noted otherwise in the LICENSE file.
Legal Information & Privacy Statement
This site is hosted by GitHub Pages. Please see the GitHub Privacy Statement for any information how GitHub processes your personal data.
Please note the SAP terms of use.