How to build an ecommerce website with Commerce Layer Demo Store.

Prerequisites

1. Some JavaScript, command-line, and API knowledge are required.
2. A working programming IDE.
3. A stable internet connection.
4. Optionally, you can study these data models to understand the key Commerce Layer API entities, their mutual relationships, and common usage.

How it works

The Demo Store project is a static ecommerce solution with no third-party services required, so you can easily tailor your own with different levels of customization. As such, even content is stored as JSON files. The Demo Store comes with:

• A full product catalog management with taxonomies and taxons.
• Single product variants management.
• Multi-language capabilities to make selling internationally easier.
• A built-in search engine with a faceted search (filtered search).
• An 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, carrier accounts, etc.).

In the sections below, I’d show you how to set up and configure your own ecommerce store using the demo store project. Ready? Let’s go!

Get your API credentials

The demo store project is powered by Commerce Layer, Nextjs, TypeScript, and other internal/external tools. You can explore our API resources in these Postman collections to test specific resources and see how they all work. To get started, all requests to Commerce Layer API must be authenticated with an OAuth2 bearer token. You need to execute an authorization flow using a valid application type as the client to get an access token. Each application type has its usage, authentication flow, and permissions. The application type can be authenticated with different authorization grant flows using the available authorization grant types as described in the table below:

Kindly create a Commerce Layer account here, follow the onboarding tutorial to create an organization, and read this guide from our documentation to learn how to create a sales channel and integration application type. When you are done creating them, save your organization slug, base endpoint, and the generated client ID and client secret credential — we will use this to configure the demo store and seed some demo data shortly.

Install and configure the Demo Store

The Demo Store project is a GitHub template that uses the demo-store-core repository as a git submodule. This will retain the features, look, and feel of the default Demo Store. With this, you won't have to care about the whole source code but instead focus on your data/content and easily get free updates with almost no risk just by running the git submodule update --remote && npm install command. Kindly follow the steps below to get started:

1. Select the template

Click on the "Use this template" button from the demo-store's homepage on GitHub as seen in the screenshot below.

2. Clone the forked repository

Run the following commands to clone the forked repository to your local computer and install the required dependencies:

3. Copy the required files

Run the following commands to copy all the required environment variables and data files into your demo store:

4. Add some environment variables

Create a .env.local file and add the following variables, including your previously created sales channel application credentials (client ID and base endpoint):

Seed Organization with Demo Data

To create an ecommerce store, you need to add some commerce resources to your organization. Suppose this is your first time doing something like this. In that case, you can easily seed your organization automatically with demo data and use that to learn about the key commerce resources required. When you’re ready, you can add the actual data for your ecommerce store. Kindly follow the steps below to seed your newly created Commerce Layer organization:

1. Install the Commerce Layer CLI

Install the Commerce Layer CLI using the command (this will give you access to the cl command):

2. Install the required CLI plugins

Install the seeder plugin and the imports plugin using the command:

3. Log into the CLI

Log into the CLI with your previously created integration application credentials like so:

4. Seed your commerce organization

Run the command below to populate your organization with all the resources you need to build a multi-market ecommerce with Commerce Layer (this includes markets, SKUs, prices, inventory, stock locations, etc.):

5. Seed your commerce organization (if the previous step fails)

If the command above fails with errors (usually because of unstable internet), you can seed your organization with sample data using the command like so (but this process will take a bit more time):

6. Setup your market scopes

The data/json/countries.json file contains a list of available countries for your ecommerce store. Choose the countries you want to start with and replace all findings of "market": xxxxx with the valid market scopes from your organization (you can find these in the sales channel application you created earlier).

7. Start the development server

Now, you can start the development server and visit http://localhost:3000 to preview your ecommerce store like so:

You must first select a country when you visit the homepage. When you select the United States, for example, you will be redirected to the http://localhost:3000/en-US/ path, which will return a shopping experience from the United States market in Commerce Layer with English content translations. Changing the language to French, for example, will redirect to a http://localhost:3000/fr-US page. Changing the country to Italy will return a shopping experience from the Europe market in Commerce Layer and redirect to a http://localhost:3000/fr-IT page. You can play around with it for other countries and languages.

This is a fully-functional international ecommerce website with a multi-market setup, facet search, cart, and checkout in just a few minutes and fewer development efforts. Also, if you already have an existing CMS with content, you can still use that to generate the required content JSON file (we will show you how in a follow-up tutorial 😉). Now, you can go ahead and make transactional changes for each market in Commerce Layer, and your demo store will return the right experience to your users. Isn’t this cool?

In the next section, you will learn how to do more by customizing your store and adding more translations, pages, countries, and other commerce resources.

Customizing your Demo Store

The Demo Store project is built around three main data elements stored as JSON files to decouple them from any third-party services you might want to add yourself. To customize your store, you'll have to create and manage these files.

1. The content JSON files are located in the data/json/ directory with different structured text and image content (here is a sample from the finished code).
2. The locale JSON files are located in the data/locales/ directory with a collection of language translation files (here is a sample from the finished code with french and Italian translations).
3. The configuration files are located in the config/ directory with some JS files that change the behavior of search facets and variants swatching for products with multiple variants (which in turn means the existence of multiple SKUs).

When you are done with any change, always ensure to check if everything is correct by running the command:

You can take a look at the finished code to see all the extra pages and translation changes added to the demo conference swag ecommerce website.

Deploying the Demo Store

There are two things you need to do before you deploy your store using your favorite hosting platforms (e.g., Netlify, Vercel, GitHub Pages, Cloudflare Pages, etc.):

1. Add all the environment variables you currently have in .env.local to the deployment service you'll use to run the build.
2. Decide if you want to use static site generation (SSG) or server-side rendering (SSR) in production.

The next sections will outline the steps required for each option.

Static site generation (SSG)

1. Update your .env.local file

Add this in addition to other variables in your env file:

2. Build the website

Run npm run export to create a static optimized production build of your application.

3. Deploy the built website

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

Server-side rendering (SSR)

1. Update your .env.local file

Add this in addition to other variables in your env file:

2. Setup your build directory

Set the output directory in your deployment service to demo-store-core/packages/website/.next.

3. Setup your build command

Set npm run build as your build command to create an optimized production build of your application.

CI/CD Deployment

You can use the same steps and options if you set up CI/CD deployment directly from a GitHub or GitLab repository. For example, you can create a netlify.toml file for Netlify with SSG like so:

Or a vercel.json file for Vercel with SSR like so:

PS: If you use this option, please make sure that your Commerce Layer API credentials are private. The API credentials in the netlify.toml or vercel.json files should only be added to a private repository. You should always add API credentials directly to your deployment service. We added ours to the repository just for educational purposes.

Conclusion

And that’s a wrap!

I hope you’ve found this tutorial useful and have learned how composable commerce and international websites work. Feel free to expand your knowledge by researching more, customizing your ecommerce store, integrating with other third-party services, adding more commerce data to your Commerce Layer organization, and exploring Commerce Layer’s other suite of developer tools. You can go ahead and use this project to start selling conference swags or any products and receive orders for free (courtesy of our free Developer plan) 😃.

We’d also love to see what you build with this, so please feel free to share what you’ve built and let us know what you think about the tutorial in our Slack community or via Twitter @commercelayer!