Skip to Content
Technical Articles
Author's profile photo Petar Skelin

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-buttonui5-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:

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.

Assigned Tags

      14 Comments
      You must be Logged on to comment or reply to a post.
      Author's profile photo Gregor Wolf
      Gregor Wolf

      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

      Author's profile photo Petar Skelin
      Petar Skelin
      Blog Post Author

      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 🙂

      Author's profile photo AMIT GUPTA
      AMIT GUPTA

      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

      Author's profile photo Martin Hristov
      Martin Hristov

      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

      Author's profile photo AMIT GUPTA
      AMIT GUPTA

      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 🙂

      Author's profile photo Michael Kremser
      Michael Kremser

      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

       

       

      Author's profile photo Michael Kremser
      Michael Kremser

      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

      Author's profile photo Yang Zhao
      Yang Zhao

      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!

      Author's profile photo Michael Kremser
      Michael Kremser

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

      Author's profile photo Petar Skelin
      Petar Skelin
      Blog Post Author

      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

      Author's profile photo Veranika Kiykouskaya
      Veranika Kiykouskaya

      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 

      Author's profile photo Petar Skelin
      Petar Skelin
      Blog Post Author

      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/

      Author's profile photo Veranika Kiykouskaya
      Veranika Kiykouskaya

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

      Author's profile photo Petar Skelin
      Petar Skelin
      Blog Post Author

      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