Widget Builder

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.

Prerequisites

• Node.js 18+
• npm 9.5.1
• A BigCommerce store or sandbox store.
• A store-level or app-level API account with the following OAuth scopes:

For more information on authentication, see Authentication.

Install Widget Builder

To install Widget Builder and its dependencies, follow these instructions:

1. Open a terminal, and verify that you are using supported versions of Node.js and npm.

2. Clone the widget-builder GitHub repository.

3. Navigate to the widget-builder directory, and install Widget Builder using the following command:

1
npm run install-cli

To retrieve usage information and view supported options and commands, run the following command:

1
widget-builder -h

Sample output:

1
Usage: widget-builder [options] [command]
2
3
Options:
4
  -V, --version                  output the version number
5
  -h, --help                     display help for command
6
7
Commands:
8
  init                           Initialization of widget builder configuration
9
  start [options] [widgetPath]   starts the widget builder locally
10
  validate [options] <file>
11
  create <widget-template-name>  Create a blank widget template
12
  publish <widget-template>      Releases the widget template to the store
13
                                 belonging to the env config
14
  help [command]                 display help for command

Configure Widget Builder

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 Client ID, Access Token, and API Path. To configure the environment, follow these instructions:

1. Locate or create a parent directory for the widgets you plan to develop using these credentials.

Sample input:

# organized by name of store 
cd ~/bc-projects/tools-r-us
mkdir widget-workshop
cd widget-workshop

2. Run the interactive sequence that generates the configuration file. The session will prompt you to enter your API account credentials. Begin by running widget-builder init.

Sample session:

1
  ~/bc-projects/tools-r-us/widget-workshop % widget-builder init
2
3
  Thank you for using Widget Builder
4
5
  This guide will help you get your environment set up.
6
7
  Before continuing, please make sure you've created or received a Store API account.
8
  You'll need those credentials in order to generate the appropriate configurations.
9
  You can find more information here. https://support.bigcommerce.com/s/article/Store-API-Accounts#creating
10
11
  ? Are you ready to continue? You may press any key to continue (Y/n) 
12
    > Y
13
  ? What is the Client ID? 
14
    > xxxxxxxxxxxxx
15
  ? What is the Access Token? 
16
    > xxxxxxxxxxxxx
17
  ? What is the API Path? 
18
    > xxxxxxxxxxxxx
19
  [2021-09-08T15:12:40.271Z] Successfully created your configuration, you're all set!

Reset or create parallel configurations

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.

Generate a scaffold with create

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:

1
widget-builder create <[path/to/]some-widget>

Sample output:

1
[2021-09-08T17:29:38.868Z] Successfully created ./some-widget 
2
[2021-09-08T17:29:38.870Z] Successfully created schema.json in ./some-widget/schema.json
3
[2021-09-08T17:29:38.871Z] Successfully created config.json in ./some-widget/config.json
4
[2021-09-08T17:29:38.871Z] Successfully created widget.html in ./some-widget/widget.html
5
[2021-09-08T17:29:39.564Z] Starting widget-builder at http://localhost:8080!
6
[2021-09-08T17:29:39.887Z] Socket connected.

Your default browser will open automatically and display a text widget on port 8080.

Continue development with start

Widget Builder’s 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:

1
widget-builder start <[path/to/]widget-name>

Sample output:

1
[2021-09-08T17:29:39.564Z] Starting widget-builder at http://localhost:8080!
2
[2021-09-08T17:29:39.887Z] Socket connected.

Your default browser will open automatically on port 8080.

Publish to store

To publish a widget to your BigCommerce store, navigate to its environment root, then run the following command:

1
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 and learn about becoming a partner developer.

Resources

• Guide to API Accounts
• Widgets API Overview
• Widget Builder GitHub repository
• Widgets on the App Marketplace
• Becoming a Partner Developer