Broadleaf Microservices
  • v1.0.0-latest-prod

Commerce Next.js Starter

Overview

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.

Warning
 We use the starter heavily in demos and testing, so it has quite a few features enabled that not all users will find useful including components for various payment gateways. It is recommended to carefully review the code and remove all the extraneous integrations. In the future, we will be slimming down the starter so that users can add in features they want rather than remove ones they don’t.

  • 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: >=1.22.0 and < 2.0.0

    • Untested with v2 or greater

  • Node: 16 or 18

    • Untested with v20

    • Node 14 has reach end-of-life and is not supported any longer.

Tip
 If you don’t have Node at all yet: Download it from nodejs.org. 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

Important
 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=https://repository.broadleafcommerce.com/repository/npm-private/
Note
 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 https://repository.broadleafcommerce.com/repository/npm-private/

Backend Options

Tip
 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)

Important
 Ensure that the existing values for these properties in the .env are replaced with the following or errors will occur on start up. 
NEXT_PUBLIC_AUTH_BASEURL=https://demo123abc.blcdemo.com/auth
NEXT_PUBLIC_AUTH_CLIENTID=demo123abc
# Optionally enable embedded login to have login and registration forms hosted by the next.js app
# rather than redirecting the user to the Auth server.
NEXT_PUBLIC_USE_EMBEDDED_LOGIN=true
# Required when using a Private Demo instance as the backend since it is enabled there.
NEXT_PUBLIC_USE_PKCE=true
NEXT_PUBLIC_TENANT_RESOLVER_APPLICATION_TOKEN=PD_demo123abc
NEXT_PUBLIC_CLIENT_BASE_HOST=https://demo123abc.blcdemo.com
NEXT_PUBLIC_GATEWAY_HOST=https://demo123abc.blcdemo.com
CONTENT_SECURITY_POLICY_CONNECT='self' https://demo123abc.blcdemo.com
CONTENT_SECURITY_POLICY_CHILD='self' https://demo123abc.blcdemo.com
Note
 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.

Note
 These are all listed at the bottom of the .env and can be uncommented there. 
NODE_TLS_REJECT_UNAUTHORIZED=0

NEXT_PUBLIC_AUTH_BASEURL=/auth
NEXT_PUBLIC_CLIENT_BASE_HOST=
NEXT_PUBLIC_GATEWAY_HOST=https://localhost:8456
NEXT_PUBLIC_AUTH_CLIENTMODE=dynamic

NEXT_PUBLIC_API_ORIGIN=https://localhost:8456

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

Troubleshooting

Blank Screen after login with URL param indicating an auth error occurred because of invalid request (missing challenge code)

This likely means that PKCE is enabled on the Auth Server but not in this app. Set NEXT_PUBLIC_USE_PKCE=true.