SAP / ui5-typescript

Tooling to enable TypeScript support in SAPUI5/OpenUI5 projects

🚧 Work in Progress! 🚧

UI5-TypeScript

UI5-TypeScript is an npm mono-repo that contains tooling to support TypeScript in SAPUI5 and OpenUI5 Projects. This tooling can enable:

• Better IDE integration for UI5 projects (e.g content assist).
• Using TypeScript compiler to perform type checks on UI5 application code.
• More easily implementing UI5 applications and controls in TypeScript thus enjoying the general benefits of TypeScript.

Learn more about the general benefits of TypeScript here:

• https://stackoverflow.com/a/35048303
• https://channel9.msdn.com/posts/Anders-Hejlsberg-Introducing-TypeScript

It currently contains two public packages:

• @ui5/dts-generator A low level generator which transforms the UI5 api.json format to TypeScript definition (*.d.ts) file format.
  NOTE: the sources in this repository and also the package released at npm represent an outdated version of the generator tool, not the one used for the new improved TypeScript definition files which are released since June 2021. The code of the new generator version is planned to be released here later as well.

• @ui5/ts-interface-generator A tool supporting control development in TypeScript. It is used at development time and generates type definitions for the control API methods which are only created at runtime by the UI5 framework.

How to obtain the UI5 TypeScript signatures?

The UI5 type signatures are created and published as part of the UI5 build process. There are two flavors of the type definitions right now:

1. the legacy flavor which defines all entities with their global names, like sap.m.Button. As using globals is discouraged, using this flavor should be avoided. The definition packages are named ts-types.
2. the "ES modules" flavor which defines ES6-style module names for the entities. These definition support using modern JavaScript syntax with ES modules and classes, but require an additional transformation step, which can be run together with the anyway required TypeScript compilation. These recommended definition packages are simply named types (used to be ts-types-esm before release 1.113).

Both flavors are available for SAPUI5 as well as OpenUI5.

Using the modern definitions for SAPUI5 as example, the type definitions can be obtained like this:

With npm

npm install @sapui5/types --save-dev

With Yarn

yarn add @sapui5/types --dev

Usage

To see the basic suggested project setup for TypeScript development with the new types packages, 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.

Overall, the best resource for using UI5 with TypeScript is https://sap.github.io/ui5-typescript.

See the demos directory for consumption examples of the legacy signatures.

Status

This project is in an experimental Beta State. Significant changes are likely to occur, including potential breaking changes. More details and why you should not be afraid of this can be found here.

Support

For issues caused by the generators please open issues on GitHub.
However, issues in the UI5 type definitions which are also present in the API documentation originate from the JSDoc comments in the original OpenUI5/SAPUI5 code, so please directly open an OpenUI5/SAPUI5 ticket in this case.

Contributing

See CONTRIBUTING.md.