/headstart-nextjs

A starter application built using NextJS and OrderCloud

Primary LanguageTypeScript

Overview

This project showcases a simple buyer application built with Next.js and Sitecore OrderCloud

⚠️ Interested in OrderCloud with NextJS?: Check out OrderCloud's vercel intergration! The guide for installing gives you steps to get a free hosted NextJS storefront in 5 minutes.

Demo

Link to demo

Log in with either buyer01 or buyer02. Password for both is Password1234!

Currently complete (or partially complete) features

  • Automatic Anonymous Authentication
  • Registered User Login
    • Automatic Anonymous Order Transfer
    • Refreh Tokens / Remember Me
  • Product List
    • Product Cache
    • Product Card
    • Faceted Search
  • Product Detail
    • Dynamic Spec Forms
    • Quantity Input
    • Add to Cart
  • Cart
    • LineItem List
    • LineItem Card
    • Edit/Remove LineItem
    • Order Summary
  • Checkout
    • Order Summary
    • Address Book
    • One time addresses
    • Shipping Estimates (placeholder integration)
    • Select Ship Methods
    • Calculate Order (placeholder tax integration)
    • Split Payments (purchase order only)
    • Order Submit
    • Order Confirmation

Getting Started

Configure your application by creating a new .env file at the root of your project and fill it in with details from your OrderCloud organization.

NEXT_PUBLIC_OC_CLIENT_ID=YOUR_BUYER_CLIENT_ID_HERE
NEXT_PUBLIC_OC_SCOPE=Shopper,MeAddressAdmin
NEXT_PUBLIC_OC_BASE_API_URL=https://sandboxapi.ordercloud.io
NEXT_PUBLIC_OC_ALLOW_ANONYMOUS=false
OC_WEBHOOK_HASH_KEY=HASH_KEY_FROM_CHECKOUT_INTEGRATION_EVENT

The API client defined by NEXT_PUBLIC_OC_CLIENT_ID should:

  • Allow buyer users (apiClient.AllowAnyBuyer = true)
  • Not have a client secret (apiClient.ClientSecret = null)
  • Optionally be configured for anonymous shopping (if you want to allow anonymous by setting NEXT_PUBLIC_OC_ALLOW_ANONYMOUS=true)
    • apiClient.IsAnonBuyer = true
    • apiClient.DefaultContextUserName set to the username of a valid buyer user

In order to submit an order you must do the following:

  1. Create a checkout integration event
    • Set CustomImplementationUrl to your_hosted_app_url/api/checkout
    • Set a Hashkey (this should be set to environment variable OC_WEBHOOK_HASH_KEY)
  2. Update Buyer ApiClient.IntegrationEventHashKey with the ID of the integration event from step 1.
  3. Deploy the application. Checkout won't work until the app is deployed because OrderCloud needs to call out to publicly accessible endpoints

First, run the development server:

npm run dev
# or
yarn dev

Open http://localhost:3000 with your browser to see the result.

You can start editing the page by modifying pages/index.js. The page auto-updates as you edit the file.

API routes can be accessed on http://localhost:3000/api/hello. This endpoint can be edited in pages/api/hello.js.

The pages/api directory is mapped to /api/*. Files in this directory are treated as API routes instead of React pages.

OrderCloud

The ./ordercloud folder contains everything that may one day become an installable package. It uses react-redux / @redux/toolkit for every interaction with the OrderCloud API. In later releases we plan on eliminating the dependency on react-redux in favor of vanilla redux.

This folder follows a general pattern:

  • ./ordercloud/redux/REDUCER_NAME/index.ts - This is where we use createSlice to build up the reducer and asyncThunk actions. Some folders contain separate action files to help organize the code.
  • ./ordercloud/hooks/useReducerName.ts - Some reducers come with their own React Hook to make interacting with OrderCloud data easier when developing individual components. Not all hooks are directly related to a single reducer, some use more than one reducer state to accomplish tasks.
  • ./ordercloud/components/ComponentName.tsx - React components that take advantage of our application store through the useSelector hook. They also might make use of our custom React hooks which live inside the ./lib folder. Some of them dispatch actions that live in the ./redux folder using the useDispatch hook.
  • ./ordercloud/utils/utilityName.ts - Helper functions that enhance the javascript development experience with OrderCloud.

NextJS and Pages

This project is built in NextJS, meaning that it requires specific files within ./pages to actually render components. There are a few pages included that utilize the next/router to access a query and provide information to a component - which in turn provides information to a hook or action that finally interacts with the OrderCloud API. By separating these concerns, we will be able to extract our React components and Redux logic into installable libraries that can be used in a vanilla React application (sans NextJS).

Future State

We will be separating items in the ./ordercloud folder into NPM packages. As of the time of writing this, we are thinking the packages will look something like this:

  • ./ordercloud/redux => @ordercloud/redux - A frontend framework agnostic library built on Redux / @redux/toolkit that handles data management & interaction with the OrderCloud API using the ordercloud-javascript-sdk.
  • ./ordercloud/components, .ordercloud/hooks => @ordercloud/react - A library of components, hooks, and other React specific utilities that can be used in vanilla React applications as well as frameworks built on top of React, like Next.js.
  • ./ordercloud/utils => @ordercloud/javascript-catalyst - A library of utilities and types that will help make building OrderCloud web applications faster and easier.

Learn More

To learn more about Next.js, take a look at the following resources:

You can check out the Next.js GitHub repository - your feedback and contributions are welcome!

Deploy on Vercel

The easiest way to deploy your Next.js app is to use the Vercel Platform from the creators of Next.js.

Check out our Next.js deployment documentation for more details.