Broadleaf Microservices
Commerce Next.js Starter


The Commerce Next.js Starter is designed to provide a reference for how to implement a frontend storefront using Broadleaf Microservices as the backend. It can also be used as a starting point for your own implementation.

It is based on React and Next.js It includes a variety of components, hooks, constants, and utils out-of-box to help get your storefront implementation started. We also make use of our own SDKs for interacting with the commerce-facing REST APIs and the Auth APIs. Finally, it supports both client-side and server-side rendering.

System Requirements

  • yarn: ≥ v1.22.0

  • Node: ≥ v14.16.1

If you don’t have Node at all yet: Download it from Otherwise, if you are on an older version of node, try installing n or nvm to manage your node versions.

Authenticate with Broadleaf’s NPM Repo

The following assumes you have obtained credentials outlined in the guide: Getting Started Locally.
  • Use npm login to authenticate with the registry:

npm login --registry=
There is a bug with npm version 5.6 and creating an auth token in the next step. If you are running npm version 5.6 (npm --version), it is suggested you upgrade to the latest (sudo npm i -g npm).

This will modify your ~/.npmrc file with a token used for authenticating with the registry.

  • Ensure that the @broadleaf scope uses this npm registry:

npm config set @broadleaf:registry

Backend Options

We recommend following the Frontend Walkthrough Tutorials as a primer to understanding how the Next.JS Storefront Starter code is structure.

In order to get the frontend storefront working locally, you need to point it to a working backend.

Developer Demo Environment Backend

The easiest and quickest way to do this is to point your project to a provisioned developer demo environment. This developer sandbox environment is your own, has dedicated APIs, and any data changes you make to it from your sandbox admin console are persisted. Sign up for a sandbox developer environment here.

Once you have your provisioned environment, you can configure your project to point to the APIs.

Your configuration will look something like this (replacing demo123abc with the demo instance identifier that was provisioned for you)

More details around how to run and configure additional remote backends are outlined in the README of the starter project.

Local Backend APIs

If you’re needing work with the full stack and need to run the starter against a local backend (e.g. for custom development and debugging), you can configure the .env properties in your projects.



Once you have the above configured, you will want to follow the directions here to run the backend APIs locally.

Starting the App

Install the dependencies
yarn install
To run in dev mode against a remote backend
yarn dev

Then navigate to http://localhost:4000.

To run against a local backend
yarn local