Experience Builder Command Line Interface

[SunshineLuke90]

An Esri Experience Builder Community CLI

Experience Builder custom widgets are extremely powerful, and this community has done a lot of work to share widgets with each other. I, and I'm sure many others, appreciate the willingness to share knowledge and experience with the entire community. However, difficulties arise in a few areas.

1. Widgets have potentially very different file formatting. Some people use Git/GitHub to publish their widgets as individual repos, some use a monorepo approach, packaging all of their widgets in one repository, others upload and update attachments on community posts. This makes it difficult for a developer that wants to use widgets provided from across the community to extend their applications.
2. Widgets imported into a project lose their link to the source. For developers who are constantly updating their widgets with bugfixes and improvements, those using their widgets don't get the added benefits unless they intentionally re-download the widget.
3. It's difficult to use a specific version of a widget. If a developer is publishing updates consistently, those using their widget don't have backups of any one specific version, making it difficult for those using the widget to maintain trust, since the widget source code could be updated at any time.
4. It's difficult to find new widgets, or to have your own widgets discovered. There isn't one fantastic "Source of truth" for ALL custom Experience Builder Widgets. Jeffrey Thompson's "A List of Custom Widgets" is a fantastic starting point, but the widgets within this list still have all of the difficulties listed above.
5. Experience Builder Developer Edition isn't easy to get set up the first time. When you're developing your first widget, it can be difficult to know where to start, or to see examples of fully fledged widgets with minimal effort.

How can this be solved?

Starting with point #2 and #3, NPM has good solutions to both of these issues. If widgets were published as npm packages, it would be easy to grab and keep using a specific version of a widget, and the npm package would continue to exist, meaning new updates to the npm package could be pulled. Npm comes with it's own set of issues for Experience Builder though. When trying to install a package into a project the normal way, using

npm install <packagename>

 the package will get dropped in the node_modules directory. This isn't super helpful, because we need widgets to end up as a unique folder within the your-extensions/widgets directory. This would mean some extra moving of folders around, which is exactly what I'm trying to avoid.

On point #1, unifying the formatting of widgets that are shared across the community is an effort that can only be fully realized by establishing community guidance for how to package, share and update widgets for community members. Hopefully, this blog post will assist in that.

A hopeful solution

To address all of the issues above, I have developed an Experience Builder Command Line Interface (CLI) with the following functions:

• dev-setup : Sets up the Developer Edition environment, with a single command. Makes it easy to get started for the first time, and might be the first command you run with this interface.
• install : Installs a widget from NPM, directly into the widgets folder of your Experience Builder project, without adding a package to your node_modules folder
• update : Updates a widget already installed from NPM, either to the latest package published, or to a specific version
• remove : Removes a widget from your widgets folder, making it easy to get rid of widgets you don't need.
• search : Searches all of NPM for custom Experience Builder widgets, searching for widgets based on keywords, and internal formatting
• format : Formats a widget, either adding or modifying a package.json file, preparing it to be uploaded to npm, based on both community standards, and using information entered into the manifest.json
• scaffold : Creates a new widget, based off of one of the example widgets on esri's arcgis-experience-builder-sdk-resources repository.
• start : runs npm start in both the client and server directories, starting the developer environment. Once the task is closed, both server and client directories will stop.

This CLI is based around publishing widgets as npm packages, with some standardized keywords and formatting. As long as this formatting and standardization are used, widgets can be searched across all of npm, using the CLI. This method of using keywords and naming schemes isn't entirely unique, as other communities like ESLint and Vite.

Not only that, but the CLI allows for users to format a widget that has already been developed, for publishing on NPM. This way, the standards can be auto-applied, and the developer doesn't need to spend time manually editing a config file to align with community widget formatting.

It also makes it easier to use consistent versions of widgets provided by other developers, and makes it easier to get started building a widget from scratch, based on a template provided and maintained by esri.

Using the CLI

Sound interesting? Want to try out using the CLI? Awesome! Please note, at the time of publishing this blog post, only 6 widgets have been published to NPM using these community npm standards. The hope is that this set of formatting catches on, and once it does, more widgets will follow.

Installation

To install globally, and use the community CLI, run

npm install -g exb-community-cli

This will allow you to use the cli across all Experience Builder installations, and makes it easier to run CLI commands. All commands should be run from the client directory in Experience Builder with the exception of dev-setup. This way, the CLI can place widgets in the correct location in your project.

If you don't already have Experience Builder installed, this CLI can make that process a bit easier!

To set up your development environment, navigate to where you would like the development environment installed and run

exb dev-setup

This will download and install Experience Builder Developer Edition, installing all dependencies along the way, and even making it easy to get running in a browser.

Using commands

To search for community widgets, run exb search, and you will see a list of experience builder widgets. Right now, the CLI defaults to showing 15 widgets at a time, but if you want to see more widgets listed, add the --size tag, along with the number of widgets you want listed.

If you find a widget you like, you can download it, using exb install package-name. Use the package name (Not necessarily the widget name) listed by the search tool to add the widget to your project, and you can even specify a specific version by adding the semantic version to the end of the widget name (ex. exb install widget@1.0.3). By default, when a new widget is installed, it automatically tries to download all dependencies. If you don't want te CLI to download dependencies by default, you need to add the --widget-only flag to the end of the command.

Additionally, if you want to start from scratch on a widget, run exb scaffold widget-name. This will open a selection interface where you can select from widget samples published by esri. Select one, and a new widget, using your defined widget-name, will be added to your development environment.

Publishing widgets to npm

Once you are happy with a widget, and want to share it with the rest of the community, first fill out as much information as possible in your manifest.json file, and then run exb format widget-name. This will pull information from your manifest.json file, and create a new package.json file, if it doesn't already exist. The package.json file is a requirement for publishing on npm. To publish a widget to npm, you need to navigate a terminal to the widgets folder, and run npm login then npm publish. You will need an npm account, and will need to provide authentication at both the login and publish steps, but the process to create an account and provide authentication is fairly straightforward (And free).

As long as your widget is both a valid experience builder widget, and has the keyword exb-widget in it's package.json, it will appear on the search function of the community cli for all users.

Source Code

If you're interested in seeing how the community CLI works, the code is public on my GitHub. Feel free to make a pull request if you want to add any additional features, or enhancements.

[ncramer11]

I think this CLI could be very helpful for managing all the custom widgets my organization uses. Especially the scaffold command, as it makes it easier for a novice developer like myself to start making my own. Coming from a user perspective, I would encourage developers to consider publishing to NPM (at the very least we can start a conversation about standardization).

[SunshineLuke90]

I appreciate the feedback! Do you mind providing some more information on the custom widgets that your organization uses, and maybe how you're currently using them? For instance, my organization uses a few widgets developed by the community (Namely the Rightclick widget by Brian McLeer), as well as some development in-house.

For anyone looking for publishing to NPM, referenced by @ncramer11, I just made a community post here on standardization and publishing widgets to NPM. I would love for more conversation about standardization! This CLI is just a first start, and I want to make sure to hear perspectives from the whole community.

[ncramer11]

@Brian_McLeer really is the MVP! We try to keep external applications as vanilla as possible, but for internal applications his Enhanced Measurement and Advanced Draw widgets have really been useful. I think a lot of users could benefit from his hard work, so lowering the barrier of entry for adding custom widgets is a commendable objective.