Guide to integrating Commerce.js

Introduction

In 2019, global retail eCommerce sales shot to a staggering 3.5 trillion USD and are projected to almost double by 2022. At this rate, innovation and the need for progressive software for developers to leverage will continue to grow. There is certainly no slowing down the global eCommerce industry, and as a Junior Developer entering the space, it is an exciting avenue to jump into and learn.

I have recently started my journey as a Junior Front-end Developer and Designer at Chec/Commerce.js. Chec/Commerce.js is an API-first eCommerce platform geared towards developers, designers, and businesses to create custom eCommerce experiences on, web, mobile, and beyond.

Being in a startup with a small core team, I have the privilege of being able to jump in on various aspects of design and development and learn from all the team members. Because building an incredible developer experience is always at the forefront of Commerce.js, I build integrations with Commerce.js and contribute with continuous improvement on the documentation, guides, and resources. Other days, I’ll design marketing assets or help to engage and define our developer community.

There is certainly no better time to enter the eCommerce industry as there is continuous innovation in the space with endless learning and growth opportunities.

In this article I’ll be introducing some basic eCommerce concepts and guiding fellow junior developers through a basic integration with Commerce.js.

To skip straight to the integration guide, go here Getting Started

What is headless eCommerce?

The industry has shifted from a traditional eCommerce concept and unanimously opted for a better and more efficient method to building web stores. You may have heard the fairly new coined term “headless” eCommerce. What exactly does it mean to take a “headless” approach to building eCommerce solutions?

Headless eCommerce is anything but the traditional way of building a web store. Traditional platforms come packaged as robust, monolithic solutions that bind you to its ecosystem. Within this walled-environment, you are strapped to use a specific tool, platform, and technology stack.

On the other hand, “headless” figuratively means cutting off the front-end presentation layer so that you can take an autonomous approach to fetch your backend data separately and display it with the front-end language or framework of your choice. With a headless / serverless approach, the API is treated as a “first-class citizen” in this ecosystem, where the first point-of-contact your users will encounter is the API.

This is truly exciting, as for the first time, this approach takes away the abstraction and complexity of having to roll your own solution. A junior developer is able to come into a headless eCommerce project with the know-how to simply start making requests to the API backend to fetch data, and output the data with their language or framework of choice. Ultimately, developers with no eCommerce experience can learn to create custom purchasing flows, unique brand experiences, and complete eCommerce businesses.

As a junior developer, why should you tackle a headless eCommerce project?

Being a newcomer in today’s industry can sure be overwhelming with the endless influx of information, technologies, and “best practices” to implement your projects.

When I was going through my Web Development program in a technical institute, my first foray into eCommerce was injecting WooCommerce as a plugin onto a WordPress website. I remember thinking there must be an easier and more intuitive way of handling eCommerce functionalities. The first I had heard of a headless eCommerce platform is through Chec/Commerce.js.

Within the first week, I was able to try my hand at building a basic single page eCommerce app with Commerce.js . This project was built with a product catalogue, a cart and checkout feature, all without writing any backend code. I was able to strictly stay in the front-end space by designing a simple storefront UI and develop it.

From this project alone, I learned about the concepts of API, how to use an SDK to fetch your data, JAMstack project architecture, asynchronous programming, and application state management.

With a headless approach, building an eCommerce project can truly and feasibly be a one-man’s job, whereas a whole backend and front-end team would be needed for a monolithic or roll-your-own solution.

The points below are why I believe any Junior Developer should learn modern front-end development by building a headless eCommerce project:

1. Understanding of JAMstack

• Learn how to build a JAMstack project, a modern project architecture to progressively handle data.

2. Ability to build on various touchpoints

• Ever wanted to learn how to build a Progressive Web App (PWA)? A PWA is a browser-based app mimicking a native app. Learn by integrating Commerce.js easily with a PWA tool!

3. Learn a new framework while you're at it

• Learn today’s most popular frameworks, Reactjs or Vuejs by integrating it with Commerce.js

4. Building a real-world project

• With the eCommerce industry’s continuous growth, you learn to build a real-world project. Globally, there are currently 12-24 million eCommerce stores online, be a part of this growth!

5. Take ownership of the project at hand

• Headless eCommerce project can be a one man’s job. Are you a student? A freelance designer or developer? Seize the opportunity to take full ownership of a web project by building it with a headless eCommerce tool.

What is Chec and Commerce.js?

Commerce.js was created to communicate with Chec, a lightweight API where your data is being stored on the backend. The Chec platform comes with a prebuilt merchant dashboard for managing your products and inventory. Both Chec and Commerce.js are aimed at developers and designers to create custom seamless eCommerce solutions that can easily integrate with any modern tool.

Being an API-first eCommerce tool, Commerce.js enables companies to divide capabilities into separate, autonomous services such as microservices. Building applications based on microservices helps in ensuring good UX with different devices and platforms.

I’ve always thought the best way to learn anything new is to learn through building a real-world project. Joining Chec/Commerce.js as a Junior Developer gave me the opportunity to build integrations with an API-first platform and using the Commerce.js SDK to easily communicate with the backend data. The Commerce.js documentation is continuously refined to improve developer experience of all levels. Throughout the docs are high-level ideas, tool tips and glossary terms, so that you’re learning fundamentals and concepts as you go along with your integration project.

What exactly makes Commerce.js different?

1. Developers and designers building tools for developers and designers

• Satisfies and targets pain points we have all faced as developers and designers ourselves.

2. Empathetic product built from the ground up

• As developers and businesses owners ourselves, we’ve been there. We’re creating the best merchant and developer experience to suit a broad spectrum of skill levels and business types, because one size, doesn’t fit all when it comes to eCommerce.

3. Well-documented API

• For an API to be consumed by developers, it needs to be well-documented. The Commerce.js documentation is written with this in mind, structured out with a set of patterns that we, as developers, would naturally ask for such as URLs, request methods, headers, and request parameters.

4. Time to live

• With Commerce.js, developers and designers can take a concept and go live in a matter of days. The Chec platform even has hosted checkouts and storefronts (that require no coding) that you can use to validate ideas before diving into an integration.

5. Well-designed API

• Commerce.s is the only eCommerce API that provides logic and helper functions for you to handle the functionalities of the complete eCommerce lifecycle: Before the checkout (pre-capture), during the checkout, after the checkout (post-capture).

6. Integrate anywhere

• Commerce.js can be integrated into any front end framework, platform or device, making it an incredibly extendable eCommerce tool. As Commerce.js is pre-integrated with modern payment gateways, you can just focus on the eCommerce functionality and making it work with other microservices.

7. Developer experience

• Commerce.js comes with built-in helper functions to help with common checks and functionalities such as “Is this variant available for this order?” These helper functions are built in anticipating common questions and eliminating having to build them manually.

Let’s start building our first eCommerce project with Commerce.js!

All it takes to build your first Commerce.js integration are a few key steps.

Prerequisites

This project assumes you have some knowledge of the below concepts before starting:

• Some basic knowledge of JavaScript
• Some knowledge of JavaScript frameworks
• An idea of the JAMstack architecture and how APIs work

What you will need to start this project

• An IDE or code editor
• NodeJS, at least v8/10
• npm or yarn

Front-end and Backend tools

Because the front-end presentation layer is completely decoupled from the backend logic, you are free to choose your modern front-end tool or other backend systems to integrate with:

• Modern front-end frameworks: VueJS, ReactJS, or Angular
• Static site generators like GatsbyJS or Gridsome
• CMS: Contentful or Cosmic.js for CMS’s
• PIM — Product Information Management for product marketing data

Getting started

Sign up for your Chec account

• To start building your eCommerce storefront, we first need to get you up and running with a Chec account.

Upload your products

• In order to build an eCommerce website, you'd need some data to work with like products and product details. So once you've set up your account, let's log in and start uploading our products!

Set up your project on the command line

If you prefer to use a command line interface for your Chec project, manage your backend, or scaffold an example demo store, we have a Chec CLI to rapidly help with the setup. The Chec CLI can be globally installed via npm, can provides the chec command in your terminal.

To install the Chec CLI, run the below commands:

    $ npm install -g @chec/cli
    $ chec COMMAND
    running command...
    $ chec (-v|--version|version)
    @chec/cli/1.0.0 darwin-x64 node-v10.16.3
    $ chec --help [COMMAND]
    USAGE
      $ chec COMMAND
    ...

After installation, you now have all these commands at your disposal for swift development and management of your Chec project:

• chec demo-store [STORE] [TARGETDIRECTORY]
• chec help [COMMAND]
• chec log LOGID
• chec login
• chec logout
• chec logs
• chec register
• chec request METHOD RESOURCE [PAYLOAD]
• chec whoami

To read up more on the usage of these commands, go here.

Project setup

After you have chosen your front-end application language or framework and have it set up in your local environment, we will now go ahead and install Commerce.js.

Inject the Commerce.js logic layer

After setting up your project environment, lets inject the Commerce.js logic. We need to install the Commerce.js SDK to communicate with the Chec API and fetch data from the backend.

npm install @chec/commerce.js

Now we need to link up our Chec store to our project. To do so, we need to create a new Commerce instance and pass in our public API key (grab your public key from your Chec dashboard).

// Import Commerce.js as a dependency
import Commerce from '@chec/commerce.js'

// Initialize store with public key and store key in variable
// Commerce also accepts a second argument 'true', enabling the Commerce.js console debugger

const commerce = new Commerce('ENTER YOUR PUBLIC KEY HERE', true)

Make requests to fetch data from Chec

Commerce.js was built with all the front-end functionalities you would need to build a complete eCommerce store. All you need to do is make requests to various Chec API endpoints, receive successful responses, then you have your raw data to output beautifully onto your web store.

For instance, you may want to retrieve and list all your products in your product catalogue page. From your commerce object, you can access your products like so:

commerce.products.list().then((result) => {
  console.log(result.data.map((product) => product.name))
})

The response you get from the request above will console log your product data.

These are what we have accomplished here so far:

1. Chec store set up
2. Installed Commerce.js SDK to communicate with the Chec API
3. Created a new Commerce instance and passed in your public API key to connect to your Chec store
4. Made a request to commerce product object property to list out your product data.

The whole idea of an API-first eCommerce platform is to make asynchronous calls to data when needed. Through your whole application, you will be making requests to endpoints to handle the full eCommerce logical flow.

Next steps would be to:

1. Parse out your data and populate your product catalogue view with the product media, metadata, variants, options, conditionals, and prices.
2. Fetch your cart by using the retrieve method on your cart object commerce.cart.retrieve()
3. Add products to your cart with the commerce.cart.add method.
4. Create a checkout token with commerce.cart.generateToken and capture your checkout with commerce.checkout.capture.

For the full guide on building an eCommerce product catalogue, check out this guide. If you would like a more comprehensive tutorial on building the full checkout process, have a go at this tutorial!

As a Junior Developer who came from primarily a design background, I’ve been delighted with how simple using Commerce.js is. Entering front-end development in today’s industry can seem mind-boggling with endless tools and not enough guidance on how best to use them. Commerce.js is truly a developer tool that is working hard on the ground to eliminate pain points and is aimed at letting you get your hands dirty on learning and growing your skillset.

We encourage you to check out our documentation, resources, and blogs below.

commercejs.com/docs/getting-started commercejs.com/resources blog.commercejs.com

We’re excited to be on this journey with you to build your first Commerce.js integration! Please join our community on slack, share your projects with us, or ask us any questions you have!

Join our community here!