Using third-party libraries

The jimu libraries that come with ArcGIS Experience Builder can be used to include a variety of functionality into your widget. In addition to this functionality, third-party libraries can be included and used within an Experience Builder widget.

There are three ways to include third-party libraries to make them available for use within a widget. With each way, you can use the library in one or multiple widgets.

For the "NPM install" and "download and load directly" approaches:

• If the third-party is used by only one widget, you can use static import or dynamic import depending on your requirement.
• If the third-party library is used by more than one widget, use dynamic import. The dynamically loaded modules are generated into the widgets/chunks folder after compiling.

NPM install

Using NPM to manage the dependencies is a very common approach and is the recommended way if your requirements allow.

How to

The best way to do this depends on whether the dependency is used by one or multiple widgets.

• If the dependency is used by only one widget, you can install the dependency into the widget folder.
• If the dependency is used by multiple widgets, you should create a shared module to hold the dependency and then import the module into the widgets as necessary.

In a terminal, browse to the directory (the widget folder or a shared folder), run npm init, and answer the questions. This will place a package.json file at the directory.

Next, find the name of the third-party library in the npm package directory. This can be done by going to npmjs.com and searching or the package name will be listed within the library's documentation pages. Use the package name to run the npm install command:

1
npm install <package-name> -S

Running this command does two things. First, it downloads the library files and places them into the node_modules directory. Second, it adds a reference to the library in the package.json file you created with the npm init command above.

The package name can now be used in import commands in your custom widget. For example, import ReactDataGrid from "react-data-grid"; or import('react-data-grid').then(ReactDataGrid => {...}).

Experience builder will automatically install all widget dependencies that are listed in the package.json files when you run npm install in the client folder. This automatic install will only happen for widgets that are in the your-extensions folder.

See the react-data-grid sample for an illustration of this pattern in action.

Load via CDN using manifest.json

If this library is available on the CDN, including the library by putting the library's CDN url in the manifest.json file's dependency property may be a viable option.

How to

Find the CDN url of the library. Typically this is listed in the library's documentation, or you may be able to find it on jsDelivr or unpkg. For example, in the jQuery sample the CDN url is https://unpkg.com/jquery@3.5.1/dist/jquery.js.

Add an array property to the widget manifest.json file called dependency and add the url to the array. For example:

1
2
3
"dependency": [
  "https://unpkg.com/jquery@3.5.1/dist/jquery.js"
],

Experience Builder will automatically load the library when the experience is loaded and your widget can use the library per the library's documentation.

See the jquery sample for an illustration of this pattern in action.

Download and load directly

Including the library by manually downloading the files and storing them within your widget directory structure is another option.

How to

Find the downloadable built assets for the library. Typically this is linked in the library's documentation, or in a dist folder in the downloadable assets in the Releases area of the library's GitHub repository.

After downloading, depending on whether this library will be used by one or multiple widgets, extract the files and copy them into your widget root directory or a shared directory. Because it will be included via a relative path import, you can place the files in any location within your widget. However, by convention it is recommended to place the files within a folder called lib.

After the files are in place, the library can be imported using a relative path. For example: import * as d3 from "./lib/d3/d3.min.js"; or import('./lib/d3/d3.min.js').then(d3 => {...});

See the D3 sample for an illustration of this pattern in action.