Technical Articles

Petar Skelin

April 1, 2019 5 minute read

The Fastest Way to Get Started with UI5 Web Components

2021 Update: Check out the newer blog post for an even faster way to start with UI5 Web Components – featuring automatic project creation and a production build with the same effortless development workflow.

It has been almost two months since the initial release of UI5 Web Components and the amount of positive feedback and interest has been phenomenal. There were however questions on how to most easily try out the brand new web components. It is not quite obvious how to consume a client side library from NPM and what setup is needed, especially for people with openui5 background where a CDN hosted version is available. People have been asking if there is a CDN based version of the web components and where to find it for a simple jquery-like usage.

A goal from the start of the project has been to follow modern best practices in shipping code and the UI5 web components are published as ES6 modules on NPM. The intention is for everyone who wants to use them to create their own bundle. This way, each application will get an optimal bundle containing only the web components that it uses. Compare this to a huge bundle containing all web components hosted on CDN, where most applications only use a small fraction (or even just one) of all web components in such a bundle. This is a big performance anti-pattern, but the usage via NPM is still non-intuitive for newcomers. This blog post aims to give you the easiest way for getting started with UI5 web components locally.

Prerequisites

You will need to download and install Node.js for all commands in this article.

Creating the project structure

Start up a terminal or command prompt and enter the following commands:

$ mkdir ui5-webcomponents-starter
$ cd ui5-webcomponents-starter
$ npm init -y

This will create an empty Node.js package that can consume the UI5 Web Components.
Next, add an html and javascript file containing the code for using UI5 Web Components.

src/index.html

<!DOCTYPE html>
<html>
<head>
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body>
    <ui5-button>Hello World</ui5-button><br><br>
    <ui5-textarea placeholder="Type some text" max-length="8" show-exceeded-text></ui5-textarea><br><br>
    <ui5-datepicker style="width: 180px"></ui5-datepicker><br><br>

    <script src="./main.js"></script>
</body>
</html>

In this file, we are using the ui5-button, ui5-textarea and ui5-datepicker to highlight four specific functionalities (described later) that you get for free when using UI5 web components. We also include a script tag for main.js which contains our application with the following content:

src/main.js

import "@ui5/webcomponents/dist/Button";
import "@ui5/webcomponents/dist/TextArea";
import "@ui5/webcomponents/dist/DatePicker";

To get the code of UI5 Web Components included in our project, we add ES6 Module import statements as described in the documentation of each component.

Installing UI5 Web Components as a project dependency

$ npm install @ui5/webcomponents --save

This command will download the source code of @ui5/webcomponents which are distributed as a Node.js package, and put it in the node_modules folder which will be necessary for the next step.

Starting a development server

By far the easiest way to start a development server is using the zero-configuration bundler Parcel.

You can install parcel globally (you only need to do this once).

$ npm install -g parcel

Then simply run parcel by pointing it to HTML file and voilà – open the URL shown in the output to see your first app running.

$ parcel src/index.html
Server running at http:// localhost:1234
  Built in 3.84s.

What happens under the hood is that parcel finds the main.js file included from our index.html, then follows the import statements it finds there and looks up the actual code of the UI5 web components from the node_modules folder. Then a single JS bundle is created (similar to a openui5 CDN hosted bundle) and a static web server is started so this dynamically generated bundle is served to the browser locally.

And that’s it. You can now import any UI5 web component like the <ui5-input> by following the instructions on its documentation page: ui5-input sample and API documentation. Just add the import inside src/main.js and use it either declaratively in index.html or programatically via the DOM APIs inside src/main.js. What is cool about using Parcel as a development server, is that it watches the source files for changes, automatically recreates the bundle and reloads the page on any change. You don’t event need to hit refresh in the browser.

Things to try out

All UI5 web components implement the standard themes supported by SAP products. The default theme is Fiori 3 (technical name sap_fiori_3), but you can also try out Belize and High Contrast Black by using a URL parameter:

Note: URLs work only if you are following the examples locally!

Belize: http://localhost:1234?sap-ui-theme=sap_belize

High Contrast Black: http://localhost:1234?sap-ui-theme=sap_belize_hcb

Note: The application is responsible for setting the background color of the document for HCB, so it can look as in the image above.

The other cool feature that is supported by all web components is internationalisation (or i18n). Any web component that shows text (like the “8 characters remaining” text of the `<ui5-textarea>`) or the day and month names of the date picker can also be changed by URL parameter. Go ahead and try German:

http://localhost:1234/?sap-ui-language=de

Next up, as part of the enterprise readiness of the web components, there is full support for right to left languages. You can try it out either by parameter, or automatically for languages that are RTL. Go ahead and open the datepicker in RTL mode:

http://localhost:1234/?sap-ui-rtl=true

Or try out Hebrew to see RTL being derived from the language:

http://localhost:1234/?sap-ui-language=he

Finally, there is a global configuration setting that makes the components appear more compact. This is good for desktop based applications that contain a lot of data on the screen, vs the default cozy appearance which is suitable for both mobile and desktop.

http://localhost:1234/?sap-ui-compactSize=true

What’s next

In a future blog post, we will explore how to create a production-ready bundle out of this starter project.

So stay tuned and happy coding. Don’t forget to check out the other available web components in the playground. Also give the project a star on github if you’d like to show your appreciation for our work so far. Feel free to open an issue on github for any problems, suggestions or improvements you might want to see.

14 Comments

You must be Logged on to comment or reply to a post.

Gregor Wolf

June 12, 2019 at 6:37 pm

Hi Petar,

thank you for this great quickstart guide. When I look into the network tab of the developer tools I still see requests going out to ui5.sap.com:

Is there a way to get everything local?

Best regards
Gregor

Petar Skelin

Blog Post Author

June 14, 2019 at 9:05 am

Hi Gregor,

There are some undocumented APIs to achieve this, but we have to make them more consistent and document them. At the moment, you can use the following imports to achieve local bundling:

// CLDR assets for datepicker and calendar
import "@ui5/webcomponents-base/src/cldr/CLDRAssets.js";
// icon fonts for components with icons
import sapIcons from "@ui5/webcomponents-core/dist/sap/ui/core/themes/base/fonts/SAP-icons.woff2"
import { setIconFontsLocations } from "@ui5/webcomponents-base/src/IconFonts.js";
setIconFontsLocations({woff2: sapIcons});
// message bundles for translatable texts
import "@ui5/webcomponents/dist/MessageBundleAssets.js";

In the mean time, I have created an issue for tracking the progress on improving the APIs and their documentation here:

https://github.com/SAP/ui5-webcomponents/issues/546

Thanks for reaching out 🙂

AMIT GUPTA

July 31, 2019 at 5:07 am

Hello Petar,

Thanks for the wonderful article for getting started with UI5 WebComponents . I am not able to see the language changing in TextArea like the “8 characters remaining” text of the `<ui5-textarea>` DatePicker is working fine and language is getting changed for DatePicker to German. Please check attached image for more information.

I have used below URL:

http://localhost:1234/?sap-ui-language=de

Also it seems 'theme' is not changing at all.

I have observed the same behavior in live editor - CodeSandbox.io on SAPUI5 WebComponent .Please let me know where am I gong wrong.

Regards,

Amit

Martin Hristov

July 31, 2019 at 7:26 am

Hello AMIT GUPTA ,

If you check the console warnings you can notice that there are 1 warning and an error shown:

If you do exactly what is suggested as a solution there and edit your main.js to look like this:

import "@ui5/webcomponents/dist/ThemePropertiesProvider"
import "@ui5/webcomponents/dist/MessageBundleAssets.js";

import "@ui5/webcomponents/dist/Button";
import "@ui5/webcomponents/dist/TextArea";
import "@ui5/webcomponents/dist/DatePicker";

The errors are not present anymore and both, the theming and the translations are working fine.

Regards,

Martin

AMIT GUPTA

July 31, 2019 at 8:22 am

Thanks Martin for your valuable input . I am amazed that how UI5 Web Components pin-points the exact error and how easier it is to fix.

It is working now as expected 🙂

Michael Kremser

December 27, 2019 at 12:03 pm

Hi Skelin,

your examples is nice but only with parcel.js

I would like to archieve this example only with node.js and express.js (and not parcel), but this scenario is difficult for me.

Do you have a short and clear instructions how it works with node.js and express?

I installed the dependencies, i referenced the index.js file in html. i also loaded an web component-loader in hope that i can load the module.

Obviously i lack a basic understanding of web components.

Regards

Michael

Michael Kremser

February 14, 2020 at 5:53 pm

has no one an idea how to use sap web components with express.js? currently it can't be used by bootstrap too. 🙁

any ideas would be helpful 😉

thx

Michael

Yang Zhao

April 19, 2020 at 3:00 pm

I tried ui5 web components and it looks very promising. You use parcel in the example but webpack & rollup are way much popular in non-sapui5 ui development. It would be super cool if you can give examples how to do the same with the above two bundlers. Thanks!

Michael Kremser

May 21, 2020 at 1:03 pm

Petar Skelin will be in the future tutorials released how to setup web ui components with node.js without using react, angular or vue?

Petar Skelin

Blog Post Author

May 21, 2020 at 1:19 pm

Hi Michael,

yes, I am still planning on writing this blog post, it got delayed due to some refactorings which were a prerequisite.

In the meantime, you could use this standalone example build repository with rollupjs here:

https://github.com/ilhan007/rollup-wc

Please give it a try as a starting point. The best way to get assistance with anything related to ui5-webcomponents (documentation and general questions as well), please open an issue in the project repository:

https://github.com/SAP/ui5-webcomponents

Veranika Kiykouskaya

June 7, 2022 at 10:01 am

Hi Petar,

thank you for the article. I have a problem with importing UI5 Web Components. I follow the steps in your article, but as a result I get an error in the console:

Uncaught TypeError: Failed to resolve module specifier "@ui5/webcomponents/dist/Button". Relative references must start with either "/", "./", or "../".

Only when I make a change in the import statement ("import "./node_modules/@ui5/webcomponents/dist/Button") the error changes, then it shows "Uncaught TypeError: Failed to resolve module specifier "@ui5/webcomponents-base/dist/UI5Element.js". Relative references must start with either "/", "./", or "../".

Is there a way to solve the problem? At this moment I can't use the UI5 Web Components because of this import issue.

Thanks and best regards,
Veranika

Petar Skelin

Blog Post Author

June 7, 2022 at 11:25 am

There is an updated blog post linked at the top of the article - could you give it a try? vitejs is the recommended bundler at this moment, you can follow the instructions there:

https://blogs.sap.com/2021/05/28/getting-started-with-ui5-web-components-in-2021/

Veranika Kiykouskaya

June 7, 2022 at 11:32 am

I tried the steps from this blog post too, but the error is the same.

Petar Skelin

Blog Post Author

June 7, 2022 at 11:48 am

In that case, it's best to open an issue in our repository with steps to reproduce and continue the discussion there.

https://github.com/SAP/ui5-webcomponents/issues

Technical Articles

The Fastest Way to Get Started with UI5 Web Components

Prerequisites

Creating the project structure

Installing UI5 Web Components as a project dependency

Starting a development server

Things to try out

What’s next

Assigned Tags