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.

To get started quickly with a hands-on example, you can jump into the UI5 TypeScript Tutorial right away (or watch the video walking you through this tutorial), or, for a more structured approach, follow the learning guidance outlined here.

If your development is based on SAP Fiori Elements, using the SAP Fiori tools, and you are less interested in the basic technical setup and general TypeScript coding introduction, then this workshop is for you. A presentation recording and resulting repository demonstrates important aspects in a more compact way.

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 to JavaScript is needed, which basically strips away the type information.

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 compiler and the editors 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. The fastest way to get started are two Yeoman-/easy-ui5-based TypeScript app templates:

Exercises 0 and 1 of the UI5 TypeScript Tutorial walk you through using the simple app template and demonstrate how to continue from there.

If you prefer understanding how everything works under the hood in this template, you can create the setup in few minutes on your own. A detailed step-by-step guide shows how to create the “ui5-typescript-helloworld” project, which is the same as what you get using the template.

How can I get an end-to-end hands-on impression of creating and developing a UI5 app in TypeScript?

There is a 2-hours tutorial, starting from scratch using an app template, extending the resulting app, and covering further topics later on, like control development, integrating third-party libraries from npm, and testing.
A very comprehensive look at all the important concepts in UI5 and how they are being used in TypeScript can be found in the TypeScript Walkthrough.

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?

Exercise 5 of the TypeScript tutorial is all about control development. Furthermore, 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.
Control development 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 4 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?

How to write tests is documented in exercise 6 of the TypeScript tutorial and in the testing-related sections of the “Hello World” sample app. While using qunit in TypeScript is straightforward, the OPA APIs cause a few difficulties in TypeScript, which we avoid using a simplified suggestion for how to write the OPA pages and journeys.

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 (simply “types”, used to be named “ts-types-esm” before release 1.113) 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 currently four different type definition packages:

Plus for older versions before 1.113 (plus a few releases afterwards), the “types” ones were available under a different name:

The “new OpenUI5” types are additionally provided at 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/types, 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 and the ui5-tooling-transpile task and middleware nicely integrates all TypeScript transpilation related tasks into the UI5 build tooling, so you are not bothered with configuring the Babel transpiler.

Where to report issues?

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

Are the type definitions ready for productive use?

Yes, starting with version 1.116.0 (mid July 2023) they are.

We encourage you to use UI5 with TypeScript for an improved development efficiency and experience. TypeScript itself keeps evolving and we try to further improve the UI5 type definitions, so there could be potential incompatible changes between versions of the type definitions. However, such incompatibilities would only affect the compilation of your code but will not cause runtime issues in your application. Plus, there are various ways to easily deal with them: you can, for example, simply keep using the previous version of the UI5 type definitions together with an updated UI5 runtime.
To keep track of any significant changes, observe the Release Notes.

Versions prior to 1.116.0 are in “experimental beta” state, which means an increased likelyhood of issues and of incompatibilities with upgrades. However, the list of known such changes is available in the Release Notes, so you know what is ahead on the road to version 1.116. Note that “non-beta” releases do not come with a 100% compatibility guarantee either.
Find all the details here.

If you are bound to a UI5 runtime version lower than 1.116.0, you can still consider using it with UI5 types 1.116.0 or later. You can definitely encounter issues such as APIs being offered by TypeScript which do not actually exist yet in your runtime version of UI5, but this is in fact not different at all from regular JavaScript development, where - when using the newest version of the API documentation you would also have to check the “since” annotation of APIs before using them. And of course such a new API would be noticed as soon as the code is executed. There is no support for this usage, but it could improve the usage experience a lot, as the types have become better and better.

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

Where can I find the types for UI5 2.0?

The type definitions for the OpenUI5 2.0 preview are published as part of its nightly release at https://sdk.openui5.org/nightly/2/-/types.tgz. The ui5-2.0 branch of the ui5-typescript-helloworld sample app demonstrates how these type definitions can be used for trying them: simply reference the types package in package.json via URL like

   "@types/openui5": "https://sdk.openui5.org/nightly/2/-/types.tgz"

When you are newly adding the types, the following command will create this entry:

   npm install --save-dev https://sdk.openui5.org/nightly/2/-/types.tgz

The difference of this package to the 1.x types is mainly that the deprecated methods/classes/libraries of UI5 1.x have been removed.
The SAPUI5 2.x types are not available yet.

What is the future roadmap for TypeScript in UI5?

The current focus is working on an overall improvement of the TypeScript usage experience, so we are reacting on feedback and issue reports.

What if I have further questions?

For more specific questions, please see the FAQ. If it does not contain an answer, please try asking the community or in cases that are interesting for a wider audience and go beyond a specific issue with your code open an issue in the GitHub issue tracker.

Other Deliverables

Other Resources

While the already mentioned UI5 TypeScript tutorial is the best starting point and its recording also comes with a short introduction to TypeScript and how it is transpiled in UI5 apps, there are other not yet mentioned resources which provide partly complementary content:

Status

Starting with version 1.116.0, the UI5 type definitions are provided for general use.

We encourage you to use UI5 with TypeScript for an improved development efficiency and experience. TypeScript itself keeps evolving and we try to further improve the UI5 type definitions, so there could be potential incompatible changes between versions of the type definitions. However, such incompatibilities would only affect the compilation of your code but will not cause runtime issues in your application. Plus, there are various ways to easily deal with them: you can, for example, simply keep using the previous version of the UI5 type definitions together with an updated UI5 runtime.
To keep track of any significant changes, observe the Release Notes.

Lower versions are in an experimental Beta State and significant changes on the way to 1.116.0 can be looked up in the release notes.

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) 2021-2024 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