This blog post introduces a new sample repository for a full stack TypeScript App built with the SAP Cloud Application Programming Model for Node.js (CAP) and SAPUI5. It covers a project intended for deployment on the SAP BTP Cloud Foundry environment that uses TypeScript. Find out how such a project is structured, run, built, and deployed!

With all the newly released content around TypeScript for UI5 development, I got curious: Is it time to try TypeScript in a UI project myself? Well, I kind of already gave the answer to this away by now. Still, when I initially started out with the idea, I didn’t know how TypeScript and I would get along and what this eventually would turn into. There were lots of lessons to be learned along the way, but in the end, TypeScript won me over. So I created a sample repository for a compact full stack app, where all JavaScript is replaced with TypeScript. 

Let’s look into some of the details. I’ll outline the project structure and focus on the expanded build process required when using TypeScript.

You can view the entire source code of the sample application on GitHub:
https://github.com/SAP-samples/btp-full-stack-typescript-app

Sample App Overview

Full Stack TypeScript App architecture

The diagram above showcases the different parts the Multitarget Application (MTA) consists of. In addition to the full stack app itself, some SAP BTP services are used, SAP Hana Cloud as database and a simple standalone approuter. All of this lives in the Cloud Foundry environment. A quick summary of what each part does:

• SAPUI5 App: a freestyle UI5 app serves as the frontend
• CAP Node.js App: a backend OData V4 service to provide and manage data
• SAP Hana Cloud: database to store data
• User Account and Authentication service (UAA): OAuth 2.0 server to authenticate and grant access via user roles
• SAP Destination service: provides destinations of services like the CAP Node.js app for the Application Router
• SAP HTML5 Application Repository service: contains the SAPUI5 frontend app
• Application Router: single entry point for the application

The project evolves around a simple lecture schedule scenario. Upon that, the data model consists of Courses, Professors, Rooms, and Lectures. Every lecture has a defined start and end time and is held in one of the rooms. An association to a specific course as well as the lecturing professor is possible. This data is now provided through an OData V4 service built with CAP for Node.js. A dedicated service handler implements a custom action, provides validation when creating a new entry, and adds a non-persistent virtual property. Access to the service is restricted via two different user roles: viewer and admin. Only users with the admin role can change the data. All viewers can read the entries.

Lecture Service Entity Data Model

The data for the lecture schedule is displayed with a freestyle SAPUI5 app. Here two different planning calendars are used to display the lectures over time. Filtering for a professor is possible. Creating, modifying, and deleting entries are shown as options for users with the admin role. This can be checked due to expanding the standalone approuter with an additional route to provide information about the user currently accessing the app.

Development closer look – Build Process

Now it’s time to address how the development with TypeScript differs from regular JavaScript coding. 

TypeScript is a superset of JavaScript developed by Microsoft. Essentially it is JavaScript with syntax for types. The idea is to make JavaScript development more efficient by catching mistakes early with the help of its type system. JavaScript is a loosely typed language, which can be a blessing and a curse at the same time. TypeScript, on the other hand, is optionally strongly typed and therefore helps to catch type errors. What would have resulted in a runtime error with JavaScript can be found beforehand with TypeScript static type checking. Moreover, TypeScript brings future JavaScript to coding by enabling features of ES Next for current JavaScript engines.

Difference between TypeScript and JavaScript

TypeScript files, however, cannot be executed. They need to be compiled back to JavaScript before running the code. The build process can be integrated with common build tools, and a linter adds even more options for code checking. Code linting ties right into one of my favorite TypeScript features – enhanced editor integration like code completion.

Some adjustments to the build parameters related to TypeScript are required to build an MTA for Cloud Foundry deployment. The build process needs to include a TypeScript compilation step since the generated JavaScript will be run on Cloud Foundry in the end. Regardless, the actual mta.yaml file does not differ from a regular MTA project. All that changes is the content of the already included build scripts.

CAP Node.js Service using TypeScript

There are only a few things to note when using TypeScript with CAP. First, a tsconfig.json file at the project’s root is needed to define the compiler options. A standard Node.js configuration is sufficient. This file also declares which TypeScript sources to include (everything in /srv here) and where to put the compiled files. Now you are ready to start writing TypeScript instead of JavaScript. The type declarations conveniently come with the @sap/cds package, so no additional installs are needed. One of TypeScript’s great features is the enhanced editor integration, enabling code assistance with type declarations. This is not limited to pure TypeScript development – they can also enable IntelliSense for JavaScript in an editor like Visual Studio Code. 

Code assistance enabled through @sap/cds type definitions

For the limited scope of this sample application, the interfaces to make the CDS model available in TypeScript are manually created. There are community tools to generate types based on CDS definitions to facilitate the process. You can look at this blog post to find out more: Taking CAP to the next level – with TypeScript

Things get more challenging when it comes to the familiar watch, run and build commands. The sample project includes several scripts for TypeScript adjusted commands:

 "start-service:ts": "cds-ts run --with-mocks --in-memory",
 "watch-service:ts": "cds-ts watch --open",
 "build:cf": "npm run build:cds && npm run cleanup:ts && npm run build:ts",
 "build:ts": "tsc",
 "build:cds": "cds build --production",
 "cleanup:ts": "npx rimraf gen/srv/srv/**/*.ts",
  ...

For development, cds-ts is available to spare us from compiling TypeScript to JavaScript every time we want to run the app. The command utilizes ts-node instead of the regular node engine. This is also applicable to running in watch mode.

However, this should not be used for production due to performance reasons. Therefore TypeScript code needs to be compiled when building the app for production. The build process now includes a regular cds build, removing the unnecessary TypeScript files from the output and compiling all TypeScript to JavaScript files, which are then added to the build result instead.

SAPUI5 Freestyle App using TypeScript

ForUI5 development with TypeScript, a variety of valuable resources is already available and gradually expanded:

Generating a new project with the help of the Yeoman Easy UI5 Generator, using the ui5-typescript-helloworld app as a template, or following the step-by-step guide are all great ways to achieve a setup and structure similar to the new Full Stack TypeScript App sample project.

In this approach, Babel is used for compiling TypeScript code to modern ES6 JavaScript and ultimately to classic UI5 code. For this purpose, the project utilized the Babel plugin transform UI5 from Ryan Murphy and a .babelrc.json file for configuration. This comes with the advantage of enabling modern JavaScript features like classes, modules, promises, and async/await for the UI5 coding. 

Therefore, the final build process includes this transpile step with Babel creating a webapp folder with regular UI5 JavaScript code and afterward a ui5 build to bundle the code in a /dist folder.

UI5 resources processing flow

The sample app includes several scripts to watch, run and build the SAPUI5 app taking care of TypeScript handling. 

 "build:cf": "npm run build:ts && npm run build:ui5:cf",
 "build:ui5:cf": "ui5 build preload --clean-dest --config ui5-deploy.yaml --include-task=generateManifestBundle generateCachebusterInfo",
 "build": "npm-run-all build:ts build:ui5",
 "build:ts": "babel src --out-dir webapp --source-maps inline --extensions \".ts,.js\" --copy-files",
 "build:ui5": "ui5 build --clean-dest",
 "start": "npm-run-all --parallel watch:ts start:ui5",
 "watch:ts": "babel src --out-dir webapp --source-maps inline --extensions \".ts,.js\" --copy-files --watch",
 "start:ui5": "ui5 serve --port 8080 -o index.html",
 ...

Round off

Aiming to cover every possible piece of JavaScript, the approuter extension is also implemented in TypeScript. Unfortunately, no type definitions are provided for the @sap/approuter package at the time of writing. Nevertheless, this does not rule out using TypeScript in general since, technically, all correct JavaScript code is naturally valid TypeScript. It only limits the benefit of doing so. This reveals another TypeScript benefit, which comes into play when gradually converting a JavaScript code basis to TypeScript.

Next Steps

Take a look at the sample repository for the Full Stack TypeScript App on GitHub and try out TypeScript for Cloud development yourself!

1. Clone the project from GitHub:

   git clone https://github.com/SAP-samples/btp-full-stack-typescript-app.git
   cd btp-full-stack-typescript-app

2. Install the dependencies:

   npm install
   

3. Run the app locally:

   npm run start-service:ts