Frequently Asked Questions (FAQ)

Using developer edition of ArcGIS Experience Builder with the ArcGIS API for JavaScript

By default, Experience Builder does not load the ArcGIS API for JavaScript (JSAPI) when the app loads. There are two options to utilize JSAPI modules. See Modules in the ArcGIS API for JavaScript for details.

Accessing the MapView from within a widget is demonstrated on the jimu-arcgis/JimuMapView page of the API Reference.

Yes, generally you can use widgets from the ArcGIS API for JavaScript within your custom Experience Builder widgets. See the Editor widget sample for an example.

Using view.ui.add() from a custom Experience Builder widget is not recommended. We plan to provide similar functionality in JimuMapView in the future.

When you add jimu-arcgis, the ArcGIS API for JavaScript gets loaded automatically.

When importing esri/config from the ArcGIS API for JavaScript, using esriConfig.request.interceptors.push({}) does not work. This happens because Experience Builder has added an interceptor that matches all URLs. To use interceptors, add your interceptor to the beginning of the interceptor list like this: esriConfig.request.interceptors.splice(0, 0, {}).


The current LTS version of Node.js is supported. Go to the Node.js downloads page and click LTS - Recommended for Most Users. See more information on the requirements page.

ArcGIS Services

Because Experience Builder is data source based, FeatureLayer data can be accessed in a few different ways.

To filter a FeatureLayer, there are two basic ways, depending on how the data source is configured:

  • If the widget loads data, the recommended way is to use the DataSourceComponent like:

    Use dark colors for code blocksCopy
    <DataSourceComponent useDataSource={} widgetId={} query={}>
    { Your render method }

    You can find an example of using the DataSourceComponent in the Message subscriber sample and the Server-side output data source sample.

  • If the widget does not load data, you can use the updateQueryParams() function of a Data Source. See the Filter feature layer sample for an example.

The queryRelatedFeatures method is available for execution against a FeatureLayer. Once you obtain the FeatureLayer you wish to obtain the related features from, you can implement the query making use of the relationshipId like in the ArcGIS API for JavaScript Query Related Features sample.

Once you have the related features as explained in the "How to retrieve related features" question, you can use the applyEdits() method on a FeatureLayer. This is the same method that is used on a FeatureLayer within the Editor and Table widgets, for example. A sample of this method's executions is available in the ArcGIS API for Javascript Update FeatureLayer using applyEdits() sample.


Both styles work well in Experience Builder, so it's up to you - you can use whichever you prefer. It seems like the React community is moving toward functional style components as the future, but class-based style components are easy to start and understand.

Custom Widget Development

Please review the Widget communication guide page for details on how to communicate between widgets. Also, see the Control the widget state sample for insight on how to use the getAppStore method and the appActions module from the jimu-core package.

An Experience Builder widget is a React component, so we don’t handle the widget instance object. Instead, we use state props to manage widget lifecycle. The state is saved in the app store and is mapped into widget props. A widget has three states defined by enum WidgetState: Opened, Active, Closed. When a widget is added into a page, it is opened by default; when a widget is added into the widget controller widget, the end user can open and close it. For performance reasons, when an end-user clicks a widget, we don’t make the widget's state Active. If a widget needs the Active state, it should declare needActiveState in manifest property, then its state will be changed to Active when the user clicks the widget.

Developers who are familiar with the developer edition of ArcGIS Web AppBuilder may expect to see callback functions like onOpen, onClose, etc. Because the Experience Builder widget is a React component and the widget status is saved in the application store and is mapped to widget props, you should check props.status instead.

When a widget is closed, the only thing that the framework does is to change the widget state to Closed. As a result, in React, instead of handling the instance, we hook it to the react component lifecycle, such as componentDidUpdate() for class-based components or useEffect() for functional components.

Yes, you may use React-redux. You can access it via import {ReactRedux} from 'jimu-core'.

There are a few approaches to creating widgets that have no user interface. These include:

  • Create the widget.tsx but return null in the widget render.
  • Create a widget without a widget.tsx, providing functions through the: message action, data action, or extension.

When the app is loaded, it invokes the extension point AppConfigProcessor. So, the widget can provide an extension for this extension and logic should be placed within the extension. Please see Extension points.

There is no way to add custom tools. We recommend that you create a custom widget that includes a map along with your custom tools.

Please see the Unit Testing page for instructions on how to do unit testing.


The Experience Builder deployable export is simply a JavaScript/HTML/CSS app so it can be deployed into any web server. See the Deployment page for more help on deploying.

Described below are two approaches. One is for developing custom widgets and custom themes only; the other is for the combination of custom widgets, custom themes, and app configurations.

Custom widgets and themes only
  1. The key is to have a manifest.json file at the root of your repository. The following properties in your repo's manifest.json are necessary for your repo to be integrated in your development environment. Comments pertaining to necessary properties and values are included below.

    Use dark colors for code blocksCopy
      "name": "exb-custom-widgets-themes-repo", // Required property
      "type": "exb-web-extension-repo", // Required property/value for the repo to be compiled by webpack within client
      "description": "This is a sample custom widgets and themes repo for the developer edition of ArcGIS Experience Builder.", // Required property
      "copyright": "", // Required property
      "license": "" // Required property
  2. Within your repo, any custom widgets must live within a widgets child directory. Similarly, any custom themes must live within a themes child directory.

  3. Clone the repo into the client directory, then webpack will compile the widgets automatically when executing npm start.

Custom widgets, custom themes, and app configurations

This approach requires two code repositories. The first repo, as described above, is for the custom widgets and themes. The second repo is for containing the app configuration directories at the root level. To use the second repo, do the following:

  1. If an ./server/apps/ directory exists, you must rename it to something other than "apps", or remove it.
  2. Your apps repo must be cloned into your installation's ./server/public directory with the name "apps". Either: git clone git@web-based-repo-manager:username/repo-name.git apps or git clone https://web-based-repo-manager/username/repo-name.git apps should do.
  3. The app names within the apps directory can be a string or an integer, so long as the app directory's name matches the value of the id property within info.json.
  4. The app configurations will compile when executing npm start.


Jimu UI is the primary component library for Experience Builder, and you may want to use that first because it will keep your custom widgets and themes consistent with the rest of the Experience Builder theme. If you do have a requirement to use the Calcite Design System, you can do that - see the Calcite sample widget.

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.