How to include external JavaScript libraries in SAP UI5

When using external JavaScript, CSS or other assets in a UI5 app, the key question is whether you need to integrate them into the UI5 module loading mechanism. Not doing so is simpler, but there are two situations, where you want or even need to use it:

1. If you want your app to be compatible with the SAP Fiori Launchpad. In this case, the index.html of your app is not used, so there is no way to add any HTML tags directly: all dependencies must be loaded by UI5 itself.
2. If you want to preload your libraries in order to decrease the number of server requests for the sake of performance.

Method 1: Include in index.html

The easiest way to include some third-party code is simply putting it into the index.html, just like you would do on any non-UI5 web page. The only thing, you need to keep in mind here, is that you probably want to initialize your code after UI5 has been loaded. To do this, attach your code to the init event of by wrapping it in sap.ui.getCore().attachInit() like this:

<script language="javascript" src="path/to/YourLib.js"</script>

<script id="sap-ui-bootstrap"
		src="https://openui5.hana.ondemand.com/resources/sap-ui-core.js"
		data-sap-ui-libs="sap.m"
		data-sap-ui-theme="sap_belize"
		data-sap-ui-compatVersion="edge"
		data-sap-ui-preload="async"'>
</script>

<script>
	sap.ui.getCore().attachInit(function () {
		// Initialize your UI5 app here
		sap.ui.require(...)
	});

	sap.ui.getCore().attachInit(function () {
		// Initialize your external libraries here, just the way you would do without UI5
	});
</script>

This method will work if you run your app stand-alone (e.g. an OpenUI5 app without an SAP backend) or deploy it on a SAP NetWeaver as a BSP application. It will not work in the Fiori Launchpad.

Method 2: Register module paths

If you do not want to use the index.html (e.g. if you need to stay compatible to Fiori Launchpad), you will need to use UI5's module loader. But don't worry: you don't have to create any new modules or packages or whatsoever. All you need is to specify a module name for every file, you need to include, and use that name in your controllers.

Be careful about where you place your code to register module paths: they must be registered before being used, of course. Here are some of the most advisable options:

• In the BaseController (if your app has a controller, that all other controllers inherit from), before or after the controller definition
• In the controller that is actually using the third-party lib, before the controller definition
• In Component.js, after the componenent definition

NOTE: if your library uses a global variable, you must specify it as a global explicitly by adding a special global directive comment: e.g. to make the global moment from moment.js available use /* global moment */ - see example below.

Importing third-party JavaScript

You will need to register a module path for every JS file you want to include. Here is an example, where the includes are placed in the BaseController. Refer to this tutorial for details on controller inheritance.

// Add all JavaScript includes here
jQuery.sap.registerModulePath('libs.library1.filename1', 'path/to/folder1/filename1.min');
jQuery.sap.registerModulePath('libs.library2.filename2', 'path/to/folder2/filename2.min');

// Register your globals
/* global yourGlobalVariable */

// Now define your controller
sap.ui.define([
	"sap/ui/core/mvc/Controller",
	"libs/library1/filename1",
	"libs/library2/filename2"
], function (Controller, filename1, filename2) {
	"use strict";
	return Controller.extend("your.app.controller.BaseController", {
		
		// Controller body

	});
});

This example will import the JavaScript files path/to/folder1/filename1.min.js and path/to/folder2/filename2.min.js into every controller, that extends the BaseController.

Including custom CSS

If your dependency requires it's own CSS stylesheets, you can import them like this:

if (sap.ui.getCore().byId("id-for-your-include") === undefined) {
    jQuery.sap.includeStyleSheet('http://yourdomain/your/include/path', 'id-for-your-include');
}

Since UI5 keeps track of everything using it's id-system, it is a good idea to give your include an id too. The id can be anything, but it must be unique within your application.

I recommend putting CSS includes right next to jQuery.sap.registerModulePath() for the corresponding JavaScript.

Preloading third-party dependencies

If you want to speed up your app, it is a good idea to preaload all libraries, thus limiting the amount of server requests made. Now, that UI5 takes care of loading them, this is easy: just include all required files in the Component-preload.js. To do so,  append every script file to the JS object there using the component name for key and the JSON-escaped file contents for value like this:

sap.ui.require.preload({
    "your/app/Component.js": "...",
    "libs/library1/filename1": "... Contents of file 1 ...",
    "libs/library2/filename2": "... Contents of file 2 ..."
}, "your/app/Component-preload");

Note, that you only can preload JS files. This does not seem to work for CSS.

Method 3: Create a wrapper module

Last, but not least, you can also create a real UI5 module or even a library wrapping your external lib. Then you will not need to register the paths to each include file, etc. If your are importing a widget (e.g. a charting library or so), you could even wrap it in a UI5 control to make it possible to initialize it within the code of a view. This is sure a very elegant solution, but it will also be by far more time consuming, than the options above. You can get a basic idea on what you will need in this SAP blog post.