UI5 Tooling: a modern development experience for UI5!

Introduction

On April 1^st I talked about the “UI5 Tooling – a modern CLI-based development experience” in a SAP Community call. Besides explaining the UI5 Tooling in general, I showed how to grab a UI5 application from SAP Web IDE and how to configure it to run it locally with the UI5 Tooling.

The slides can be found here: https://www.slideshare.net/PeterMuessig1/ui5-tooling-ecosystem

This blog explains the individual steps to you to make the same experience.

Background

Approximately one year ago, the SAP Web IDE switched to use the UI5 Tooling to build UI5 projects. Today, all UI5 projects created with the SAP Web IDE include the proper configuration to use the UI5 Tooling for the build process. As the SAP Web IDE comes with an integrated preview based on the HTML5 runtime, the development server of the UI5 Tooling is not required here. But when grabbing projects from SAP Web IDE and running them locally, the development server is mandatory. Compared to the HTML5 runtime, the UI5 Tooling just provides access to the UI5 resources and doesn’t provide a proxy to access backend services. But without using mockdata, such a proxy is needed.

Extensibility

Last year, at the UI5con at SAP, Volker Buzek approached me and asked for a proxy as part of the UI5 Tooling. I asked Volker what kind of proxy he needs: a simple proxy, an AppRouter, a HTML5 runtime router, …? All proxies are somehow specific to their platform, coming with different configurations and IMO the UI5 Tooling team will never satisfy all demands. But I offered Volker to help him to write a proxy and to get started with the extensibility of the UI5 Tooling demonstrating the task and middleware extensibility. This was the kick-start for the UI5 Ecosystem Showcase repository – a repository to demonstrate how easy the UI5 Tooling can be enhanced with own custom tasks and middlewares.

UI5 Ecosystem Showcase

The UI5 Ecosystem Showcase repository contains several ideas to improve the UI5 development experience by leveraging open-source tools. The extensibility concept of the UI5 Tooling allows to integrate those tools easily. So, the repository step by step grow to integrate custom tasks to e.g. transpile ES6 to ES5 code by using Babel or to provide custom middlewares to get a livereload of the browser in case of changes in the project sources as well as a simple HTTP proxy to tunnel backend services. All those features can be combined and used for UI5 development to come to a modern development experience!

A real-life example: Local UI5 development with the UI5 Tooling

Now, let’s start with some hands-on and let’s make our hands dirty. Every UI5 developer should make this experience to feel how good local UI5 development can be already today. Keep in mind, the SAP Web IDE still provides a lot of value and benefits with its wizards, tools and integration into various SAP platforms. But IMO it should be seamlessly possible to either develop a UI5 application in SAP Web IDE and locally in e.g. Visual Studio Code together with the UI5 Tooling.

Prerequisites

Before we start, we need to ensure that our computer is setup properly. Node.js 10+ should be installed and configured properly.

Step 1: Create a UI5 application

In the first step we create a UI5 application based on the SAP Fiori Worklist Application template. This can be done either in SAP Web IDE by using the template wizard or with the Yeoman generator for SAPUI5 templates.

Option A) Using the SAP Web IDE template wizard

Follow these steps to create an SAP Fiori Worklist application:

1. Open SAP Web IDE
2. File > New > Project from template
3. Select environment “Neo” (as this affects the datasource URL relevant for the proxy)
4. Select category “SAP Fiori Application”
5. Select template “SAP Fiori Worklist Application”
6. Enter your project name, title and namespace
7. In the data connection step (prerequisite: setup a destination to Northwind OData Services first), select the Northwind OData Services as “Service URL”, use the “Relative URL”: /V2/Northwind/Northwind.svc/) and press “Test”.
8. In the template customization step, select the “Standalone App” application type and Object Collection: Customers, Object Collection ID: CustomerID, Object Title: CompanyName.
9. Finish

After the UI5 application has been created, select it in the project explorer, export it from SAP Web IDE and unzip it locally in your file system.

Option B) Using the Yeoman generator for SAPUI5 templates

Follow these steps to create an SAP Fiori Worklist application:

1. Install the Yeoman generator via:

   npm install -g yo @sapui5/generator-sapui5-templates

2. Create an empty folder and switch to it
3. Run:

   yo @sapui5/sapui5-templates

4. Enter module name and module namespace
5. Select template “SAP Fiori Worklist Application”
6. Enter title and description
7. Select “Standalone App”
8. As Service Base URI enter: https://services.odata.org/V2/Northwind/Northwind.svc/
9. As Datasource URL enter: /svc/
10. In the following steps enter Object Collection: Customers, Object Collection ID: CustomerID, Object Title: CompanyName, the rest leave empty.

Now your UI5 application has been created in your local file system.

Step 2: Updating the project dependencies

After following one of the options of the previous step, we should validate whether we need to update the project dependencies of the created UI5 application. To update the project dependencies, we can use the open-source tool npm-check-updates. This tool can be installed via:

npm install -g npm-check-updates

After the installation of the tool, we can run:

ncu -u

to upgrade the project dependencies in the package.json. Once the project dependencies are upgraded run:

npm install

to prepare the project for a first run. The project can be started with the command:

npx ui5 serve -o index.html

Although the development server starts technically, there are a few things missing to make the UI5 application to run properly (e.g. the SAPUI5 resources).

Step 3: Setting up a proxy to access the SAPUI5 resources

To access the SAPUI5 resources in the UI5 application we can simply use the simple proxy middleware from the UI5 Ecosystem Showcase. I can be installed as a dev dependency by running the following command:

npm install ui5-middleware-simpleproxy --save-dev

(if the project has been generated with Yeoman the simple proxy middleware is already installed).

Option A) UI5 application created by SAP Web IDE

For the project created with the SAP Web IDE, we need to add the ui5-middleware-simpleproxy as ui5/dependencies in the package.json:

{
  […]
  "ui5": {
    "dependencies": [
      "ui5-middleware-simpleproxy"
    ]
  },
  […]
}

Afterwards we need to open the ui5.yaml and add the following configuration at the end:

server:
  customMiddleware:
  - name: ui5-middleware-simpleproxy
    mountPath: /resources/
    afterMiddleware: compression
    configuration:
      baseUri: https://sapui5.hana.ondemand.com/resources/

This configuration will ensure that all requests to /resources/ will be proxied to https://sapui5.hana.ondemand.com/resources/.

Option B) UI5 application created by Yeoman generator

If the project has been created with the Yeoman template, we need to add the following configuration to the server/customMiddleware section in the ui5.yaml (just include the first middleware entry and put it before the already existing ui5-middleware-simpleproxy entry):

server:
  customMiddleware:
  - name: ui5-middleware-simpleproxy
    mountPath: /resources/
    afterMiddleware: compression
    configuration:
      baseUri: https://sapui5.hana.ondemand.com/resources/
  - name: ui5-middleware-simpleproxy
    mountPath: /proxy/

But be careful with yaml – the indentation is pretty important.

Now the application should start properly and load the SAPUI5 resources via the proxy middleware. But still the UI5 application created with SAP Web IDE will fail to load its data since there is no proxy configured which tunnels the requests to the Northwind OData Service.

Step 4: Setting up a proxy to tunnel the Northwind OData Service

This step is only needed for the project created by SAP Web IDE. The project created with the Yeoman generator already includes the configuration to connect to the Northwind OData Service.

In the project created with SAP Web IDE open the ui5.yaml and add the following configuration (just include the second entry for the OData service into the ui5.yaml):

server:
  customMiddleware:
  - name: ui5-middleware-simpleproxy
    mountPath: /resources/
    afterMiddleware: compression
    configuration:
      baseUri: https://sapui5.hana.ondemand.com/resources/
  - name: ui5-middleware-simpleproxy
    mountPath: /Northwind/V2/Northwind/Northwind.svc/
    afterMiddleware: compression
    configuration:
      baseUri: https://services.odata.org/V2/Northwind/Northwind.svc/

This configuration ensures to proxy the request to /Northwind/V2/Northwind/Northwind.svc/ to https://services.odata.org/V2/Northwind/Northwind.svc/.

Step 5: Validate that the project runs locally

Now it’s the time to validate that the project starts locally. To ensure that all project dependencies are installed, just run:

npm install

in the UI5 application again. Now you can start the development server by running:

npx ui5 serve -o index.html

Now you should see the application running and the data being loaded from the Northwind OData Service.

Step 6: Add the livereload middleware

The livereload middleware is watching to changes of the sources in the file system. Once a source file has been modified the livereload middleware reloads the browser. Add the livereload middleware with the following command:

npm install ui5-middleware-livereload --save-dev

Afterwards in the package.json ensure to list the ui5-middleware-livereload in the ui5/dependencies (just add the last entry):

{
  […]
  "ui5": {
    "dependencies": [
      "@sap/ui5-builder-webide-extension",
      "ui5-middleware-simpleproxy",
      "ui5-middleware-livereload"
    ]
  },
  […]
}

The first entry @sapui5/ui5-builder-webide-extension is only present when you started to create the project with the SAP Web IDE. Afterwards, in the ui5.yaml just include the livereload middleware:

server:
  customMiddleware:
  […]
  - name: ui5-middleware-livereload
    afterMiddleware: compression
    configuration:
      extraExts: "xml,json,properties"
      path: "webapp"

Now you can start your development server again with the command:

npx ui5 serve -o index.html

When you modify your sources and immediately get an update in your running application (remark: in case you face issues with livereload, maybe your html page was cached before, just ensure to reload the html page properly).

Step 7: Use the UI5 Tooling 2.0 to consume SAPUI5 from NPM

With the availability of SAPUI5 on NPM and the UI5 Tooling 2.0 we finally can consume SAPUI5 as dependencies. Therefore, the UI5 Tooling implemented an own frontend package manager to overcome the versioning issue in the SAPUI5 distribution layer. The details and reasoning behind this decision can be read in the UI5ers Buzz #49: The UI5 Tooling and SAPUI5 – The Next Step.

Let’s experience it live – we now remove the ui5-middleware-simpleproxy and migrate to specVersion: ‘2.0’ in the ui5.yaml:

specVersion: '2.0'
[…]
server:
  customMiddleware:
  - name: ui5-middleware-simpleproxy
    mountPath: /Northwind/V2/Northwind/Northwind.svc/
    afterMiddleware: compression
    configuration:
      baseUri: https://services.odata.org/V2/Northwind/Northwind.svc/
  - name: ui5-middleware-livereload
    afterMiddleware: compression
    configuration:
      extraExts: "xml,json,properties"
      path: "webapp"

Next we add a framework dependency to SAPUI5 by running the following command:

npx ui5 use sapui5@latest

Now we can include the required libraries with the following command:

npx ui5 add sap.ui.core sap.m sap.f themelib_sap_fiori_3

This will create the following section at the end of the ui5.yaml:

specVersion: '2.0'
[…]
framework:
  name: SAPUI5
  version: "1.76.1"
  libraries:
    - name: sap.f
    - name: sap.m
    - name: sap.ui.core
    - name: themelib_sap_fiori_3

In case of the project has been created with the Yeoman template, open the index.html and change the bootstrap URL from “https://sapui5.hana.ondemand.com/resources/sap-ui-core.js” to “resources/sap-ui-core.js”. After starting the development server with:

npx ui5 serve -o index.html

the UI5 resources are loaded from the local framework dependencies configured in the ui5.yaml.

Step 8: Explore the UI5 Ecosystem Showcase repository and add more middlewares or tasks

Now you can go ahead and take a look into the UI5 Ecosystem Showcase repository to include additional tasks and middlewares into the ui5.yaml of your project. If you want to use modern JavaScript language features, I would recommend you to take a look into the transpile task and the livetranspile middleware. If you have ideas for additional custom tasks or custom middlewares please consider to share them with the UI5 community.

What now

Get familar with the UI5 Tooling 2.0 and the new capabilities to consume SAPUI5 dependencies from NPM. Play around with the available tasks and middlewares and try to combine them for your local UI5 development.

Help us to spread the word and share with other UI5 developers that you can also have a great and modern development experience for UI5 development.

Related links

• UI5 Evolution: The Build and Development Tooling
• Introducing the UI5 Tooling for SAPUI5 Projects
• The UI5 Tooling and SAPUI5
• Q/A for the SAP Community call about the UI5 Tooling