Widget Builder is a command-line tool that lets you build, edit, and preview custom storefront widgets in real time, outside the context of your BigCommerce store.
This article is a guide to help you learn how to use Widget Builder.
- Node.js 18
- npm (opens in a new tab) 9.5.1
- A BigCommerce store (opens in a new tab) or sandbox store.
- A store-level or app-level API account with the following OAuth scopes:
|Other||As needed for the widget to function.|
Because the OAuth scope of these API credentials permits you to modify store content, we strongly recommend that you develop widgets using a sandbox store.
For more information on authentication, see Authentication.
To install Widget Builder and its dependencies, follow these instructions:
- Open a terminal, and verify that you are using supported versions of Node.js and
Refer to the Widget Builder README.md (opens in a new tab) for the latest supported Node.js and
Clone the widget-builder (opens in a new tab) GitHub repository.
Navigate to the
widget-builderdirectory, and install Widget Builder using the following command:
npm run install-cli
To retrieve usage information and view supported options and commands, run the following command:
Usage: widget-builder [options] [command] Options: -V, --version output the version number -h, --help display help for command Commands: init Initialization of widget builder configuration start [options] [widgetPath] starts the widget builder locally validate [options] <file> create <widget-template-name> Create a blank widget template publish <widget-template> Releases the widget template to the store belonging to the env config help [command] display help for command
Once you have installed Widget Builder, the next step is to configure your development environment with your store's authentication credentials so that you can work with your store's data during the development process. You'll need the store's
Access Token, and
API Path. To configure the environment, follow these instructions:
- Locate or create a parent directory for the widgets you plan to develop using these credentials.
# organized by name of store cd ~/bc-projects/tools-r-us mkdir widget-workshop cd widget-workshop
- Run the interactive sequence that generates the configuration file. The session will prompt you to enter your API account credentials. Begin by running
~/bc-projects/tools-r-us/widget-workshop % widget-builder init Thank you for using Widget Builder This guide will help you get your environment set up. Before continuing, please make sure you've created or received a Store API account. You'll need those credentials in order to generate the appropriate configurations. You can find more information here. https://support.bigcommerce.com/s/article/Store-API-Accounts#creating ? Are you ready to continue? You may press any key to continue (Y/n) > Y ? What is the Client ID? > xxxxxxxxxxxxx ? What is the Access Token? > xxxxxxxxxxxxx ? What is the API Path? > xxxxxxxxxxxxx [2021-09-08T15:12:40.271Z] Successfully created your configuration, you're all set!
If you need to reset the configuration, you can run the
widget-builder init command in the same directory to overwrite the existing assignments. Running
widget-builder init in a sibling directory will create a separate development environment.
Initializing Widget Builder at multiple levels of a single file hierarchy can have unpredictable results and is not recommended.
To use Widget Builder as a development tool, you must run
widget-builder commands from the same directory where you ran
Jump-start widget development with Widget Builder's
create command, which creates a child directory, populates it with blank template files, and starts a development server. To use the generator, run the following command:
widget-builder create <[path/to/]some-widget>
[2021-09-08T17:29:38.868Z] Successfully created ./some-widget [2021-09-08T17:29:38.870Z] Successfully created schema.json in ./some-widget/schema.json [2021-09-08T17:29:38.871Z] Successfully created config.json in ./some-widget/config.json [2021-09-08T17:29:38.871Z] Successfully created widget.html in ./some-widget/widget.html [2021-09-08T17:29:39.564Z] Starting widget-builder at http://localhost:8080! [2021-09-08T17:29:39.887Z] Socket connected.
Your default browser will open automatically and display a text widget on port 8080.
start command will start the development server for an existing widget that is located in a child directory of the environment root. Navigate to that environment root, then run the following command:
widget-builder start <[path/to/]widget-name>
[2021-09-08T17:29:39.564Z] Starting widget-builder at http://localhost:8080! [2021-09-08T17:29:39.887Z] Socket connected.
Your default browser will open automatically on port 8080.
To publish a widget to your BigCommerce store, navigate to its environment root, then run the following command:
widget-builder publish <[path/to/]widget-name>
Publishing a widget from the same path will update or overwrite your existing widget. If you have a widget with the same name currently deployed in your store, the updated widget will immediately replace the previous version on your live storefront.
To add published widgets to your store, open your store's control panel and navigate to Storefront > My Themes. Click the Customize button on your active theme, and locate your published widget in the Custom section of the left-side menu.
If you're interested in making your widgets available for download or sale on other stores, check out the BigCommerce App Marketplace (opens in a new tab) and learn about becoming a partner developer.