Development

4 min read

Introducing the Commerce SDK from Broadleaf

Broadleaf

Written by Broadleaf

Published on Jul 28, 2021

SDK Feature Image

We have been hard at work building out the next iteration of our customer storefront using Next.js. But what really drives it is our Commerce SDK. The Commerce SDK provides abstractions for interacting with our customer-facing endpoints, making it easier to interact with our microservice based architecture. This has allowed us to quickly iterate the development of our storefront application.

Jumping to the Project Structure

We structure our project as a monorepo, meaning the SDK resides in one repository but is split into multiple packages. This helps organize the SDK in a single codebase but allows for the publishing of multiple repositories, so that you only import what you need. Our monorepo is broken down into these packages, related by task and underlying micro-service:

  • @broadleaf/commerce-browse: Facilitates search and catalog browse requests
  • @broadleaf/commerce-menu: Facilitates retrieving menus and their hierarchies
  • @broadleaf/commerce-cart: Facilitates cart, checkout, and CSR operations
  • @broadleaf/commerce-personalization: Facilitates retrieving content targeters like a banner
  • @broadleaf/commerce-core: Defines concepts shared across the other packages
  • @broadleaf/commerce-sandbox: Enables preview-on-site functionality
  • @broadleaf/commerce-customer: Facilitates retrieving an authenticated customer’s profile information
  • @broadleaf/commerce-tenant: Enables resolving tenant information, particularly the correct Application instance

Method Nomenclature

Within the packages we have methods that follow a simple naming scheme to easily find the correct method. For example in @broadleaf/commerce-browse, you will see the following:

VerbExampleReturnsComments
list<NOUNS>listProductscollection of itemsRetrieves a collection of items
get<NOUN>getProductretrieved itemRetrieves a single item
create<NOUN>createProductnewly created itemCreates a new item
update<NOUN>updateProductthe updated itemUpdates an existing item
replace<NOUN>replaceProductthe replaced itemReplaces an existing item
delete<NOUN>deleteProductnoneDeletes an existing item
search<NOUN>searchProductthe search result itemsExecutes a search on a collection of items and returns the results

Quick Start

If you would like to jump in you can start by adding one of the modules to your Node app. The following is an example of doing so for the commerce-browse SDK.

Once installed, it’s a matter instantiating the client with the correct Application token and base host URL to start using the client:

Demo application

From the quick start information, we can begin developing applications like a simple paperless menu or kiosk app. At a high level, we are creating an application that just allows for the query of products. Based on this we will be using @broadleaf/commerce-browse. So lets create a simple react app using create-react-app.

Setup

Let’s create the react app (based off of typescript template)

We next have to install our dependencies:

Menu Component

The first component we will need to create is a Menu component that will list the products available. Each product should be shown in another component, Menu Item, that just displays the product information. So we will create two files one called Menu.js and MenuItem.js. let’s create the files (in the src folder):

Next we are going to create the MenuItem component, not the type definition for the Props in which we explicitly expect an object with product that is of the type Product.

We must also then create the Menu Component that will query a category’s products based on the URL, and then display all the products in that category. Note we use React Hooks to manage the state of the component.

All that’s left is to replace the contents of App.tsx with:

In Conclusion

And now we have a simple kiosk menu that can be used in-store to display products. It’s very easy to get started with the Commerce SDK and begin building apps around Broadleaf Commerce. For more tutorials please checkout our DevCentral Frontend Walkthroughs.

Related Resources