Skip to navigation
CoursesWidgets in StencilModule 4: Schema

Lab - Widget Builder Setup

Plan: Stencil Developer

 Lesson 12 of 23 · 30 min

Summary

In the previous lab, you created a widget template by sending a request to the Widgets API with a REST client. From here on, you’ll build widget templates with Widget Builder, a command-line tool that lets you build, edit, and preview widget templates locally, outside the context of your BigCommerce store. In this lab, you will install and configure Widget Builder and create the blank template files for the next lab. You only need to install and configure it once; later labs in this course reuse the same setup.

In this lab you will

  • Install Widget Builder
  • Configure Widget Builder with your store’s API credentials
  • Create a blank widget template

Prerequisites

  • BigCommerce store
  • BigCommerce API credentials (Content: Modify)
  • Git, Node.js 18+, and npm 9.5.1+ installed locally

Install Widget Builder

  1. Clone the Widget Builder repository:
git clone https://github.com/bigcommerce/widget-builder.git
  1. Navigate into the cloned directory and install Widget Builder globally:
cd widget-builder
npm run install-cli
  1. Confirm the install by viewing the available commands:
widget-builder -h

You should see the usage information for Widget Builder, including commands such as init, start, create, and publish.

Configure Widget Builder

Widget Builder needs your store’s Client ID, Access Token, and API Path to preview and publish widget templates.

  1. Create a local directory to hold your widget templates for this course, outside of the widget-builder repo you just cloned:
mkdir ~/widget-templates
cd ~/widget-templates
  1. Run the init command to save your store’s API credentials:
widget-builder init
  1. Enter the Client ID, Access Token, and API Path for the API account you created in Module 1: Lab - Getting Started, when prompted. This saves an .env file in the current directory.

An example session looks like this:

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? https://api.bigcommerce.com/stores/abcd1234/v3/
Successfully created your configuration, you're all set!

If you need to use different credentials later, run widget-builder init again from the same directory to overwrite them.

The .env file contains your API access token. Keep it out of version control and don’t share it.

Create a Blank Widget Template

Widget Builder can generate a blank widget template to start from.

  1. From your ~/widget-templates directory, run the following command to scaffold a new widget template:
widget-builder create product-grid

This creates a ./product-grid directory containing three files:

  • schema.json holds the widget template’s schema
  • config.json holds sample configuration values used by the local preview
  • widget.html holds the widget template’s markup

Widget Builder also opens a live preview of the starter template in your browser at http://localhost:8080. Leave this running — the preview refreshes automatically each time you save a file.

In the next lab, you will edit these files to build a widget template.

To see what a finished template looks like in Widget Builder’s format, browse the static content widget from the earlier lab in the static-image-content directory of the lab repository: