← Back to xUI downloads

xUI Installation & Deployment Guide

Use this guide to add xUI to ArcGIS Experience Builder Developer Edition, confirm that it works, and prepare an xUI-enabled application for production.

xUI licensing You may download and use xUI for development and evaluation at no charge. A purchased xUI license is required before deploying xUI in a production environment or making an xUI-enabled application available to end users.
Request a license

1. Before you begin

You will need:

Version compatibility matters: Download the xUI package built for your exact Experience Builder Developer Edition version. For example, use the EXB 1.21 package only with Developer Edition 1.21.

2. Download the correct xUI package

  1. Return to the xUI Downloads page.
  2. Expand the row matching your Experience Builder Developer Edition version.
  3. Choose the recommended xUI release unless you need a specific earlier version.
  4. Select Download ZIP.
  5. When the download finishes, locate the ZIP in your browser's Downloads folder.

A filename such as XUI-v0.7.1-exb21-dev.zip identifies xUI 0.7.1 built for Experience Builder 1.21.

3. Install xUI in Developer Edition

  1. Stop the Experience Builder client if it is currently running. In its command window, press Ctrl+C.
  2. Open the downloaded ZIP and extract its contents to a temporary folder.
  3. Locate the extracted XUI widget folder. This is a compiled, obfuscated distribution; it should contain dist, config.json, icon.svg, and manifest.json.
  4. Open your Experience Builder Developer Edition installation folder.
  5. Browse to:
ExperienceBuilder\client\your-extensions\widgets\
  1. Copy the complete extracted XUI folder into the widgets folder. Do not copy only the files inside it.
  2. Confirm that the resulting structure resembles:
ExperienceBuilder
└─ client
   └─ your-extensions
      └─ widgets
         └─ XUI
            ├─ dist
            ├─ config.json
            ├─ icon.svg
            └─ manifest.json
Precompiled and obfuscated package The Developer Edition download contains the deployable xUI files, not the original source code. Do not rename, rearrange, or edit files inside dist. Copy the package exactly as provided.
Avoid an extra folder level If you see a path such as widgets\XUI\XUI\manifest.json, move the inner XUI folder up one level. The correct path is widgets\XUI\manifest.json.
  1. Restart the Experience Builder client using the normal command for your Developer Edition version.
  2. Wait until the client finishes compiling and displays no xUI-related errors.
  3. Start or confirm the Experience Builder server, then open the Developer Edition home page in your browser.

4. Add and test xUI

  1. Open an existing experience or create a test experience.
  2. In the builder, open the Insert widget panel.
  3. Find xUI under the custom widgets section.
  4. Drag xUI onto the page and complete its configuration.
  5. Preview the experience and test the workflows that matter to your organization.
  6. Check the client command window and browser console for errors before proceeding.

Development and evaluation can stop here and do not require a paid xUI license.

5. Prepare for production deployment

Purchase the xUI license before this step A production deployment includes making an xUI-enabled application available to internal staff, clients, customers, or the public.
Request a license
  1. Confirm that your organization has purchased the appropriate xUI production license.
  2. In Experience Builder Developer Edition, open the completed experience.
  3. Publish the experience.
  4. From the experience gallery, open the experience's three-dot menu and select Download.
  5. Extract the downloaded application ZIP.
  6. Copy the extracted application folder to your supported web server.
  7. If the application accesses private ArcGIS content, register the application in ArcGIS Online or ArcGIS Enterprise and add the resulting App ID to the application's config.json.
  8. Open the deployed application's index.html address and complete a production acceptance test.

For Esri's current application-hosting procedure, see Experience deployment in the ArcGIS Experience Builder documentation.

6. Update an existing xUI installation

  1. Back up the existing xUI widget folder and any application configuration you need to preserve.
  2. Confirm that the replacement package supports your exact Experience Builder version.
  3. Stop the Experience Builder client.
  4. Replace the existing xUI widget folder with the newly downloaded version.
  5. Restart the client and confirm that it compiles without errors.
  6. Open a copy of an existing experience and test it before updating production.
  7. Re-publish, download, and redeploy the application using your normal release process.
Do not overwrite production without a rollback copy Retain the previously deployed application until the new release has passed acceptance testing.

7. Troubleshooting

xUI does not appear in the widget list

The widget appears but produces errors

The deployed application cannot access private content

Confirm that the downloaded application was registered in the correct ArcGIS Online organization or ArcGIS Enterprise portal and that its App ID was added to the deployed application's configuration.

Deployment checklist

ArcGIS and ArcGIS Experience Builder are trademarks of Esri. xUI licensing is separate from any Esri software or subscription requirements.