commercelayer/demo-store

Demo Store is a completely static ecommerce solution (with SSR capability) powered by Commerce Layer.

Commerce Layer Demo Store

This Demo Store is a completely static ecommerce solution (with SSR capability) powered by Commerce Layer. The store is full-featured and fully operational, with no third-party services required. You can easily tailor your own with different levels of customization. Keep reading to learn more.

The Demo Store project consists of two repositories, this one is the GitHub template.

What is Commerce Layer?

Commerce Layer is a multi-market commerce API and order management system that lets you add global shopping capabilities to any website, mobile app, chatbot, wearable, voice, or IoT device, with ease. Compose your stack with the best-of-breed tools you already mastered and love. Make any experience shoppable, anywhere, through a blazing-fast, enterprise-grade, and secure API.

Table of contents

• Features
• How it works
• Getting started
• Customization
• Deploy
• Need help?
• Troubleshooting
• License

Features

We decided to build the Demo Store removing all third-party services that are usually used to create a comprehensive ecommerce website experience (CMS, search, PIM, etc.).

Everything related to content is stored as JSON files. To build your own Demo Store you will need to create these files manually or via scripts.

The Demo Store comes with:

• a built-in search engine with facet search powered by fuse.js
• a full product catalog management with taxonomies and taxons
• single product variants management
• multi-language capabilities to make selling internationally easier
• the whole extensive set of features provided out of the box by Commerce Layer APIs (multiple currency price lists, inventory models that support multiple stock locations and fulfillment strategies, market-specific payment gateways, delivery options and carrier accounts, etc.)

The integration with Commerce Layer is achieved by leveraging some of our open-source developer tools, specifically:

• the JS Auth library
• the Javascript SDK
• the React components
• the Hosted cart
• the Hosted checkout

How it works

The Demo Store project consists of two repositories that you can leverage to build your own store, based on the amount of customization you need to add:

• demo-store

  This is a GitHub template that uses the below-mentioned demo-store-core as a git submodule. If you're happy with the features and the look and feel of the Commerce Layer Demo Store we suggest you follow this path. You won't have to care about the whole source code and you'll be free to focus just on your data and content. On top of that, you'll get free updates with almost no risk just by running:

  git submodule update --remote
  npm install

• demo-store-core

  This repository contains the source code. If you need to fully customize your store (behavior, UI, UX, etc.) you just have to fork this repo and create your own. This is also the way to contribute.

  ⚠️ Please note that if you follow this path and start diverging too much from the original source code the risk is to lose all future updates or not be able to replicate them.

Getting started

If you have no experience with Commerce Layer, you can start by creating an account (it's free!) and following the onboarding tutorial.

Important

Please note that to set up a Demo Store you need a properly configured organization with at least a few products and one market.

If you prefer to start from scratch, you can create a new organization and use the following commands to configure a Commerce Layer's Demo Store-like project.

Setting up your organization

Once the organization is created, you need to create two API clients: a sales channel and an integration.

If you haven't yet, install the Commerce Layer CLI and two of its plugins: the seeder plugin and the imports plugin:

npm install -g @commercelayer/cli

commercelayer plugins:install seeder
commercelayer plugins:install imports

Now you can log in to your integration API client from the CLI:

commercelayer applications:login \
  --clientId Oy5F2TbPYhOZsxy1tQd9ZVZ... \
  --clientSecret 1ZHNJUgn_1lh1mel06gGDqa... \
  --organization my-awesome-organization \
  --alias cli-admin

Building your store

Once your organization is set up, to build you store you need to follow some simple steps... let's get started!

1. Create a new repository

Whichever path you choose, first of all, you need to create a new repository for your store:

• If you decided to keep the demo-store template you just need to click on the "Use this template" from the repository homepage on GitHub and then run:

  git clone <your-repository-url> my-new-project
  cd my-new-project
  git submodule update --init
  npm install
  
  cp ./demo-store-core/packages/website/.env.sample.submodule .env.local
  
  cp -r ./demo-store-core/packages/website/data/json ./data/json

• If you decided to fork the demo-store-core repository you can run this instead:

  git clone <your-repository-url> my-new-project
  cd my-new-project
  npm install
  
  cp ./packages/website/.env.sample ./packages/website/.env.local

2. Set the environment variables

Edit .env.local and fill in all the missing information:

# this is the 'sales channel' client id
NEXT_PUBLIC_CL_CLIENT_ID=er34TWFcd24RFI8KJ52Ws6q...

3. Seed the data

ℹ️ This step is optional. If you already have a properly configured organization on your Commerce Layer account, you can skip it.

The following script will populate your organization with all the resources you need to build a multi-market ecommerce with Commerce Layer (the ones we are using for our Demo Store).

npm run seeder:seed -ws --if-present

If the command above executes with no errors, please skip to step 4. Otherwise, you can still seed your organization with sample data using the CLI by running the following:

commercelayer seeder:seed -b custom -n demo_store_full -u ./demo-store-core/packages/setup/

4. Choose the countries where you're going to sell

The json/countries.json file contains a list of available countries for your ecommerce. You can change it with your preferred editor. Just make sure to replace all findings of "market": xxx with the related markets of your organization. You can get the list of your markets from the Commerce Layer admin dashboard or by running this command:

npm run markets -ws --if-present

5. See it in action 🚀

npm run dev

# http://localhost:3000/

Managing updates

You can always find the latest code of the demo-store-core in its main branch.

To update your Demo Store to the latest changes you can simply run:

git submodule update --remote
npm install

Sometimes can happen that a new major version contains breaking changes. In this case, by updating to the latest, your Demo Store could stop working and you'll need to manually solve all the issues by following the release notes.

If you like, you can receive a GitHub notification as soon a new version is released.

Customization

When you're using our Demo Store template you can customize three main elements: content data, locales, and configuration files.

⚠️  We're going to continuously improve our Demo Store to add new features and optimize the existing ones. When you update to the latest release, the build could fail. Take a look at the release notes to understand how to fix it by updating your customized files.

JSON data files

As mentioned earlier, our Demo Store is built around a set of data that are stored as JSON files, to decouple it from any third-party services. To build your store you'll have to create and manage these files.

JSON files are located at data/json/, but you can choose a different position by changing the environment variable NEXT_PUBLIC_JSON_DATA_FOLDER.

Type-definition files are located at packages/types/src/json/. We are using zod for schema validation. Take a look at these files to understand which structure you have to follow.

When you are done with all the changes you can check if everything is correct by running:

npm run test:data

Locale data files

Our Demo Store is a multi-language website. When you built your data in the previous step, you probably noticed that some fields were localized. You can add new languages or change existing translations.

Locale JSON files are located at data/locales/, but you can choose a different position by changing the environment variable NEXT_PUBLIC_LOCALES_DATA_FOLDER.

Do as follows to start customizing the locales:

cp -r ./demo-store-core/packages/website/data/locales ./data/locales

# .env.local
NEXT_PUBLIC_LOCALES_DATA_FOLDER=../../../data/locales/

Configuration files

Configuration files are located at config/, but you can choose a different position by changing the environment variable NEXT_PUBLIC_CONFIG_FOLDER.

There are three configuration files that you can manage:

• general.config.js
  This file contains the general configuration.

• facets.config.js
  This is the facets configuration file. You can choose the order in which they are displayed in the filter panel, their appearance, and the sorting rules of their values.
  

• variants.config.js
  This is the variants configuration file. You can choose the order in which they are displayed on the product detail page and their appearance.
  

Do as follows to start customizing the configuration:

cp -r ./demo-store-core/packages/website/config ./config

# .env.local
NEXT_PUBLIC_CONFIG_FOLDER=../../../config/

Additional environment variables

There are some environment variables that you can use to customize your store. For an exhaustive list and description, you can take a look at additional-env.d.ts file.

Deploy

You can deploy the Demo Store wherever you prefer. You just need to:

1. Set all the environment variables in the system that you'll use to run the build, according to your needs.
2. Decide if you want to go with static site generation or server-side rendering.

ℹ️ The Demo Store is designed to be SSG first and foremost, but you can switch to SSR in a snap. We tested some ways to deploy it (e.g. using GitHub Workflow, Netlify, Vercel, etc.) and you can find more information about it here. If you did it differently or used other services and you want to share the steps with the community, please join the discussion, and thanks in advance!

Static site generation

To build and deploy the Demo Store:

1. Set the following environment variable accordingly:

   NEXT_PUBLIC_DATA_FETCHING=ssg

2. Run npm run build to create a statically optimized production build of your application.

3. Copy the folder demo-store-core/packages/website/out to your preferred static hosting.

Server-side rendering

The Demo Store can be deployed to any hosting provider that supports Node.js. To do that:

1. Set the following environment variable accordingly:

   NEXT_PUBLIC_DATA_FETCHING=ssr

2. Run npm run build to create an optimized production build of your application.

3. Run npm start to start the Node.js server in production mode.

Need help?

• Join Commerce Layer's Discord community.
• Open a new Q&A discussion
• Ping us on Bluesky, X (formerly Twitter), or LinkedIn.
• Is there a bug? Create an issue on this repository.

Troubleshooting

1. Q. Even if I changed NEXT_PUBLIC_JSON_DATA_FOLDER, NEXT_PUBLIC_LOCALE_DATA_FOLDER or NEXT_PUBLIC_CONFIG_FOLDER, the website is still referring to previous files.

   A. These environment variables are used as alias in Webpack. Starting from Webpack 5, caching for faster builds has been introduced. Changing these environment variables will not invalidate the Webpack cache. You have to remove .next folder manually or by running:

   # update the path if needed
   rm -rf demo-store-core/packages/website/.next/

License

This repository is published under the MIT license.