View on GitHub

UI5 & TypeScript

The central entry point for everything TypeScript-related in SAPUI5/OpenUI5

UI5-TypeScript

This page provides an overview of all official TypeScript-related resources in the UI5 world.

Topics

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:

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 above 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:

  1. 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.
  2. 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:

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:

Before reporting an issue, please check the list of known issues.

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.
To keep track of any significant changes, observe the Release Notes.

Where can I find release notes or news about changes in the UI5 type definitions?

In short: here.
There is not one specific changelog for the type definitions, as they are influenced by changes in three different areas:

  1. the JSDoc across all UI5 code, which is the source of API information
  2. the UI5 JSDoc parser (extending the original JSDoc parser), which parses and processes the JSDoc
  3. the UI5 type generator, which turns the processed API information into TypeScript type definitions

The former two are included in the general UI5 “What’s New” and Change Log (which contain also many changes not affecting the type definitions, though).
The type generator, on the other hand, influences how the types are generated and can hence have a huge impact as well, independently of any UI5 changes. It is currently not developed in this repository, but for the time being we list any significant or even breaking changes on the release notes page (also ones originating from the UI5 JSDoc or parser).

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 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 on the status and the release notes for significant changes.

Support

The type definitions and tools for TypeScript support are provided as-is. For reporting issues, please see the respective section above.

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.

Legal Statement / Impressum

Trademark Notice