How to install Experience Builder developer edition

Developer edition of ArcGIS Experience Builder is a developer-focused tool for creating custom web applications, widgets, and themes. It is compatible with ArcGIS Online and ArcGIS Enterprise 10.6 and later. This page outlines the installation steps and available options for setting up the developer edition of Experience Builder.

How to install developer edition

Here are the general steps to install developer edition of Experience Builder.

1. Create a Client ID
Create a Client ID to start using Experience Builder developer edition.
2. Install server service
Install the server service to run the builder interface.
3. Install client service
Install the client service to run the webpack server that bundles your custom widgets.

1. Create a Client ID

The developer edition of Experience Builder requires a Client ID to connect to ArcGIS Online or ArcGIS Enterprise. This is a unique identifier that allows the developer edition of Experience Builder to authenticate with your ArcGIS account and access the necessary resources.

Log in to your ArcGIS Online or ArcGIS Enterprise portal and go to the Content page.
In the Content page, click New Item.
In the New Item dialog box, select Application.
Under the Application type selection, choose the Other application option and click Next.
Enter the following parameters:
- Title - Enter the application title, such as Experience Builder credentials.
- Folder - Select a folder where the item will be stored within your Content.
- Optionally fill Categories, Tags, and Summary if you prefer.
- Click Save to create the application.
In the Credentials section, click the Manage button.

Note
In ArcGIS Enterprise 11.1, click the Settings button at the top of the item page, then click the Update button under "App Registration".
In the Redirect URLs section, click the + Add button and enter https://localhost:3001/.
At the bottom of the page, click the Save button.
Copy the Client ID to use it in the "Server Install" steps, see below.

2. Install server service

The Server service is responsible for running the builder interface of developer edition of Experience Builder. The server service must be running in order to see your changes in the builder interface.

Experience Builder uses Node.js. Check the recommended Node version for the version of Experience Builder you are using, then download and install that version of Node.js for your operating system.

Note
You can also view the installation video for a walkthrough.
Download the developer edition of Experience Builder and unzip it on your local drive.
Open a command prompt or terminal window.
Within the terminal, browse to the /server directory of the Experience Builder files that you unzipped in step 2 using the cd command.
Type npm ci and then the Enter key to install the necessary modules.
Type npm start and then the Enter key to start the service.

Tip
To use custom ports, you can pass them as options like this: npm start -- --port 81 --https_port 443.
To run the server at a subdirectory (e.g. https://localhost:3001/subfolder), you can pass the path option like this: npm start -- --path /subfolder.
In a browser, open this URL: https://localhost:3001/. You should see the builder interface.

Tip
Experience Builder uses a self-signed certificate in Node.js to support HTTPS. You can run Experience Builder using this certificate by trusting it, or you can use your own certificate. To use your own certificate, replace these two files in the server/cert directory: server.key and server.cert. Alternatively, you may pass in a custom path to the folder in which the certificate files (server.cert and server.key) reside, like this: npm start -- --cert_folder <folder path>
Specify the URL to your ArcGIS Online or ArcGIS Enterprise organization, and paste in the Client ID that you created in the previous section.

Tip
In Safari, signing in to developer edition of Experience Builder with PKI, Kerberos, IWA, or LDAP authentication types requires selecting Disable Cross-Origin Restrictions (in Safari's develop menu).
Install the client, see below.

3. Install client service

The Client service is responsible for running the webpack server, which is used to bundle and load your custom widgets and themes. The client service must be running in order to see your changes in the builder interface.

Open a command prompt or terminal window.
Within the terminal, browse to the /client directory of the Experience Builder files that you unzipped in the previous section using the cd command.
Type npm ci and then the Enter key to install the necessary modules.
Type npm start and then the Enter key to start the service.

Tip
New files/folders created in the client/your-extensions directory will require a restart of the client server.

You can have multiple versions of the developer edition of Experience Builder on the same machine. Please check that your machine meets the System requirements.

Installation options

The developer edition of Experience Builder can be installed in different ways depending on your needs. Here are the options:

Install offline
Install as a Windows Service

Install offline

If you are in a disconnected environment, you can perform an offline install of developer edition. This is useful if you are in an environment that does not have access to the internet or if you want to run Experience Builder on a server that does not have internet access.

Install developer edition using the offline Node cache ZIP.
Install the offline libraries, ArcGIS Maps SDK for JavaScript and Calcite, for offline use and update Experience Builder to reference them.

Note
You can also view the offline installation video for a walkthrough. It is also suggested that you setup CORS support on your server for the hosted ArcGIS Maps SDK for JavaScript. For example, with Windows OS, you can add Access-Control-Allow-Origin action in HTTPS Response Header.

Install the offline Node cache

Experience Builder uses Node.js. Check the recommended Node version for the version of Experience Builder you are using, then download and install that version of Node.js for your operating system.
Download the developer edition of Experience Builder and unzip it on your local drive.
Download the Node cache ZIP for the developer edition of Experience Builder and unzip it on your local drive.
Open your user folder in a command prompt or terminal. Type npm config get cache and press the Enter key. A folder path will be displayed.
Tip
- In Windows, the user folder will be something like C:\Users\my_username.
- On macOS, the user folder will be something like /Users/my_username.
Copy the folder path that you got in the previous step and open that directory in Windows Explorer or Finder.
Copy the downloaded Node cache files (from step 3) into this directory.
Open a command prompt or terminal window.
Within the terminal, browse to the /client directory of the Experience Builder files that you unzipped at the beginning of this section using the cd command.
Type npm install --offline and then the Enter key to install the necessary modules.
Open another command prompt or terminal window.
Within the terminal, browse to the /server directory of the Experience Builder files that you unzipped at the beginning of this section using the cd command.
Type npm install --offline and then the Enter key to install the necessary modules.

Install the offline libraries

In a disconnected environment you will not have access to the CDN libraries that are necessary for Experience Builder to run:

ArcGIS Maps SDK for JavaScript CDN
Calcite Components CDN

Because of this, you will need to download these libraries, host them locally, and point developer edition of Experience Builder to use those locally hosted versions.

Check the recommended ArcGIS Maps SDK for JavaScript version for the version of Experience Builder you are using, then download and install that version of the ArcGIS Maps SDK for JavaScript locally. Note the URL of the hosted files to use later.
In the Experience Builder files, browse to client/node_modules/@esri/calcite-components/dist/calcite and copy these files to your web server. Note the URL of the hosted files to use later.
In the Experience Builder files, browse to client/dist.
There are four places you will need to update the variables arcgisJsApiUrl and calciteComponentsUrl with the local URLs you got in the steps above. For example:
- Replace "arcgisJsApiUrl": "https://js.arcgis.com/4.33/" with "arcgisJsApiUrl": "https://YOUR_JS_API_URL/4.33/"
- Replace "calciteComponentsUrl": "https://js.arcgis.com/calcite-components/3.0.3/" with "calciteComponentsUrl": "https://YOUR_CALCITE_URL/"
... in each of the files below:
- <install folder>/client/dist/index.html
- <install folder>/client/dist/experience/index.html
- <install folder>/client/dist/template/index.html
- <install folder>/client/dist/builder/index.html

Run developer edition offline

Now that you've installed the offline Node cache and updated Experience Builder to point to locally accessible versions of the libraries, you can run developer edition offline.

Experience Builder requires a connection to ArcGIS Enterprise portal. Create a Client ID using the steps in the previous section.
Within the terminal window opened to the /client folder from the previous section, type npm start to start the client service.
Within a separate terminal window opened to the /server folder from the previous section, type npm start to start the server service.
In a browser, open this URL: https://localhost:3001/. You should see the builder interface.
Specify the URL to your ArcGIS Enterprise organization, and paste in the Client ID that you created at the beginning of this section.

Install as a Windows Service

You can install developer edition of Experience Builder as a Windows service. This allows you to run the server service in the background and automatically start it when your computer starts. This is useful if you want to run developer edition of Experience Builder on a server or in a production environment.

Download and install the latest Node.js LTS version for your operating system.
Open Windows command prompt as administrator.
Change the directory (cd) to the /server directory of Experience Builder.
Run the command npm ci to install the dependencies.
Run the command npm run install-windows-service.
Open the Windows Services app and start the Experience Builder service (default name: exb-server).
To remove the Experience Builder service, run the command npm run uninstall-windows-service.