Welcome to the Sitecore Headstart React Admin, an open-source admin application for Sitecore OrderCloud built with React. Whether you're looking to explore how admin applications are constructed or kickstart your own custom solution, this project provides a valuable resource.
Important Note: This application is intended for demonstration and learning purposes and is not production-ready.
OrderCloud is a versatile commerce and marketplace development platform, offering limitless customizations and API-first, headless eCommerce architecture
The Sitecore Headstart React Admin application is a powerful and flexible tool built on top of the Sitecore OrderCloud API and Javascript SDK. It utilizes:
- React
- Next.JS
- Typescript
- Chakra UI
- Various toolings for linting, formatting, and conventions
These are the currently implemented features:
- Admin products including products, product facets, prices, and catalogs (both as admin users and suppliers)
- Admin promotions
- Admin buyers including users and usergroups
- Admin suppliers including users, usergroups, and addresses
- Admin and assign security profiles (controls visibility of admin applciation)
- Fulfill orders - including managing orders and order returns
Check out our roadmap for upcoming features
An OrderCloud Marketplace (https://portal.ordercloud.io) with the following (minimum):
- An admin api client without client secret defined
- An admin user with the correct permissions (or FullAccess)
Using the Deploy Button below, you'll deploy on Vercel the Next.js project as well as connect it to your Sitecore Commerce OrderCloud Marketplace.
- Using this repository as a template, create a new repository.
- Clone your new repository locally
- Copy the
.env.local.examplefile in the root directory to.env.local(ignored by default during your next Git commit):
# Copy the template .env.local.example to .env.local
cp .env.local.example .env.localThen set each variable on .env.local:
| Variable | Description |
|---|---|
NEXT_PUBLIC_APP_NAME |
Name of the application title used on page title |
NEXT_PUBLIC_OC_CLIENT_ID |
Admin Client ID |
NEXT_PUBLIC_OC_API_URL |
Base OrderCloud API URL (varies based on region/environment check portal) |
NEXT_PUBLIC_OC_MARKETPLACE_ID |
The ID for your OrderCloud Marketplace |
NEXT_PUBLIC_OC_MARKETPLACE_NAME |
The name for your OrderCloud Marketplace |
NEXT_PUBLIC_THEME_COLOR_PRIMARY |
The primary theme color hex code (optional) |
NEXT_PUBLIC_THEME_COLOR_SECONDARY |
The secondary theme color hex code (optional) |
NEXT_PUBLIC_THEME_COLOR_ACCENT |
The accent theme color hex code (optional) |
NEXT_PUBLIC_THEME_FONT_HEADING |
The font used for heading text (optional) must be one of the available google fonts |
NEXT_PUBLIC_THEME_FONT_BODY |
The font used for body text (optional) must be one of the available google fonts |
NEXT_PUBLIC_THEME_LOGO_URL |
The URL to your logo (optional) |
Your .env.local file should look something like this:
NEXT_PUBLIC_APP_NAME='Sitecore Commerce Admin App'
NEXT_PUBLIC_OC_CLIENT_ID='****0BAC-****-4711-B01F-1A**4F7*****'
NEXT_PUBLIC_OC_API_URL='https://sandboxapi.ordercloud.io'
NEXT_PUBLIC_OC_MARKETPLACE_ID='SitecoreCommerce'
NEXT_PUBLIC_OC_MARKETPLACE_NAME='Sitecore Commerce'- Run Next.js in development mode
npm install
npm run devYour app should be up and running on http://localhost:3000!
There are scenarios where having your own marketplace becomes essential. Whether you're initiating a new project, creating data for a specific workflow, or safeguarding against unwanted data changes before a demo, we've simplified the process for you. Our application includes a convenient command-line feature for generating two types of marketplaces.
The first option is a minimal marketplace, featuring only the essential configurations such as API Clients, security profiles, and initial login details. We recommend choosing this option when you are starting a new project, providing a streamlined foundation to build upon.
To generate a minimal marketplace, run the following command:
npm run seed-minimal -- -u=YOUR_PORTAL_USERNAME -p=YOUR_PORTAL_PASSWORD -n=YOUR_MARKETPLACE_NAMEThe second option crafts a B2C-style marketplace, pre-populated with products from the PlayShop demo. Opt for this option to quickly explore the capabilities of the admin application without the need to manually set up extensive data. This option is particularly handy for demo purposes.
To generate a B2C-style marketplace with PlayShop demo data, run the following command:
npm run seed-playshop -- -u=YOUR_PORTAL_USERNAME -p=YOUR_PORTAL_PASSWORD -n=YOUR_MARKETPLACE_NAMEAfter generating the marketplace, complete the setup by filling out your .env.local file with the relevant information from your newly created marketplace. You can then run the application locally by executing:
npm run devLog in as initialadminuser with the password Testingsetup123! to explore the functionalities of the admin application. When creating new admin users, ensure you assign them a security profile for proper access.
These options empower you to kickstart your projects or explore the application's capabilities effortlessly.
This project uses Jest for unit testing. To write a unit test:
- Create a file under either test/components or tests/pages that ends in .test.tsx (so it gets picked up by test runner)
- Write your unit test
- Run unit tests by running the command
npm test
To deploy your local project to Vercel, push it to public GitHub/GitLab/Bitbucket repository then import to Vercel.
Check out the Discussion board. You ask questions or suggest answers in our Q&A board.
Check out our Contributing guide.
Changes from release-to-release are tracked in the Changelog wiki page.
Larger roadmap items are outlined in the project milestones
- OrderCloud Javascript SDK
- OrderCloud API Reference
- Next.js Documentation - learn about Next.js features and API.
- Learn Next.js - an interactive Next.js tutorial.
- Chakra UI
- TypeScript