Composable Images with Cloudinary and BigCommerce

Demola Malomo

The Jamstack architecture has revolutionized how E-commerce platforms are built. It leverages technologies like Pre-rendering, Markups (HTML), and API economy to build platforms that are fast, secure, and easier to scale.

As the popular saying goes, “With great power comes great responsibility”. Jamstack offers a variety of APIs to build different features of an E-commerce platform, and developers are burdened with constant context switching when using and managing the provided APIs.

In this post, we will learn how to deliver composable commerce images in a Next.js application using Cloudinary, BigCommerce, and Uniform.

Technology Overview

Cloudinary is a visual media service we use to upload, store, manage, transform, and deliver images and videos for websites and applications.

BigCommerce is a software as a service company offering retailers and developers a platform to build e-commerce applications.

Uniform is a digital experience platform that supports the composition, delivery, and management of building blocks required to build an application. It allows developers to seamlessly adapt and manage Jamstack technologies like headless content management systems, commerce APIs, and CDNs and deliver it as a single source of truth instead of making multiple requests.

CodeSandbox and Github

We completed this project in a CodeSandbox. Fork it to get started quickly.

The source code is on Github.

Prerequisites

To fully grasp the concepts presented in this tutorial, the following requirements apply:

  • Basic understanding of JavaScript and React
  • Cloudinary account (Create an account here)
  • BigCommerce account. BigCommerce offers a 15-day trial we can leverage
  • Uniform account (Create an account here)

Getting Started

In this post, we will focus on implementations only. The project UI has already been set up.

To get started, we need to clone the project by navigating to the desired directory and running the command below:

1git clone https://github.com/Mr-Malomz/commerce-img.git && cd commerce-img

Running the Project

First, we need to install the project dependencies by running the command below:

1npm i

Then run the project using the command below:

1npm run dev

Image Sourcing and Upload to Cloudinary

With our application up and running, we need to upload sample images for our e-commerce products.

Sample Images

In our Cloudinary dashboard, we uploaded the image by clicking on the Media Library tab, clicking on Upload, selecting the Web Address option, inputting the URL, and finally clicking on the Arrow Button to upload.

After uploading the images, we will see them displayed on the console.

Configuring BigCommerce

Product data upload to BigCommerce Next, we need to upload sample data for our e-commerce products.

Product NameDefault PriceWeight
Hero5002
Pattern 1 active store4502
Pattern 2 active store2702
Pattern 3 active store2702

On the homepage, navigate to the Products menu and click on Add; input the Product Name, Default Price, and Weight, then Save.

Create an API A**ccount Next, we need to create an API account that exposes our products to 3rd party applications. To do this, navigate back to the main menu by clicking on the Product menu, navigate to the Settings menu, scroll to the API section and click on API accounts**.

Click on the Create API account button, input pattern_store as the name, scroll down to the Product section, and select read-only. The permission selected will give 3rd party applications read-only access to our products.

Before we save the settings, we need to create a .env file in the root directory of our application and add the snippet below:

1NEXT_PUBLIC_BIGCOMMERCE_STORE_HASH=/YOUR STORE HASH HERE/
2NEXT_PUBLIC_BIGCOMMERCE_TOKEN=/YOUR ACCESS TOKEN HERE/

By scrolling up to the API path and copying the characters after /stores/ and before the /v3/ , we can get our Store Hash.

Finally, we can click on the Save button. The application will reveal and download our Access Token and other credentials on save. We can copy the Access Token and update the .env file.

Putting it all Together on Uniform

With our images and product data uploaded, we need to unify them and create a seamless digital experience using Uniform. To do this, we must sign up and fill in the required information.

Next, input commerce_image as the project name and click Continue.

Next, navigate to the Security tab, select the API Keys, and click on the rounded Plus Icon to create one. Input patter_store as the API name, click on Add to Project, mark all the permissions, and click on Set Permissions. Then click on the Create API Key to create the API key

With this done, we should see a screen containing our API Key and Project ID. The .env file needs to be updated with these parameters, as shown in the screenshot below.

Updated .env

1NEXT_PUBLIC_BIGCOMMERCE_STORE_HASH=/YOUR STORE HASH HERE/
2NEXT_PUBLIC_BIGCOMMERCE_TOKEN=/YOUR ACCESS TOKEN HERE/
3NEXT_PUBLIC_API_KEY=/YOUR API KEY GOES HERE/
4NEXT_PUBLIC_PROJECT_ID=/PROJECT ID GOES/

Add BigCommerce and Cloudinary I**ntegration** S**upport Uniform improves the product’s digital experience through integration with an existing system. To connect BigCommerce and Cloudinary to our project, we need to navigate to the Projects tab, click on the project, and click on any of the highlighted sections to add integrations** to our project.

Search or browse through the available integrations, select the BigCommerce integration, click on the Add to project button, input the Store Hash and API Token we added to our .env file earlier, and Save.

Following the same step as above, we must navigate to the All Integration tab, and add Cloudinary to our project.

We can get our Cloud Name **and API Key** from our Cloudinary dashboard.

Understanding Components and Compositions on Uniform Before we start modeling our project on Uniform, it’s paramount we understand the features we will be leveraging to achieve this. Components in Uniform application work similarly to those in a React application; it lets us break our application into smaller reusable building blocks with properties, while a Composition is the combination of one or more components. For our project, we will create an Item component with an img and details properties.

To get started, navigate to the Canvas tab, select the Component Library, and click on the Plus Icon.

Parameter NameHelp TextType
imgitem imageCloudinary
detailsitem detailsBigCommerce Product

Input Item as the component, Add properties of img and details as shown above, and then click on OK.

Then click on the Save and Close button.

Now that we have created the Item Component, it will serve as a blueprint for creating other components for our e-commerce product.

With that done, we can leverage the Item blueprint component to create our e-commerce landing page component. To get started, click on the Plus Icon, input EcommItem as the component name, check the Composition Component, navigate to the Slots section, and click on the Plus Icon to create a slot.

*PS**: Slots help us create instances of our component (4 in our case) and allow them to accept data dynamically.*

Input EcomProduct as the Slot Name, 0 as the Minimum, 4 as the Minimum (The hero section and the remaining 3 product features), select the Item component as the allowed component, and click OK.

Then click on the Save and Close button.

With that done, we can start using the EcommProduct component to compose our e-commerce landing page. To do this, navigate to the Composition tab, and click on the Plus Icon to create a composition.

Select the EcommItem as the composition type, input EcommPage as the name, and Create.

Input homepage as the slug and click on the Plus Icon to add a component to our EcommPage

*PS**: The slug inputted will come in handy when searching for our composition.*

Select the Item component, add the matching image from Cloudinary, and the product data from BigCommerce.

We need to repeat the steps above to add the remaining products. Then click on Save and Publish option.

Finally, we need to navigate back to the Canvas tab and click on the Publish button. This makes our composition available to third-party applications.

Integrating Uniform with Next.js

First, we need to install the required dependencies by running the command below:

1npm i @uniformdev/canvas @uniformdev/canvas-bigcommerce

Add an Enhancer Enhancers in Uniform are a system used to control the layout of data sent through compositions. Basically, it gives us the power to ask for the exact data needed. To do this, we need to create a utils.js file inside the components folder and add the snippet below:

1import {
2 createBigCommerceClient,
3 createBigCommerceEnhancer,
4} from '@uniformdev/canvas-bigcommerce';
5
6export const bigCommerceEnhancer = createBigCommerceEnhancer({
7 client: createBigCommerceClient({
8 storeHash: process.env.NEXT_PUBLIC_BIGCOMMERCE_STORE_HASH,
9 token: process.env.NEXT_PUBLIC_BIGCOMMERCE_TOKEN,
10 }),
11 createProductOptions: () => {
12 return {
13 include_fields: ['id', 'name', 'price'],
14 };
15 },
16});

The snippet above does the following:

  • Imports required dependencies
  • Creates a bigCommerceEnhancer using the createBigCommerceEnhancer functions that also configures the client using the Store Hash and Token we saved earlier. Uses the createProductOptions to specify required product fields (id, name, and price)

Getting composable data from Uniform With that done, we can use the bigCommerceEnhancer to enhance returned data from Uniform. To do this, we need to modify the index.js file inside the pages folder as shown below:

1import Head from 'next/head';
2import { Item } from '../components/Item';
3import LogoIcon from '../components/LogoIcon';
4import { CanvasClient, EnhancerBuilder, enhance } from '@uniformdev/canvas'; //add
5import { CANVAS_BIGCOMMERCE_PARAMETER_TYPES } from '@uniformdev/canvas-bigcommerce'; //add
6import { bigCommerceEnhancer } from '../components/utils'; //add
7
8export default function Home({ composition }) { //modify
9 const {slots} = composition //add
10 return (
11 <div>
12 <Head>
13 <title>Commerce IMG</title>
14 <meta name='description' content='Commerce Landing Page in Nextjs' />
15 <link rel='icon' href='/favicon.ico' />
16 </Head>
17 <main>
18 <header className='p-5 bg-[#292961] shadow-slate-400'>
19 <div className='flex items-center'>
20 <LogoIcon />
21 <p className='text-white ml-4'>Pattern Store</p>
22 </div>
23 </header>
24 <section className='flex h-[500px]'>
25 <div className='w-1/2 bg-[#d8dbe2] h-full flex justify-center items-center'>
26 <h1 className='text-4xl px-4 lg:px-5 font-medium'>
27 {' '}
28 Uniform, Bigcommerce, and Cloudinary{' '}
29 <span className='text-[#292961]'>powered</span> pattern store
30 </h1>
31 </div>
32 <div className='w-1/2 h-full'>
33 <img
34 alt='hero'
35 src={slots.ecomproduct[0].parameters.img.value[0].url}
36 className='h-full w-full object-fit'
37 />
38 </div>
39 </section>
40 <section className='px-5 py-10'>
41 <h3 className='mb-4 font-medium capitalize text-[#292961]'>
42 featured products
43 </h3>
44 <div className='grid grid-col-1 lg:grid-cols-3 w-full h-96'>
45 {slots.ecomproduct.slice(1).map((item, i) => (
46 <Item
47 key={i}
48 img={item.parameters.img.value[0].url}
49 title={item.parameters.details.value.name}
50 price={item.parameters.details.value.price}
51 />
52 ))}
53 </div>
54 </section>
55 </main>
56 </div>
57 );
58}
59
60//add
61export async function getStaticProps() {
62 //fetching data from uniform
63 const client = new CanvasClient({
64 apiKey: process.env.NEXT_PUBLIC_API_KEY,
65 projectId: process.env.NEXT_PUBLIC_PROJECT_ID,
66 });
67
68 const { composition } = await client.getCompositionBySlug({
69 slug: 'homepage',
70 });
71
72 //enhancing with bigcommerce
73 const enhancers = new EnhancerBuilder().parameterType(
74 CANVAS_BIGCOMMERCE_PARAMETER_TYPES,
75 bigCommerceEnhancer
76 );
77
78 await enhance({ composition, enhancers, context: {} });
79
80 return {
81 props: {
82 composition,
83 },
84 };
85}

The snippet above does the following:

  • Imports the required dependencies
  • Gets data from Uniform using the getStaticProps function. The function also does the following:
    • Creates a CanvasClient instance using the API key and Project ID we saved earlier.
    • Uses the instance to get composition by passing in the homepage (we configured this on the Uniform platform) as a slug.
    • Uses the bigCommerceEnhancer to filter the data returned by the composition.
  • Updates the UI to show data dynamically from the composition

With that done, we can restart our development server using the command below:

1npm run dev

Conclusion

This post discussed creating a composition on Uniform with product data from BigCommerce and a Product image from Cloudinary. With Uniform, we can improve our digital experience, personalize our data, and improve application performance (single API call).

These resources might be helpful:

Demola Malomo

Software Engineer & Technical Writer

Demola is a software developer, technical writer, and product designer. He has a passion for designing and building scalable applications.