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.
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.
<!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:
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!
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.
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:
Or try out Hebrew to see RTL being derived from the language:
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.
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.
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?
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:
In the mean time, I have created an issue for tracking the progress on improving the APIs and their documentation here:
Thanks for reaching out 🙂
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:
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.
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.jsto look like this:
The errors are not present anymore and both, the theming and the translations are working fine.
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 🙂
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.
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 😉
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!
Petar Skelin will be in the future tutorials released how to setup web ui components with node.js without using react, angular or vue?
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:
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:
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,
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:
I tried the steps from this blog post too, but the error is the same.
In that case, it's best to open an issue in our repository with steps to reproduce and continue the discussion there.