Project Shims – Using NPM modules with UI5

Have you ever heard of ‘Shims’?

Conventionally speaking, shim means a thin piece of material used for filling small gaps or spaces between objects. Typically these are used to provide better support and fit to an existing structure. In the tech world, ‘shim‘ has been used to refer to polyfills or libraries that help a particular software/code support a newer environment.

In this blog we are going to talk a bit more of tech and share about ‘Project Shims’ in the context of ui5 tooling.

Shims in UI5

If you are aware about UI5 (OpenUI5/SAPUI5), then you already know that UI5 provides us a powerful development toolkit for developing apps. But it can’t provide everything and also it should not re-invent everything which already exists. Every framework solves this problem by using third party tools. Some of the popular examples are bootstrap library for responsive UI, lodash for JS utility functions, d3 for charts and diagrams etc. These third party libraries are shims which will help UI5 framework for building better apps.

Until UI5 Tooling came into picture, using third party libraries with UI5 was not easy as compared to other JavaScript frameworks. Some of the popular ways to use third party libraries in UI5 was,

1. Using CDN script in index.html of the UI5 application.
2. Downloading the library files and loading it in project.

A major issue with the above approach is that prevents us from using world’s largest software registry and the standard choice for JavaScript packages-  npm. NPM packages greatly help with easy installations and easy version management. This problem is now tackled in UI5 with the help of Project Shims. 🎉

A project shim extension can be used to define or extend a project configuration of a module. The most popular use case is probably to add UI5 project configuration to a third party module that otherwise could not be used with the UI5 Tooling.

The below part of blog assumes that you have a basic understanding about ui5-tooling and yarn. If not, then go through UI5 Tooling documentation and yarn documentation.

(1) Preparing a sample UI5 project:

If you don’t have a ui5-tooling based project with you, then just follow the below steps:

1. Clone or download UI5 boilerplate project from ‘https://github.com/integrtr/ui5-boilerplate‘
2. Install project dependencies using yarn install
3. Run yarn start to start local development server. Once started you would be able to view your app running in default browser at http://localhost:8080

Voila! We have our ui5-starter-app built with the new ui5-tooling ready !

(2) Enhancing with NPM packages

Let’s add lodash and momentjs to our current project. You can do so by running the below commands in your terminal:

yarn add lodash
yarn add moment

UI5 tooling needs all dependencies to be maintained in ui5 > dependencies section of Package.json. Lets add that configuration to our Package.json. Below is how your final Package.json file should look like.

Tip: You can verify your dependencies using ui5 tree command in the terminal

Now new modules should be maintained in ui5.yaml file. This can be done using UI5 tooling extension project-shim. At the end of your ui5.yaml file below code should be placed. Since we are adding a project extension, below code should be separated by new line with 3 dashes (- – -)

---
specVersion: '2.1'
kind: extension
type: project-shim
metadata:
  name: thirdparty # this can be your project shim name
shims:
  configurations:
    lodash: # name as defined in package.json
      specVersion: '2.1'
      type: module # Use module type
      metadata:
        name: lodash
      resources:
        configuration:
          paths:
            /resources/thirdparty/lodash/: ''  # location where modules are stored
    moment: # name as defined in package.json
      specVersion: '2.1'
      type: module # Use module type
      metadata:
        name: moment
      resources:
        configuration:
          paths:
            /resources/thirdparty/moment/: ''  # location where modules are stored

/resources/thirdparty/lodash will be the location inside dist folder where your modules will be stored. Location inside /resources/ folder can be customized further similar to /resources/<custom_folder_path>/. Same path will be used in controller and component file to import node modules.

Now we have our NPM modules and that should be imported in project. These can be imported in any JS file such as component or controller files. If you are using some package globally and need it as soon as you load application, then it is better to require in Component.js, otherwise it can be required in any controllers file.

Below is a sample controller file where we are using lodash and momentjs for demonstration purpose.

While importing you need to use the same path which was provided in ui5.yaml file after omitting /resources part. At the end of path NPM package JavaScript file name should be added. For example lodash.js is the file inside lodash folder. If you are having confusion with file name you can always build project using yarn build-all to view folder structure and find file name.

That’s it! Now go ahead and include your favorite npm packages inside your UI5 projects and make use of amazing third party libraries to build your awesome UI5 applications.