I wrote this article in December 2023 for an interview screening task and thought to share it today while clearing my drafts for some new content prep, just in case it's still helpful to someone out there. The goal was to write a technical article on using GraphQL to build server-driven UIs. I spent quite some time researching the concept, refreshing my very little GraphQL experience and using my general REST API knowledge to pull it off. By the way, when I submitted this task, the reviewer was surprised I claimed to have had a little GraphQL experience and praised the piece for its depth and clarity —the effort put into this was worth it at that point :). All of this was done under 24 hours, by the way, per the instructions.

In conventional client-server architectures, the client application typically calls the shots when it comes to the structure and behaviour of the user interface. However, rising specific business needs have led to a new architecture called Server-Driven UIs (SDUI). In this powerful approach, the server shapes the UI and manages the UI logic and rendering strategy. This enables the client application to become lighter and focus purely on displaying the content dished out by the server. Recently, more mobile-focused companies like Airbnb and Meta have embraced the Server-Driven UI approach, significantly improving their overall engineering architecture and user experience. In this article, you'll learn about the server-driven approach to building user interfaces, why/when you might want to consider it, how some notable companies have implemented it, and how you can start implementing yours using GraphQL.

Photo by UX Indonesia on Unsplash.

What Exactly Are Server Driven UIs?

A large percentage of software applications (specifically mobile) today require some graphical user interface with which end consumers interact with the application. The experience each user has (usually referred to as UX—User Experience) while interacting with the application in their respective geographical locations determines whether they will be satisfied. This involves all mundane and complex tasks, like how fast specific data is rendered to the user upon a button click or screen swipe, to how quickly they get feedback from the application when they make manual requests by entering some text in an input field. This phenomenon makes it essential for engineering teams to invest in delivering the perfect user experience. If your software product falls under categories like ecommerce or payment services, where every interaction impacts revenue, it gets even more complex. As is commonly said in ecommerce industry, “failure to satisfy users will result in unhappy consumers, influencing conversions, sales, and revenue”—the trio that business owners hate to be affected. This philosophy drives the technological advancements in the ecommerce industry, leading to the rise and wide adoption of concepts like headless, composable commerce, and edge computing. This same philosophy drives the evolution of server-driven UIs, but for a slightly different challenge, which we will discuss soon.

While the resulting experience of rendering data "seems easy" from the user's perspective, it is usually a lot of work for engineering teams at companies that render data to billions of users every second of the day. This involves a coordinated and distributed amount of work on both the client-side (frontend) and server-side (backend) as summarized in the illustration below.

Non-Server Driven UIs

To explain server-driven UIs, let’s first talk about what the architecture looks like without server-driven UIs. A typical application over the HTTP protocol follows a client-server architecture, where data is exchanged between the frontend (client) and the backend (server) via an application programming interface (API). Based on the query requests, the backend retrieves and inserts data into the database and returns the results to the frontend. The frontend then receives the data from the backend in a structured schema and determines where and how to render it to the user interface, based on the UX goals for each UI view (feature). This is how most classic applications function, and it is the common practice today.

Let’s consider a hypothetical MVP ecommerce mobile application that returns the UI components on the home view screen for listing different types of products as described in the list and image below. Each product listing section returns a different type of design and styling for the product(s).

1. Carousel block: for highlighting top products (either based on demand or sales data).

2. Grid block: for in-season products (e.g., Christmas, Winter, Summer, etc.).

3. Checkout block: quick checkout for a randomly selected discounted product (promotions).

The query will look something like this:

query homePage {
    brand {
        title
		logo
	}
    products (country: US) {
        id
		name
		description
		slug
		price
		currency
		isTop
		isDiscounted
	    seasonTypes {
            name
            description
        }
    }
}

And the returned JSON data will look like this:

{
  "data": {
    "brand": {
			"title": "Welcome to Tailcall Shop!",
			"logo": "<https://avatars.githubusercontent.com/u/112062857>"
		},
    "products": [
      {
        "id": "1",
        "name": "Product A",
        "description": "This is a description for Product A.",
        "slug": "product-a",
        "price": 29.99,
        "currency": "USD",
        "isTop": true,
        "isDiscounted": false,
        "seasonTypes": [
          {
            "name": "Spring",
            "description": "Fresh arrivals for the spring season"
          },
          {
            "name": "Winter",
            "description": "Stay warm with our winter collection"
          },
          {
            "name": "All Seasons",
            "description": "Suitable for all seasons"
          }
        ]
      },
      {
        "id": "2",
        "name": "Product B",
        "description": "Description for Product B.",
        "slug": "product-b",
        "price": 39.99,
        "currency": "USD",
        "isTop": false,
        "isDiscounted": true,
        "seasonTypes": [
          {
            "name": "Christmas",
            "description": "Cool christmas picks"
          },
          {
            "name": "All Seasons",
            "description": "Versatile for all seasons"
          }
        ]
      },
      {
        "id": "3",
        "name": "Product C",
        "description": "Introducing Product C with a unique description.",
        "slug": "product-c",
        "price": 49.99,
        "currency": "USD",
        "isTop": true,
        "isDiscounted": true
      }
    ]
  }
}

When the frontend receives this JSON data, it’s responsible for consuming the data and rendering it to the user interface. Depending on the sequence of the returned data, the frontend renders the data in the different category blocks from top to bottom using different pre-defined UI components and logic. In addition, based on which seasonTypes the product is associated with, the frontend logic will also sort the product displayed in the Grid Block (knowing that in a real scenario, the number of products could be up to Infinity theoretically).

Now, if you want to reorder the sequence of the category blocks or add new category blocks (which will require adding new UI components), you will need to make some changes to the UI logic (code) on the client-side. This sounds good and should be easily achievable. However, since this is a cross-platform mobile application, code updates will not get to the end user immediately, just like web apps work, where you can deploy a new release and use different rendering strategies to update the entire web application upon a new user request. Each user’s device hosts the software code of the mobile application. Also, the latest version of the app needs to be submitted to the app store (most often both Android and iOS), and after a successful review and approval, the user must update the application manually if they don’t have “auto-update” turned on. There will be many repeated processes when you need to make more changes over time! Plus, users often don’t update their applications immediately after you ship a new version, which makes them lose out on new features, and you lose out on testing feedback. In addition, there might be compatibility issues with breaking changes, where the latest code state no longer matches the previous client. All of these signal the need for a different approach; ergo, server-driven UIs.

Server Driven UIs

In this case, and for the same query described above, the returned JSON data will look like this:

{
  "data": {
    "brand": {
			"title": "Welcome to Tailcall Shop!",
			"logo": "<https://avatars.githubusercontent.com/u/112062857>"
		},
    "products": [
      {
		"componentType": "gridBlock",
        "id": "1",
        "name": "Product A",
        "description": "This is a description for Product A.",
        "slug": "product-a",
        "price": 29.99,
        "currency": "USD",
        "isDiscounted": false,
        "seasonTypes": [
          {
            "name": "Spring",
            "description": "Fresh arrivals for the spring season"
          },
          {
            "name": "Winter",
            "description": "Stay warm with our winter collection"
          },
          {
            "name": "All Seasons",
            "description": "Suitable for all seasons"
          }
        ]
      },
      {
		"componentType": "carouselBlock",
        "id": "2",
        "name": "Product B",
        "description": "Description for Product B.",
        "slug": "product-b",
        "price": 39.99,
        "currency": "USD",
        "isDiscounted": true,
        "seasonTypes": [
          {
            "name": "Christmas",
            "description": "Cool christmas picks"
          },
          {
            "name": "All Seasons",
            "description": "Versatile for all seasons"
          }
        ]
      },
      {
	    "componentType": "checkoutBlock",
        "id": "3",
        "name": "Product C",
        "description": "Introducing Product C with a unique description.",
        "slug": "product-c",
        "price": 49.99,
        "currency": "USD",
        "isDiscounted": true
      }
    ]
  }
}

The UI will now read and render the data (the UI Schema) without further processing or delegation. The supplied JSON data already stipulates how and where to present each product data to the UI using the componentType property. The backend now includes UI components for the screen alongside the product information (UI components' layout view, appearance shape, content, etc.), and the client already has the agnostic templating logic to add styling to the displayed visuals. In the above MVP example, product A will be rendered first in the Grid Block, followed by product B in the Carousel Block, as shown in the image below.

The server is now facilitating the UI change. It simultaneously updates the JSON structure and UI with no additional UI logic change and app re-deployment. This approach reduces the client-side logic and leads to consistency and better versioning across all client platforms (including web, iOS, Android, etc.). This architecture becomes super helpful when the UI of your application should change multiple times based on different types of users (e.g., an ecommerce app for multiple merchants where you need to customise the UI differently for each user). You can experiment and iterate faster without doing an entire release cycle.

Some Case Studies

Although the MVP example described earlier is hypothetical, many notable companies, including Reddit, Shopify, Airbnb, Meta, Persona, and Lyft, already use this architecture. For example, Reddit revamped its feed architecture across Android and iOS some months ago. According to an iOS engineer at Reddit, the implementation of the previous feed presented several challenges (~source):

“Last year our feeds were pretty slow. You’d start up the app, and you’d have to wait too long before getting content to show up on your screen. Equally as bad for us, internally, our feeds code had grown into something of a maintenance nightmare. The current codebase was started around 2017 when the company was considerably smaller than it is today. Many engineers and features have passed through the 6-year-old codebase with minimal architectural oversight. Increasingly, it’s been a challenge for us to iterate quickly as we try new product features in this space.”

The resulting implementation featured each post unit, represented by a generic Group object with an array of Cell objects, as seen in the image below. With this, they describe anything the Feeds screen shows as a Group (e.g., the Announcement Card or the Trending Carousel).

Example Schema and UI of Reddit Feeds for their Announcement Items (Source: Reddit Engineering Blog).

Another Android Engineer at Airbnb mentions similar challenges (~source):

“To show our users a listing, we might request listing data from the backend. Upon receiving this listing data, the client transforms that data into UI. This comes with a few issues. First, there’s listing-specific logic built on each client [referring to web, Android, and iOS] to transform and render the listing data. This logic becomes complicated quickly and is inflexible if we make changes to how listings are displayed down the road. Second, each client has to maintain parity with each other. As mentioned, the logic for this screen gets complicated quickly and each client has their own intricacies and specific implementations for handling state, displaying UI, etc. It’s easy for clients to quickly diverge from one another. Finally, mobile has a versioning problem.”

The resulting implementation features the backend returning the UI types the data should be rendered with, as seen in the image below. With this, they describe anything the Product Listing screen shows as a Section (e.g., the Title Section or the Home Details Section).

Example Schema and UI of Airbnb’s Property Overview (Source: The Airbnb Tech Blog).

Both implementations demonstrate the concept of delegating UI rendering and logic decisions to the server, with the client just rendering visuals.

Benefits of Server Driven UIs

Think about content for a minute; it's easy to ensure mutability for content-intensive applications by leveraging a headless content management system (CMS). You will develop the application to accept dynamic data from a content API and ship it to the user's devices. Multiple content managers can then collaboratively create and modify structured data stored in some repository on the cloud. The content API is updated frequently, and the application returns the new data. I previously wrote about this concept, and you can read more about it. This process is similar to server-driven UIs, but instead of just returning real-time data, the server returns real-time UI component sequences and arrangements. I was talking with a friend who expressed their engineering team's concerns about shipping their enterprise software on a point-of-sale (POS) payments machine, which will power different payment providers (see them like merchants for the end users—the hardware owners). A consumer will purchase each machine with the pre-installed software, which can be updated later, though tedious (especially for less digitally savvy users). Updating the software each time they want to add new UI logic for the newly added providers (merchants) on the hardware is even more complex than typical smartphones, making it a good case for Server-Driven UIs. If implemented successfully, they can ship the hardware with the first version of the software and incrementally update the software’s UI logic from the server as they deem fit.

In summary, some benefits of Server Driven UIs include:

• Better Versioning: There won't be a need for multiple releases for UI logic changes.

• Reduced Bundle Size: Since no code is added to the frontend logic when the developers need to make UI customisation changes, the app size remains lightweight as shipped. This is essential for software shipped on low-end devices with limited computing power.

• Faster Experimentation and Iteration: Now, engineering teams can experiment with and test new ideas (whether driven by creativity, UX research, or user feedback) faster across all supported platforms without releasing new versions.

• Efficient A/B Testing: Due to the advantages described above, engineering teams can now compare two versions of the UI logic to determine which performs better and faster than they would without SDUI. Now, the dataset would be more extensive since all inactive and active users with the application installed will receive the updates.

• Personalised User Experiences: It becomes easier to adjust the UI rendering based on user demands, user behaviour, preferences, or results from the A/B testing phases.

• Easier Migration: It's easier to adopt new frontend frameworks because there's less business logic in them. With the UI shape returned from the server, you can experiment and innovate on the frontend much faster with minimal business impact.

Companies that require both native mobile and web application development may benefit the most from SDUI. This can be software running on a smartphone or an embedded system (Arduino, Raspberry Pi, point-of-sale payment machines, etc.). Generally, server-side UIs can be applied in the following software industries:

• Social Media: dynamically update feeds and notifications across different devices.

• Ecommerce Applications: dynamically update product listings, promotions, and user interfaces without requiring users to update their applications.

• Content Management Systems (CMS): dynamically manage and deliver content to different clients, ensuring a consistent user experience across web and mobile interfaces.

• Multiplayer Gaming Applications: dynamically update game interfaces, dashboards, leaderboards, and in-game feeds and notifications.

• Enterprise Software: dynamically manage and update dashboards, reports, and other UI components used by customers and consumers across different devices.

• Real-Time Collaboration Tools: synchronise changes and maintain a consistent user interface for messaging or collaborative document editing software.

• Medical Applications: dynamically update patient records, appointment schedules, transactions, and other relevant information for medical professionals in real-time.

• Internet of Things (IoT): dynamically control and update the user interfaces of software running on embedded systems.

• Et cetera.

Various factors, including the necessity for dynamic changes, platform consistency, and the application's nature, determine the suitability of server-driven UIs. While not suitable for all scenarios, server-driven UIs provide advantages in certain situations.

Using GraphQL to Build Server Driven UIs

SDUI is a software design pattern you can implement in various ways, including with GraphQL. GraphQL is more suited for something like this compared to its counterpart since it's a query language that offers a better development experience. With a single query to the GraphQL server, you can get multiple UI components (product information, in our case) without multiple API round-trips. Facebook started using GraphQL in 2012 for their native mobile applications, even before announcing it at the React.js Conference in 2015. Although GraphQL seems more known for web applications recently, Facebook's use since its inception shows that the technology is well-suited for mobile application development.

Your schema and design must correlate when building a GraphQL server using the server-driven UI approach. The backend must leverage the existing UI component schemas to build the new view components or screen structure. The frontend UI should update if the server introduces a new design component or structural adjustment. This approach will require focusing on:

• A well-defined UI design system and collection of components (UI elements).

• A template processing layer that will receive and process customisation requests.

• A well-defined GraphQL Schema.

• Other required orchestration layers.

Whatever method you choose to implement SDUI with GraphQL, you should observe the following fundamental principles:

1. Start with UI design. Create a design system using patterns like Atomic Design and follow the demand-oriented schema approach.

2. Return product information as UI elements (presentation information on UI components' layout view, appearance, content, etc.) and not domain data (core business logic).

3. Implement the design and API using GraphQL types. You can follow Apollo's recommended approach to schema design, which includes common strategies and best practices.

4. Avoid including styling values (like font size, colours, etc.) in the server. UI component styling should be pre-built on the client to meet the server's requirements.

5. Adopt SDUI incrementally if your product is already in production. Start with minor features, reduce business logic in the existing client code, gather feedback, and slowly work your way up.

The schema of our hypothetical MVP described earlier will look like this without a server-driven UI approach in use:

type Brand {
	title: String;
	logo: Image;
}

type SeasonTypes {
	name: String;
	description: String;
    count: Int;
}

type Product @key(fields: "country") {
    componentType: String;
    id: String;
    name: String
    description: String;
    slug: String;
    price: String;
    currency: String;
	isTop: Boolean;
	isDiscounted: Boolean;
	seasonTypes?: [SeasonTypes];
    count: Int;
}

If we then switch to server-driven UIs, we will have something like this:

type Brand {
	title: String;
	logo: Image;
}

type SeasonTypes {
	name: String;
	description: String;
    count: Int;
}

type Product @key(fields: "country") {
  componentType: String;
  id: String;
  name: String
  description: String;
  slug: String;
  price: String;
  currency: String;
  isTop: Boolean;
  isDiscounted: Boolean;
  seasonTypes?: [SeasonTypes];
  count: Int;
}

# ...

type BlockCarousel {
	elements: [...];
	product: [Product];
}

type BlockGrid {
	elements: [...];
	product: [Product];
}

type BlockCheckout {
	elements: [...];
	product: [Product];
}

ProductViews = BlockCarousel | CarouselGrid | CheckoutGrid;

type HomeScreen {
	blocks: ProductViews;
}

A client-side query for HomeScreen.blocks will return all the product data and different product listing views. The client can then render multiple specific experiences depending on the query result (user’s customisation request). This is a quick pseudocode overview of how implementing Server-Driven UI will look in GraphQL. For further learning, you can check out this project on GitHub, which you can use as a resource or playground to learn SDUI. It covers an end-to-end implementation of how SDUI works and follows the SDUI paradigm by ensuring the clients reference the same data endpoint that provides the UI schematics on how the client should render it. It includes a graphql-server, template-server, style-tokens, web-app, and mobile-app modules alongside extensive documentation that you can read.

Conclusion

Server-Driven User Interfaces (SDUIs) provide a dynamic, efficient, and adaptable solution to maintaining and updating the user interfaces of mobile apps. By transferring UI rendering operations from the client to the server, updates and modifications can be implemented fast without requiring users to download a new version of the app. This method results in a more seamless developer experience and a customizable user experience.

You should also note that SDUI is an expensive undertaking that requires significant engineering effort, especially if you have to migrate from an existing architecture. It comes with downsides (like the application becoming more online-first-focused and some offline capabilities needing to be reworked). However, there are benefits if your use case fits it so well that the business value of the upsides outweighs the downsides. As with any technology, evaluating your requirements and understanding the benefits and potential challenges is crucial before implementing server-driven UIs in your application. Hopefully, this article has been insightful, and you can take it further and do advanced research and experimentation.

Thanks for reading this far; cheers! 💙

The Digital Public Goods Alliance is a UN-endorsed, multi-stakeholder initiative that accelerates the attainment of the sustainable development goals by facilitating the discovery, development, use of, and investment in digital public goods. According to the UN Secretary General’s Roadmap for Digital Cooperation, digital public goods are open source software, open standards, open data, open AI systems, and open content collections that adhere to privacy and other applicable best practices, do no harm, and are of high relevance for attainment of the United Nations 2030 SDGs. This definition is operationalised through the DPG Standard, and you can find all DPGs being developed and used across the world in the DPG Registry.

Images source: https://digitalpublicgoods.net/digital-public-goods.

Digital public goods are important to building a more equitable world, solving global challenges, and attaining the sustainable development goals. Open Software like FormSG or OpenCRVS enables government agencies to better serve their citizens, and others like OpenFn enable other digital solutions to automate processes and exchange data. Open Datasets like AGROVOC Multilingual Thesaurus or Govdirectory enable different sectors to make better decisions. Likewise, Open Content Collections like Creative Commons Legal Tools or Data to Policy Navigator.

All these solutions are designed in ways different from all the libraries we npm or pip install. This is part of what makes DPGs different from proprietary or even many typical open source projects. We need solutions many others can adapt to their unique contextual needs, and DPGs are designed for this purpose. They are designed to work in different settings and take into consideration the geographical differences of where they will be used. They are designed to be interoperable, so other solutions can exchange data and continue extending the value provided. They are designed following open standards and best practices. They are designed to anticipate, prevent, and do no harm by design, thereby protecting their users. They are designed to ensure the privacy, security, and integrity of PII data. They can be made part of a country's digital public infrastructure (DPI) and even a lot more!

To learn more about applying to become a digital public good, you can read this submission guide, take this eligibility test, or read the DPG Wiki.

This is a new space for me, and the past two months have been an exciting ride working with amazing colleagues, with so much learning and work already being done. Please feel free to book a call or write to me to chat if you’d like to:

• Learn more about the DPGA or Digital Public Goods.

• Learn more about how your open source project can become a DPG.

• Learn more about how certain DPGs can fit into your country’s DPI or how you can support or implement certain DPGs.

• Chat about anything else!

I see how the Digital Public Good Alliance is facilitating the discovery and deployment of open source technologies, bringing together countries and like-minded organizations to create a thriving global ecosystem for digital public goods. This prompted me to develop an interest in the great work they’ve been doing, and I'm elated to join and help in different capacities to drive the goals of the DPGA towards unlocking the potential of open source technologies for a more equitable world.

"If we create a product we like that never ends up in people’s hands, who are we working for beyond ourselves? How can we fix that? How do we know we’re making the world a better place and not just creating software for people with free time and a spare laptop?..." —Thibault Martin.

Cheers to making the world a better place. Onwards! 💙

We’re in the age of composability, a term that describes the ability of engineering teams to compose different optimal tools to build the perfect experience for their users. With that in mind, I spent some time experimenting on how to build media design editing apps and I found a tool called the CreativeEditor SDK Engine that allows you to build fully customizable design editors with fewer lines of code. In this tutorial, I will show you how to use the CE.SDK Engine in a Nextjs web application to build a simple image editor and even a Canva-like editor! As a bonus, I’d also show you how you can build an image background removal app (using the background-removal.js library) and integrate with Clerk Auth.

If you want to see the final code integration, you can head to this repository now, but you might want to read along to learn one or two things, especially if you’re new to this :).

Prerequisites

To get the best out of this tutorial, you need to have the following:

• Nodejs and NPM installed on your computer.

• An IDE and terminal installed on your computer.

• A web browser installed on your computer.

• A stable connection to the internet.

• Some prior knowledge of the JavaScript programming language.

• Some prior knowledge of the Reactjs JavaScript framework.

• A smile on your face :).

The CreativeEditor Engine

IMG․LY has built a creative engine that allows developers and businesses to add video and photo editing features to their applications. The engine is used to build different SDKs, that can power photo, video, design editing, and creative automation features for unlimited distributed end-users. They currently provide a CreativeEditor SDK (CE.SDK), PhotoEditor SDK, VideoEditor SDK, and Camera SDK on different platforms including, Web, Server, iOS, and Android. This means you can use these SDKs with a wide range of frameworks like Vanilla JS, Reactjs, Nextjs, Vuejs, Angular, Svelte, Electron, Flutter, ReactNative, Ionic, etc. All these SDKs can be used for a wide range of use cases and industries like:

• Personalized printing.

• Ecommerce product customization.

• Web2Print.

• Automated design templates.

• Photo editors.

• Video editors.

• Design editors (like Canva).

• Website editors (like Wix).

The beautiful part is that you can use the SDK to programmatically automate different creative design tasks, workflows, and ideas you have in mind, making your business even more efficient. From code, to design, to export, to print, to ♾️! Fortune 100 businesses and other startups like HP, ZARA, Shopify, Flickr, etc. are already using the SDKs to power hundreds of applications.

Building a Demo Image Background Editing App

To show you the basics of CE.SDK Engine, let’s build a simple Nextjs web application that enables users to craft an attractive profile picture for social media platforms. With this application, a user can upload a professional headshot image (or maybe a cute image of their pet 🙃) without a background (usually in PNG format). We will then use the CE.SDK Engine to apply different background options and allow the user to download all the edited variations. In summary, this is what the flow of the application looks like:

Now, let’s get started!

[I] Install Packages and Setup Project Structure

First, use create-next-app to set up a new Nextjs project with TypeScript and App Router like so:

npx create-next-app@latest

Next, install all the packages we need:

npm install @cesdk/engine @cesdk/cesdk-js @imgly/background-removal @clerk/nextjs

Next, create some extra directories and files, as seen in the file structure below (the ones with an asterisk * beside the name are the new files):

┌── app
    ├── bg-add*
        ├── page.tsx
    ├── bg-remove*
        ├── page.tsx
    ├── components*
        ├── editorCanvas.tsx
        ├── headshotCanvas.tsx
    ├── editor*
        ├── page.tsx
    ├── start*
        ├── page.tsx
    ├── utils*
        ├── grids.ts
    ├── layout.tsx
    ├── page.tsx
┌── public
├── .env.local
...
├── middleware.ts*
├── package.json
└── tsconfig.json

[II] Some Key Terms

Before we proceed further, here are some unique key terms used in the CE.SDK engine which are the fundamental components that make up the engine canvas.

• Canvas: the HTML element used to draw graphics using JavaScript on the web.

• Scene: the root of the canvas for each instance of the engine accessed with the Scene API. Generally, a scene will contain multiple pages which will also contain other blocks.

• Page: the parent block of all elements in the scene (usually used to group all blocks/elements together).

• Block (or design block): the main building unit in CE.SDK accessed with the Block API and organized in a hierarchy structure through parent-child relationships inside the scene. Every element is a block in the canvas (e.g., graphics, shapes, images, texts, etc.).

• Fill: an object that defines the contents within a design block (e.g., images, videos, solid colors, gradients, etc.).

[III] Setup the CE.SDK Engine

The CreativeEditor SDK Engine (@cesdk/engine) provides different APIs for powering any editing UI. To get started, we need to initialize the engine and pass in the config object. In the /components/headshotCanvas.tsx file you created earlier, add the following code:

"use client";
import { useEffect, useRef, useState, ChangeEvent } from "react";
import CreativeEngine from "@cesdk/engine";

const config = {
  license: process.env.NEXT_PUBLIC_CESDK_LICENSE,
  userId: "guides-user",
  baseURL: "https://cdn.img.ly/packages/imgly/cesdk-engine/1.24.0/assets",
};

export default function BgAddPage() {
  const cesdk_container = useRef<HTMLDivElement>(null);

  const initializeCESDK = () => {
    CreativeEngine.init(config).then((engine) => {
      // Append the engine element to the container.
      const container = cesdk_container.current!;
      container.innerHTML = "";
      container.append(engine.element);

      // Create a new scene and page.
      let scene = engine.scene.create();
      const page = engine.block.create("page");
      engine.block.setWidth(page, 500);
      engine.block.setHeight(page, 500);
      engine.block.appendChild(scene, page);
    });
  };

  useEffect(() => {
    initializeCESDK();
  }, []);

  return (
    <div
      ref={cesdk_container}
      style={{ width: "100vw", height: "100vh" }}
      >
    </div>
  );
}

In the code snippet above, we:

• Setup the config object and add the following parameters:

  • license: the CE.SDK API key. You can get one and test the platform free for up to 30 days once you sign up using this form. For testing in development, you can use the mtLT-_GJwMhE7LDnO8KKEma7qSuzWuDxiKuQcxHKmz3fjaXWY2lT3o3Z2VdL5twm license publicly available on the CE.SDK documentation. Only ensure to add that to your .env file using the NEXT_PUBLIC_CESDK_LICENSE name.

  • userID: an optional unique ID tied to your application's user. This is used mainly for tracking user data, specifically to calculate monthly active users.

  • baseURL: link to a public URL where different asset files are stored.

• Use the CreativeEngine.init(config) function to start up a new instance of the engine inside an HTML div element with a useRef reference to the element. This element will then contain the engine's <cesdk-canvas/> and will fill out its container.

Next, add the following code in the /bg-add/page.tsx file to render the /components/headshotCanvas.tsx component above in a page (/bg-add in this case):

import dynamic from "next/dynamic";

const CreativeEditorSDKWithNoSSR = dynamic(
  () => import("../components/headshotCanvas"),
  {
    ssr: false,
  }
);

export default CreativeEditorSDKWithNoSSR;

We’re doing this to avert errors like ReferenceError: document is not defined which will come up when the page renders with SSR. The CE.SDK Engine is a client-side library that requires various browser features (like document), hence it must be loaded and executed in the browser upon render. With this logic, we will load the library dynamically using next/dynamic and disable server rendering when the page is loaded in the browser.

[IV] Add Color and Image to Page

In the same /components/headshotCanvas.tsx file, let’s add more code like so:

"use client";
import { useEffect, useRef, useState, ChangeEvent } from "react";
import CreativeEngine from "@cesdk/engine";

const config = {
  license: process.env.NEXT_PUBLIC_CESDK_LICENSE,
  userId: "guides-user",
  baseURL: "https://cdn.img.ly/packages/imgly/cesdk-engine/1.24.0/assets",
};

// Default image for the page (user can update later).
const defaultImage =
  "https://github.com/BolajiAyodeji/attraktives-headshot/blob/main/public/headshot.png?raw=true";

export default function BgAddPage() {
  const cesdk_container = useRef<HTMLDivElement>(null);

  const initializeCESDK = () => {
    CreativeEngine.init(config).then((engine) => {
      const container = cesdk_container.current!;
      container.innerHTML = "";
      container.append(engine.element);

      let scene = engine.scene.create();
      const page = engine.block.create("page");
      engine.block.setWidth(page, 500);
      engine.block.setHeight(page, 500);
      engine.block.appendChild(scene, page);

      // Create a graphic block, set the shape/size,
      // get the color fill block of the page,
      // add a color to the block,
      // and add the block to the scene's page.
      const block = engine.block.create("graphic");
      engine.block.setShape(block, engine.block.createShape("rect"));
      engine.block.setFill(block, engine.block.createFill("color"));
      engine.block.setWidth(block, 500);
      engine.block.setHeight(block, 500);
      const colorFill = engine.block.getFill(page);
        // Red RGB color
      engine.block.setColor(colorFill, "fill/color/value", {
        r: 1.0,
        g: 0.0,
        b: 0.0,
        a: 1.0
      });
      engine.block.appendChild(page, block);

      // Create a block with an image fill
      // and add it to the scene's page.
      const imageFill = engine.block.createFill("image");
      engine.block.setString(
        imageFill,
        "fill/image/imageFileURI",
        defaultImage
      );
      engine.block.setFill(block, imageFill);
    });
  };

  useEffect(() => {
    initializeCESDK();
  }, []);

  return (
    <div
      ref={cesdk_container}
      style={{ width: "100vw", height: "100vh" }}
      >
    </div>
  );
}

In the code snippet above, we:

• Create a graphic block, set the shape/size, add a color to the block using the fill/color/value fill, and add the block to the page on the scene. Colors can be specified with either RGB, CMYK, or Spot color formats (I used RGB here).

• Create another block using the fill/image/imageFileURI fill and add it to a block.

At this point, you should start seeing the page rendering with a red color on the canvas like so:

[V] Display Multiple Pages on the Scene

Now let’s attempt to display multiple pages in a grid-like format on the same. In the same /components/headshotCanvas.tsx file, now add more code like so:

"use client";
import { useEffect, useRef, useState } from "react";
import CreativeEngine from "@cesdk/engine";
import { grids } from "@/app/utils/grids";

const config = {
  license: process.env.NEXT_PUBLIC_CESDK_LICENSE,
  userId: "guides-user",
  baseURL: "https://cdn.img.ly/packages/imgly/cesdk-engine/1.24.0/assets",
};

const defaultImage =
  "https://github.com/BolajiAyodeji/attraktives-headshot/blob/main/public/headshot.png?raw=true";

export default function BgAddPage() {
  const cesdk_container = useRef<HTMLDivElement>(null);

  const initializeCESDK = () => {
    CreativeEngine.init(config).then((engine) => {
      const container = cesdk_container.current!;
      container.innerHTML = "";
      container.append(engine.element);

      let scene = engine.scene.create();

      // Display multiple pages in the scene (as grid)
      // using the same properties but different positions and colors.
      for (let i = 1; i <= 6; i++) {
        const page = engine.block.create("page");
        engine.block.setWidth(page, 500);
        engine.block.setHeight(page, 500);
        engine.block.setPositionX(page, grids[i].x);
        engine.block.setPositionY(page, grids[i].y);
        engine.block.appendChild(scene, page);

        const block = engine.block.create("graphic");
        engine.block.setShape(block, engine.block.createShape("rect"));
        engine.block.setFill(block, engine.block.createFill("color"));
        engine.block.setWidth(block, 500);
        engine.block.setHeight(block, 500);
        const colorFill = engine.block.getFill(page);
        engine.block.setColor(colorFill, "fill/color/value", grids[i].color);
        engine.block.appendChild(page, block);

        const imageFill = engine.block.createFill("image");
        engine.block.setString(
          imageFill,
          "fill/image/imageFileURI",
          defaultImage
        );
        engine.block.setFill(block, imageFill);
      }
    });
  };

  useEffect(() => {
    initializeCESDK();
  }, []);

  return (
    <div
      ref={cesdk_container}
      style={{ width: "100vw", height: "100vh" }}
      >
    </div>
  );
}

Also, add the following code in the /utils/grids.ts file:

interface gridLayout {
  [key: number]: {
    x: number;
    y: number;
    color: { r: number; g: number; b: number; a: number };
  };
}

// Red, Blue, Green, Yellow, Pink, and Orange colors (in that order).
export const grids: gridLayout = {
  1: { x: -800, y: -50, color: { r: 1.0, g: 0.0, b: 0.0, a: 1.0 } },
  2: { x: -250, y: -50, color: { r: 0.0, g: 0.0, b: 1.0, a: 1.0 } },
  3: { x: 300, y: -50, color: { r: 0.0, g: 1.0, b: 0.0, a: 1.0 } },
  4: { x: -800, y: 500, color: { r: 1.0, g: 1.0, b: 0.0, a: 1.0 } },
  5: { x: -250, y: 500, color: { r: 1.0, g: 0.0, b: 1.0, a: 1.0 } },
  6: { x: 300, y: 500, color: { r: 1.0, g: 0.5, b: 0.0, a: 1.0 } },
};

In the code snippets above, we:

• Use a for loop to create multiple pages using the same properties we used earlier.

• Use the setPositionX and setPositionY options to position each page on the scene (coordinate of an element in a document—x and y axis on a graph) so they all appear in a grid sequence. This was a good hack for the grid layout and ideally you might want to display multiple pages horizontally or vertically.

• Create a grids object to store the values for the positions and color and dynamically use them inside the loop (grids[i].x, grids[i].y, and grids[i].color) based on the object’s key matching the loop’s index (i).

At this point, your canvas should get polished with a beautiful grid as seen below. NB: the scene will be displayed a little below the default view point on your screen but remember this is a canvas and you can drag the entire scene in any direction you want and reposition.

[VI] Upload an Image Locally to the Scene

Now, let’s add some more logic to allow a user to upload their own image locally. We can easily do this without having to handle any images in the cloud by using the <input type="file> element which will store the accessed files in the FileList JavaScript object returned by the File property in the input element. We can then convert the file into a Blob URL, save it in state, and display it in the canvas using the src attribute of an <img> HTML element.

In the same /components/headshotCanvas.tsx file, now add more code like so:

"use client";
import { useEffect, useRef, useState, ChangeEvent } from "react";
import CreativeEngine from "@cesdk/engine";
import { grids } from "@/app/utils/grids";

const config = {
  license: process.env.NEXT_PUBLIC_CESDK_LICENSE,
  userId: "guides-user",
  baseURL: "https://cdn.img.ly/packages/imgly/cesdk-engine/1.24.0/assets",
};

const defaultImage =
  "https://github.com/BolajiAyodeji/attraktives-headshot/blob/main/public/headshot.png?raw=true";

export default function BgAddPage() {
    // State to store the Blob URL of the uploaded image.
  const [imagePath, setImagePath] = useState<string>("");
  const cesdk_container = useRef<HTMLDivElement>(null);

  const initializeCESDK = (imagePath: string) => {
    CreativeEngine.init(config).then((engine) => {
      const container = cesdk_container.current!;
      container.innerHTML = "";
      container.append(engine.element);

      let scene = engine.scene.create();

      for (let i = 1; i <= 6; i++) {
        const page = engine.block.create("page");
        engine.block.setWidth(page, 500);
        engine.block.setHeight(page, 500);
        engine.block.setPositionX(page, grids[i].x);
        engine.block.setPositionY(page, grids[i].y);
        engine.block.appendChild(scene, page);

        const block = engine.block.create("graphic");
        engine.block.setShape(block, engine.block.createShape("rect"));
        engine.block.setFill(block, engine.block.createFill("color"));
        engine.block.setWidth(block, 500);
        engine.block.setHeight(block, 500);
        const colorFill = engine.block.getFill(page);
        engine.block.setColor(colorFill, "fill/color/value", grids[i].color);
        engine.block.appendChild(page, block);

        const imageFill = engine.block.createFill("image");
        engine.block.setString(
          imageFill,
          "fill/image/imageFileURI",
          imagePath || defaultImage
        );
        engine.block.setFill(block, imageFill);
      }
    });
  };

    // Function to process the image file upload on input change.
  const uploadImage = async (event: ChangeEvent<HTMLInputElement>) => {
    if (event.target.files) {
        // Get the first file in the list
      const file = event.target.files[0];
      // Create a Blob URL from the file.
      const blobUrl = URL.createObjectURL(file);
      // Set the Blob URL to state.
      setImagePath(blobUrl);
    }
  };

    // Add imagePath to the useEffect dependency.
  useEffect(() => {
    initializeCESDK(imagePath);
  }, [imagePath]);

  return (
    <div className="flex flex-col items-center justify-center">
      <label htmlFor="upload-headshot" className="hidden">
        Upload your image
      </label>
      <input
        type="file"
        accept="image/png, image/jpeg, image/jpg"
        id="upload-headshot"
        name="upload-headshot"
        className="mt-6 text-white border-2 border-white rounded-full 
        file:mr-3 file:px-3 file:py-2 file:border-0 
        file:bg-white file:text-black hover:file:bg-blue-200"
        onChange={uploadImage}
        required
      />
      <div
        ref={cesdk_container}
        style={{ width: "100vw", height: "100vh" }}
        className=""
      ></div>
    </div>
  );
}

In the code snippet above, we:

• Use the URL.createObjectURL() method to create a Blob string URL representing the image file. This string URL’s lifetime is tied to the current document in the window.

• Use the useState hook to store the Blob URL of the uploaded image.

• Add imagePath to the useEffect dependency, so the initializeCESDK() function is called again whenever imagePath changes ensuring that the UI updates accordingly without reloading the page.

• Add the new <input type="file"> HTML element with an onChange event.

Now you should be able to upload a new image in the canvas and get the same background colors applied (NB: ensure you’re uploading PNG images with a transparent background).

[VII] Download all Pages as PNG Image

Now let’s add the last feature to allow a user to download all the generated variations of their headshot. In the same /components/headshotCanvas.tsx file, add more code like so (this is the final code of this entire component):

"use client";
import { useEffect, useRef, useState, ChangeEvent } from "react";
import CreativeEngine, { MimeType, ExportOptions } from "@cesdk/engine";
import { grids } from "@/app/utils/grids";

const config = {
  license: process.env.NEXT_PUBLIC_CESDK_LICENSE,
  userId: "guides-user",
  baseURL: "https://cdn.img.ly/packages/imgly/cesdk-engine/1.24.0/assets",
};

const defaultImage =
  "https://github.com/BolajiAyodeji/attraktives-headshot/blob/main/public/headshot.png?raw=true";

export default function BgAddPage() {
  const [imagePath, setImagePath] = useState<string>("");
  const cesdk_container = useRef<HTMLDivElement>(null);

  const initializeCESDK = (imagePath: string) => {
    CreativeEngine.init(config).then((engine) => {
      const container = cesdk_container.current!;
      container.innerHTML = "";
      container.append(engine.element);

      let scene = engine.scene.create();

      for (let i = 1; i <= 6; i++) {
        const page = engine.block.create("page");
        engine.block.setWidth(page, 500);
        engine.block.setHeight(page, 500);
        engine.block.setPositionX(page, grids[i].x);
        engine.block.setPositionY(page, grids[i].y);
        engine.block.appendChild(scene, page);

        const colorFill = engine.block.getFill(page);

        const block = engine.block.create("graphic");
        engine.block.setShape(block, engine.block.createShape("rect"));
        engine.block.setFill(block, engine.block.createFill("color"));
        engine.block.setColor(colorFill, "fill/color/value", grids[i].color);
        engine.block.setWidth(block, 500);
        engine.block.setHeight(block, 500);
        engine.block.appendChild(page, block);

        const imageFill = engine.block.createFill("image");
        engine.block.setString(
          imageFill,
          "fill/image/imageFileURI",
          imagePath || defaultImage
        );

        engine.block.destroy(engine.block.getFill(block));
        engine.block.setFill(block, imageFill);
      }

      // Export all pages on the scene.
      const exportButton = document.getElementById("export_button")!;
      exportButton.removeAttribute("disabled");
      exportButton.onclick = async () => {
        // Specify the image format (PNG).
        const mimeType = "image/png" as MimeType;
        // Specify compression level (original default for PNG is 5).
        const options: ExportOptions = {
          pngCompressionLevel: 9,
        };

        const pages = engine.scene.getPages();
        // Loop through all the pages on the scene.
        pages.map(async (page) => {
          // Download multiple Blob files as PNG for each page.
          const blob = await engine.block.export(page, mimeType, options);
          const anchor = document.createElement("a");
          anchor.href = URL.createObjectURL(blob);
          anchor.download = `attraktives-hs-${page}.png`;
          anchor.click();
        });
      };
    });
  };

  const uploadImage = async (event: ChangeEvent<HTMLInputElement>) => {
    if (event.target.files) {
      const file = event.target.files[0];
      const blobUrl = URL.createObjectURL(file);
      setImagePath(blobUrl);
    }
  };

  useEffect(() => {
    initializeCESDK(imagePath);
  }, [imagePath]);

  return (
    <div className="flex flex-col items-center justify-center">
      <label htmlFor="upload-headshot" className="hidden">
        Upload your image
      </label>
      <input
        type="file"
        accept="image/png, image/jpeg, image/jpg"
        id="upload-headshot"
        name="upload-headshot"
        className="pt-6 text-white
        file:mr-4 file:py-2 file:px-4
        file:rounded-full file:border-0
          file:bg-white file:text-black
          hover:file:bg-blue-200"
        onChange={uploadImage}
        required
      />
      <button
        id="export_button"
        className="w-80 lg:w-52 px-6 py-4 mt-6 text-center bg-white text-black hover:bg-blue-200"
      >
        Download Pages &nbsp; ↯
      </button>
      <div
        ref={cesdk_container}
        style={{ width: "100vw", height: "100vh" }}
      ></div>
    </div>
  );
}

In the code snippet above, we:

• Specify the image format and compression level of the export.

• Loop through all the pages on the scene and download multiple Blob files as PNG for each page.

• Add a <button> element to the page and use the id of the element to add a <a href="" download=""> element so clicking the button will automatically trigger the downloads. Since there are just six images, this probably is sufficient and there’s no need to add a zip file logic (if the pages on the scene increase, a zip file will be best!).

Here’s what the final page should look like now. You can now use other different images from your computer and download them swiftly :).

Bonus: Building an Image Background Removal App

For users to effectively use the app we just built, they need to always upload a transparent image with its background removed. So why not build another app that allows a user to remove the background of an image first before proceeding to add background colors? Well, IMG․LY also built a background-removal.js library that allows you to remove backgrounds from images right in the browser environment with no additional costs or privacy concerns! The library used the Neural Network (ONNX model) and WASM files which are hosted by default.

You can pass either an ImageData, ArrayBuffer, Uint8Array, Blob, URL, or string to the imglyRemoveBackground() function from the package and the result will be another Blob URL (PNG image format). You can learn more by reading the documentation. That said, I gave the library a quick spin and this is what the code looks like (in the /bg-remove/page.tsx file):

"use client";
import { useState, ChangeEvent } from "react";
import Image from "next/image";
import imglyRemoveBackground from "@imgly/background-removal";

const loadingGif = "/loading.gif";

export default function BgRemovePage() {
    // State for the initial Blob URL of the uploaded image.
  const [initialImagePath, setInitialImagePath] = useState<string>("");
  // State for the final Blob URL of the processed image.
  const [finalImagePath, setFinalImagePath] = useState<string>("");
  // State to track when the image is processing.
  const [loading, setLoading] = useState<boolean>(false);

  const uploadImage = async (event: ChangeEvent<HTMLInputElement>) => {
    setLoading(true);
    setFinalImagePath("");
    if (event.target.files) {
      const file = event.target.files[0];
      const initialBlobUrl = URL.createObjectURL(file);
      setInitialImagePath(initialBlobUrl);
      imglyRemoveBackground(initialBlobUrl)
        .then((blobUrl) => {
          const finalBlobUrl = URL.createObjectURL(blobUrl);
          setFinalImagePath(finalBlobUrl);
        })
        .catch((error) => {
          console.error("Something went wrong.", error);
        })
        .finally(() => {
          setLoading(false);
        });
    }
  };

  return (
    <div className="flex flex-col h-screen items-center justify-center">
      <label htmlFor="upload-image" className="hidden">
        Upload your image
      </label>
      <input
        type="file"
        accept="image/png, image/jpeg, image/jpg, image/webp"
        id="upload-image"
        name="upload-image"
        className="text-white border-2 border-white rounded-full 
        file:mr-3 file:px-3 file:py-2 file:border-0 
      file:bg-white file:text-black hover:file:bg-blue-200"
        onChange={uploadImage}
        disabled={loading}
      />

      {initialImagePath && (
        <div className="grid grid-cols-2 gap-8 m-12">
          <Image
            src={initialImagePath}
            alt="Preview Initial Image"
            width={400}
            height={400}
            className="border-2 border-white"
          />
          <Image
            src={!finalImagePath ? loadingGif : finalImagePath}
            alt="Preview Final Image"
            width={400}
            height={400}
            className={`${finalImagePath ? "border-2 border-white" : ""}`}
          />
        </div>
      )}

      {initialImagePath && !finalImagePath && (
        <p>
          Hang on :). Removing image background
          <span className="inline-block ml-2 animate-ping">...</span>
        </p>
      )}

      {finalImagePath && (
        <a
          className="w-80 lg:w-52 px-6 py-4 text-center bg-white text-black hover:bg-blue-200"
          href={finalImagePath}
          download="attraktives-hs"
        >
          Download Image
        </a>
      )}
    </div>
  );
}

As seen in the documentation, the SharedArrayBuffer object has some security requirements and hence two headers need to be set to cross-origin isolate the page where the library is being used. To add this, update your next.config.mjs config file like so:

/** @type {import('next').NextConfig} */
const nextConfig = {
  async headers() {
    return [
      {
        source: "/bg-remove",
        headers: [
          {
            key: "Cross-Origin-Opener-Policy",
            value: "same-origin",
          },
          {
            key: "Cross-Origin-Embedder-Policy",
            value: "require-corp",
          },
        ],
      },
    ];
  },
};

export default nextConfig;

This is what the result looks like. Works like magic!

This app doesn’t require a license so you can use it as much as you want here (I deployed the finished code and will probably make more changes later to make the experience better). For first-time use, the WASM and ONNX model files are fetched in the browser and this might take some time depending on your bandwidth. But it would be faster for subsequent requests since the files are cached. Give it a spin and feel free to share it with your friends and enemies too :).

Bonus: Building a Canva-Like Design Editor

So far, we’ve explored how to use the CE.SDK Engine (@cesdk/engine). But there’s also the CE.SDK (@cesdk/cesdk-js) that offers more customizable editing UI components (more like a full-suite Canva-like design editor experience). You get the chance to customize the editor as much as your need requires. I won’t go into much detail here since we’ve covered quite a lot already but you can read the documentation to learn more. To test this quickly, you can add the code below in the /coomponents/editorCanvas.tsx:

"use client";
import { useEffect, useRef } from "react";
import { UserButton } from "@clerk/nextjs";
import CreativeEditorSDK, { Configuration } from "@cesdk/cesdk-js";
import { useRouter } from "next/navigation";

export default function EditorPage() {
  const cesdk_container = useRef(null);
  const router = useRouter();

  const config: Configuration = {
    license: process.env.NEXT_PUBLIC_CESDK_LICENSE,
    userId: "guides-user",
    baseURL: "https://cdn.img.ly/packages/imgly/cesdk-js/1.24.0/assets",
    ui: {
      elements: {
        view: "default",
        navigation: {
          show: true,
          action: {
            close: true,
            back: true,
            load: true,
            save: true,
            export: {
              show: true,
              format: ["application/pdf", "image/png"],
            },
            download: true,
          },
        },
        panels: {
          settings: {
            show: true,
          },
        },
      },
    },
    callbacks: {
      onUpload: "local",
      onBack: () => {
        router.push("/start");
      },
      onClose: () => {
        router.push("/start");
      },
    },
  };

  useEffect(() => {
    const container = cesdk_container.current!;
    if (container) {
      CreativeEditorSDK.create(container, config).then(async (instance) => {
        instance.addDefaultAssetSources();
        instance.addDemoAssetSources({ sceneMode: "Design" });
        await instance.createDesignScene();
      });
    }
  });

  return (
    <>
      <div className="flex flex-col items-center p-2">
        <UserButton afterSignOutUrl={"/start"} />
      </div>
      <div
        ref={cesdk_container}
        style={{ width: "100vw", height: "100vh" }}
      ></div>
    </>
  );
}

The setup is similar to the previous we covered. All we need to do now is add the following code in the /editor/page.tsx file to render the component above in a page (/editor in this case):

import dynamic from "next/dynamic";

const CreativeEditorSDKWithNoSSR = dynamic(
  () => import("../components/editorCanvas"),
  {
    ssr: false,
  }
);

export default CreativeEditorSDKWithNoSSR;

With this, your canvas should looks like the amazing screenshot below!

Authentication and Protected Pages with Clerk

If you observed, I imported a @clerk/nextjs package in the snippet above. That’s Clerk, a complete suite of embeddable UIs, flexible APIs, and admin dashboards to authenticate and manage users. By installing the SDK package and importing a few components, you can setup auth routes, authenticate users, and protect certain pages from unauthenticated access. The major configuration is done in the /middleware.ts file as seen in the code snippet below where I specify the /editor route to protect (will not be accessible unless the user signs in). You can learn more by reading Clerk’s Nextjs documentation and exploring my setup in the repository.

import { clerkMiddleware, createRouteMatcher } from "@clerk/nextjs/server";

const isProtectedRoute = createRouteMatcher(["/editor"]);

export default clerkMiddleware((auth, req) => {
  if (isProtectedRoute(req)) auth().protect();
});

export const config = {
  matcher: ["/((?!.+\\.[\\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
};

Conclusion

Phew (happy sigh 😅)! That was quite some learning and building! Trust me, there’s so much more you can do with the CE.SDK Engine and CE.SDK; we only attempted to scratch the surface in this tutorial. But I believe you’ve learned some new things here and this gives you a good foundation to get started with and then you can further your learning (I’ve attached some helpful resources in the next section that you might want to check out). Do let me know what you think and how helpful all of the information is to you! I’m keen to hear what you plan to build next with CE.SDK or any use case you have in mind (feel free to leave a comment below). You can explore the code on GitHub too. Thanks for reading this far!

Further Resources

• CreativeEditor SDK documentation.

• CreativeEditor SDK collection of examples (for different platforms).

• Collection of preconfigured starter-kits.

• Clerk guides and resources.

Friendly disclaimer: This is not a paid promotional for IMGLY or so :). I built this app and wrote this tutorial months ago as part of an interview process and I’m happy to share my learnings with everyone as always. I hope you still find the content useful; there’s quite a lot you can learn here. Cheers!

After building some demos, I came up with a simple chatbot implementation. In this tutorial, we will build a conversational text and voice chatbot with full-stack Nextjs, OpenAI, and ElevenLabs. A user would be able to ask a question by text and get an audio and text response. Sounds interesting to you? Then Let’s get into it! If you want to see the code, you can head to this repository now, but you might want to read along to learn one or two things, especially if you’re new to this :).

Prerequisites

To get the best out of this tutorial, you need to have/do the following:

• Nodejs and NPM installed on your computer.

• An IDE and terminal installed on your computer (I use Visual Studio Code!).

• A web browser installed on your computer (I use Arc!).

• Some prior knowledge of the JavaScript and TypeScript programming language.

• Some prior knowledge of the Reactjs JavaScript library.

• Some prior knowledge of the Nextjs JavaScript framework.

• A smile on your face :).

Chatbot Implementation Flow

Since our goal is to allow a user to ask a question by text and get an audio response, we would need to:

1. Build a user interface with an input element for receiving the text input.

2. Send the text input to OpenAI using their API and receive a text response.

3. Send the received text response to ElevenLabs using their API and receive an audio response.

4. Return the final results (text response from OpenAI and audio response from ElevenLabs) to the user in the same user interface.

Key Concepts

Now that we have a draft implementation flow designed, let’s briefly talk about some key concepts and the core tools we will be using for this application (specifically, OpenAI’s GPT and ElevenLabs’ Speech Synthesis Models) in the sections below.

AL and LLM Terms

The terms below should help you get acquainted with some of the concepts introduced in this tutorial, especially if you’re new to AI and LLMs.

OpenAI’s GPT (Generative Pre-trained Transformers)

OpenAI is an AI research company building artificial general intelligence (AGI). They’ve built several models (you can explore the full list here), but for this tutorial, we will use the GPT text generation model through the Chat Completions API. OpenAI uses its large language model to build ChatGPT and also provides the LLM as an API for developers to build their own applications. This allows developers to build creative stuff powered by AI for different use cases. I’m sure in the past year, you have seen almost every startup include some AI feature in their product, like GitHub Copilot, Notion AI, Grammarly AI, Vercel’s v0, tldraw make a real, etc. These startups either build their own in-house model or use OpenAI’s GPT or DALL-E or Whisper models (or other similar models like Meta's LLaMA, Google’s Gemini, Anthropic’s Claude, Midjourney, Mistral AI, Stability AI, etc.). I’m sure many like myself started hearing more about LLMs from the launch of ChatGPT for consumers, but many companies have been building AI tools for years now, like Microsoft’s Sketch2Code, amongst many others.

ElevenLabs Speech Synthesis

ElevenLabs has created realistic AI audio models, providing the ability to generate speech in hundreds of voices in 25+ languages. You can design brand new synthetic voices from scratch, clone your own voice, or use one from their voice library for speech synthesis (text-to-speech or speech-to-speech), creating audiobooks, or even video translations. Using their API to generate audio from text is quite straightforward, as seen in the code snippet below. You can also look at this sandbox repository I created with quick examples of making requests with ElevenLabs’ API and client libraries (JavaScript and Python).

async function generateAudio() {
  const voiceId = "IKne3meq5aSn9XLyUdCD";

  const response = await fetch(
    `https://api.elevenlabs.io/v1/text-to-speech/${voiceId}`,
    {
      method: "POST",
      headers: {
        Accept: "audio/mpeg",
        "Content-Type": "application/json",
        "xi-api-key": process.env.ELEVENLABS_API_KEY,
      },
      body: JSON.stringify({
        model_id: "eleven_multilingual_v2",
        text: "Hi, I'm Bolaji Ayodeji. How are you doing today?",
        voice_settings: { similarity_boost: 0.5, stability: 0.5 },
      }),
    }
  );

  await fs.writeFile("audio-js.mp3", await response.buffer(), "binary");
  console.log("Audio file saved successfully!");
}

Here’s a sample output of the request above using a random voice selection:

I also used their dubbing feature to translate the audio in this summary video below of myself and other speakers at InfoBip’s Shift conference to French. Now, I can argue with you that I was born in Paris 😅.

Just kidding. Anyway, let’s get back to the tutorial :).

Getting Started

To get started, use create-next-app to set up a new Nextjs project with TypeScript and App Router like so:

npx create-next-app@latest

Next, create some extra directories and files, as seen in the file structure below (the directories with an asterisk * beside the name are the extras):

┌── app
    ├── api*
       ├── chat
         ├── route.ts
       ├── speech
         ├── route.ts
    ├── chat*
      ├── page.tsx
    ├── components*
      ├── chatControls.tsx
      ├── chatInput.tsx
      ├── chatMessages.tsx
      ├── chatVoice.tsx
    ├── hooks*
      ├── useLocalStorage.ts
    ├── types*
      ├── chat.ts
    ├── utils*
      ├── getVoices.ts
      ├── notifyUser.ts
    ├── layout.tsx
    ├── page.tsx
┌── public
├── .env.local
...
├── package.json
└── tsconfig.json

Next, install ElevenLabs’ TypeScript SDK and the React Toastify library using the command below:

npm install elevenlabs react-toastify

Now, let’s generate API keys on both platforms we will be using.

Setting up OpenAI

Kindly follow the steps below to create an OpenAI developer account and generate an API key:

1. Visit this website and create a new account.

2. Upon successful signup, you will be redirected to a new page. Select the “API” card displayed.

3. On the left side of the page, click “API Keys”, and this will take you to the desired page.

4. Now click the “Create new secret key” button and create a new API key. Once you do that, copy the key and add it to the .env.local file you created earlier (i.e., OPENAI_API_KEY=<the key here>).

5. When you create a new account, you might get some free credits for your first few requests. If you exhaust that, you will need to buy some credits. All you have to do is click on "Settings" on the left side of the page and select "Billing" and this will take you to the desired page. Now click the "Add to credit balance" button to top up any amount you want (at least $5).

Setting up ElevenLabs

Kindly follow the steps below to create an ElevenLabs account and generate an API key:

1. Visit this website and create a new account.

2. Upon successful signup, you will be redirected to a new page. At the bottom left section of the page, select the icon displayed, click on your name, and click on the “Profile + API” option.

3. You should see a pop-up with an API key displayed. Copy the key and add it to the .env.local file you created earlier (i.e., ELEVENLABS_API_KEY=<the key here>). You can also regenerate a new API key here anytime you want by clicking the 🔄 button.

4. When you create a new account, you might get free 10,000 characters per month which should be sufficient. If you exhaust that and you want more, you can upgrade your plan in the "Settings > Subscription" page.

Chatbot Implementation

Now that we have our API keys ready, we can proceed to implement the project. With Nextjs, you can create APIs (API Routes) and there are so many ways to fetch data on the client or server-side aside. But since we’re using the latest version of Nextjs, we can experiment with the new Route Handlers and Server Actions.

• Route Handlers are a replacement for the previous API Routes and can be defined in directories anywhere in the app directory, inside a route.js or route.ts file. A good convention is to define them in a /app/api subdirectory.

• Server Actions are asynchronous functions that are executed on the server and can be used in both Server and Client components to handle form submissions and data mutations. In a Server Component, you must use the "use server" directive at an inline function or module level and in a Client Component, you must import another file that uses the "use server" directive at the module level. You can watch this video to learn more about this concept and it's benefits.

Now that we're up to speed, let's proceed with building our API. We will create a public API to fetch data from OpenAI and ElevenLabs and then use the APIs somewhere in the UI upon user request to generate responses.

Type Interfaces

First, let's define all the type interfaces we will import across the project in the /app/types/chat.ts file, as seen in the code below:

import { Voice as VoiceResponse } from "elevenlabs/api";

export const userRole = "user";
export const botRole = "assistant";

export interface Message {
  role: typeof userRole | typeof botRole;
  content: string;
}

export interface ChatVoiceProps {
  voices: VoiceResponse[];
  selectedVoice: string;
  setSelectedVoice: (voice: string) => void;
}

export interface ChatMessagesProps {
  messages: Message[];
}

export interface ChatInputProps {
  input: string;
  setInput: (input: string) => void;
  loading: boolean;
  sendMessage: (e: React.FormEvent<HTMLFormElement>) => void;
}

export interface ChatControlsProps {
  audioRef: React.RefObject<HTMLAudioElement>;
  savedAudio: boolean;
  messages: Message[];
  clearMessages: () => void;
}

API for OpenAI Requests

Now, let's create a new API. In the /app/chat/route.ts file, add the code below:

import { Message } from "@/app/types/chat";

export const runtime = "edge";

export async function POST(req: Request) {
  const { messages } = await req.json();

  messages.map((message: Message) => {
    if (message.role === "user") {
      message.content = `Imagine you are Siri, Apple's digital assistant and a user asks you the question: "${message.content}". Kindly generate a suitable response.`;
    }

  const res = await fetch("https://api.openai.com/v1/chat/completions", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.OPENAI_API_KEY}`
    },
    body: JSON.stringify({
      model: "gpt-3.5-turbo",
      max_tokens: 100,
      temperature: 0.7,
      n: 1,
      messages
    })
  });
  const data = await res.json();

  if (data.error && data.error.code === "invalid_api_key") {
    return Response.json("Something went wrong. Kindly check for error alerts.", {
      status: 401
    });
  }

  const output = data.choices[0]?.message?.content?.trim();

  return Response.json(output);
}

Here, we make a POST request to OpenAI’s Chat Completion API, passing in the messages value from the UI. The request’s body expects the following parameters:

• model: the ID of the model to use. You can explore the list of all the available models, including how they affect your API credits. For this tutorial, we will use the gpt-3.5-turbo model since it's more cost-effective.

• max_tokens: The maximum number of tokens that can be generated in the chat completion. Generally, one token is equivalent to ~4 characters of English text.

• temperature: Values between 0 and 2 that determine how GPT should generate a response. Higher values will lead to more random or creative responses, while lower values will lead to more focused and deterministic outputs.

• n: The number of chat completion choices GPT will generate for each input message. If you want to offer your users multiple options, then you should change this parameter, but for our use case, one is fine.

• messages: A list of messages of the entire conversation. This will be an array of objects, with each object containing messages from either the user, GPT, or both. Each object must contain:

  • role: who’s sending the message (either user, system, assistant or tool)

  • content: the content of the message (e.g., How can I fry plantain?)

[
   {
     "role": "user",
     "content": "Hello world!"
   },
   {
     "role": "system",
     "content": "Hello! How can I assist you today?"
   },
   {
     "role": "user",
     "content": "How can I fry plantain?"
   },
   {
     "role": "system",
     "content": "Frying plantains is a straightforward process..."
   }
   ...
];

To learn more about each of these parameters and the other available options, read OpenAI’s API Reference documentation or read the LLM Settings section of this Prompt Engineering Guide (highly recommend!). When a request is made to this API route, it returns an object like the code snippet below, and we will then render the data to the UI.

{
  id: 'chatcmpl-5sDSChIREMEImOpENToworK',
  object: 'chat.completion',
  created: 1377924170,
  model: 'gpt-3.5-turbo-0613',
  choices: [
      {
          index: 0,
          message: { role: 'assistant', content: 'Hello! How can I assist you today?' },
          logprobs: null,
          finish_reason: 'stop'
        }
    ],
  usage: { prompt_tokens: 219, completion_tokens: 9, total_tokens: 228 },
  system_fingerprint: null
}

API for ElevenLabs Requests

Next, let's create a new API. In the /app/speech/route.ts file, add the code below:

import { ElevenLabsClient } from "elevenlabs";

export async function POST(req: Request) {
  const { message, voice } = await req.json();

  const elevenlabs = new ElevenLabsClient({
    apiKey: process.env.ELEVENLABS_API_KEY
  });

  try {
    const audio = await elevenlabs.generate({
      voice,
      model_id: "eleven_turbo_v2",
      voice_settings: { similarity_boost: 0.5, stability: 0.5 },
      text: message
    });

    return new Response(audio as any, {
      headers: { "Content-Type": "audio/mpeg" }
    });
  } catch (error: any) {
    console.error(error);
    return Response.json(error, { status: error.statusCode });
  }
}

Here, we make a POST request to ElevenLabs’ Text-to-Speech API, passing in the voice and text values from the UI. The request’s body expects the following parameters:

• voice: the name of the voice to be used in generating the audio. ElevenLabs offers pre-made and community-created voices in 29 languages, but only about 35+ are added by default to your account. To add more, explore the voice library or make a new voice.

• model_id: the ID of the model to use. These are the available options as extracted from the /models API:

• voice_settings: the settings to override the default stored voice settings of the voice in use. You can learn more about the options for this in this documentation.

• text: the text message you want to convert to speech.

To learn more about each of these parameters and the other available options, read ElevenLabs’ API Reference documentation. When a request is made to this API route, it returns a Blob object ReadableStream raw data. Since we’re working on the web, we can’t use the play() function that comes with the SDK to play the audio directly. We will then have to process this Blob object to work inside a <audio> element.

Composing the Nextjs UI (Utility Files)

First, add the code below in the /app/utils/getVoices.ts file to fetch voices from ElevenLabs (all voices in your account). If you created a cloned voice or generated a new one, they all will be returned from the API.

"use server";

import { ElevenLabsClient } from "elevenlabs";

export default async function getVoices() {
  const elevenlabs = new ElevenLabsClient({
    apiKey: process.env.ELEVENLABS_API_KEY,
  });

  try {
    const allVoices = await elevenlabs.voices.getAll();
    return allVoices.voices;
  } catch (error) {
    console.error(error);
  }
}

Next, add the code below in the /app/utils/notifyUser.ts file. We will use this to display alerts using the React Toastify library.

import { toast } from "react-toastify";
import type { ToastContent, ToastOptions } from "react-toastify";

export default function notifyUser(
  message: ToastContent,
  options: ToastOptions
) {
  toast(message, {
    position: "top-right",
    theme: "light",
    hideProgressBar: true,
    closeOnClick: true,
    pauseOnHover: true,
    draggable: true,
    pauseOnFocusLoss: false,
    ...options,
  });
}

You will also need to addd<ToastContainer> and the ReactToastify.min.css CSS file in app/layout.tsx to make the library work like so:

import { ToastContainer } from "react-toastify";
import "react-toastify/dist/ReactToastify.min.css";

export default function RootLayout({
  children
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body>
        {children}
        <ToastContainer stacked />
      </body>
    </html>
  );
}

Composing the Nextjs UI (Hooks)

Add the code below in the /app/hooks/useLocalStorage.ts file to save and get data from localStorage and useState. We will reuse this multiple times later to store data like the messages and selected voice.

import { useEffect, useState } from "react";

export default function useLocalStorage<T>(key: string, initialValue: T): [T, (value: T) => void] {
  const [savedValue, setSavedValue] = useState(initialValue);

  useEffect(() => {
    const item = localStorage.getItem(key);
    if (item) setSavedValue(JSON.parse(item));
  }, [key]);

  const updateValue = (value: T) => {
    setSavedValue(value);
    localStorage.setItem(key, JSON.stringify(value));
  };
  return [savedValue, updateValue];
}

Composing the Nextjs UI (Chat Page)

Now that we have created our API routes, we will create and import a couple of components inside the /app/chat/page.tsx file (this is the file that renders the UI on the /chat slug) as seen below. If you’re familiar with Reactjs, you should be able to understand what’s going on here. However, I have added comments to summarize each part of the logic. Kindly read through them slowly for some more context.

"use client";

// Import all we need.
import { useState, useEffect, useRef } from "react";
import ChatVoice from "@/app/components/chatVoice";
import ChatMessages from "@/app/components/chatMessages";
import ChatControls from "@/app/components/chatControls";
import ChatInput from "@/app/components/chatInput";
import useLocalStorage from "@/app/hooks/useLocalStorage";
import getVoices from "@/app/utils/getVoices";
import notifyUser from "@/app/utils/notifyUser";
import { userRole, botRole, Message } from "@/app/types/chat";
import { Voice as VoiceResponse } from "elevenlabs/api";

export default function ChatPage() {
  // Ref hook to update the audio element.
  const audioRef = useRef<HTMLAudioElement>(null);

  // Store the list of voices.
  const [voices, setVoices] = useState<VoiceResponse[]>([]);

  // Store the name of the selected voice.
  const [selectedVoice, setSelectedVoice] = useLocalStorage<string>("selectedVoice", "Myra");

  // Store the message the user enters in the input field.
  const [input, setInput] = useState("");

  // Store the list of all messages (user and bot).
  const [messages, setMessages] = useLocalStorage<Message[]>("chatMessages", []);

  // Store the state of generating a response.
  const [loading, setLoading] = useState<boolean>(false);

  // Store the state of generating the audio response.
  const [savedAudio, setSavedAudio] = useState<boolean>(false);

  // Function to make a request to the /chat API route (JSON response).
  const getOpenAIResponse = async (chatMessages: Message[]) => {
    const response = await fetch("/api/chat", {
      method: "POST",
      headers: {
        "Content-Type": "application/json"
      },
      body: JSON.stringify({ messages: chatMessages })
    });

    // Notify the user if the API Key is invalid.
    if (response.status === 401) {
      notifyUser("Your OpenAI API Key is invalid. Kindly check and try again.", {
        type: "error",
        autoClose: 5000
      });
    }

    const data = await response.json();
    return data;
  };

  // Function to make a request to the /speech API route (BLOB response).
  const getElevenLabsResponse = async (text: string) => {
    const response = await fetch("/api/speech", {
      method: "POST",
      headers: {
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        message: text,
        voice: selectedVoice
      })
    });

    // Notify the user if the API Key is invalid.
    if (response.status === 401) {
      notifyUser("Your ElevenLabs API Key is invalid. Kindly check and try again.", {
        type: "error",
        autoClose: 5000
      });
    }

    const data = await response.blob();
    return data;
  };

  // When the user clicks the submit button, this function runs.
  const sendMessage = async (event: React.FormEvent<HTMLFormElement>) => {
    event.preventDefault();

    // Set the loading state to true.
    setLoading(true);
    // Clear the input field.
    setInput("");

    // Store all messages from the user in an array of objects.
    const chatMessages: Message[] = [...messages, { role: userRole, content: input }];
    setMessages(chatMessages);

    // Make a request to OpenAI with the user's message.
    // For subsequent requests, this will include previous messages.
    const botChatResponse = await getOpenAIResponse(chatMessages);

    // Make a request to ElevenLabs with the current response from OpenAI.
    const botVoiceResponse = await getElevenLabsResponse(botChatResponse);

    // Read the contents of the Blob file using JavaScript's FileReader
    // https://developer.mozilla.org/en-US/docs/Web/API/FileReader.
    const reader = new FileReader();
    // Start reading the contents of the Blob file
    // Once finished, the `result` attribute will contain the
    // URL representing the file's data (base64 encoded string).
    reader.readAsDataURL(botVoiceResponse);
    reader.onload = () => {
      if (audioRef.current) {
        // Pass the file to the <audio> element's src attribute.
        // Will look like: data:audio/mpeg;base64,//uQxAAAC213G6GI0ZA8...
        audioRef.current.src = reader.result as string;
        // Immediately play the audio file.
        audioRef.current.play();
      }
    };

    // Add the bot's response to all the stored messages.
    setMessages([...chatMessages, { role: botRole, content: botChatResponse }]);
    // Set the loading state to false.
    setLoading(false);
    // Set the state of the audio to saved.
    setSavedAudio(true);
  };

  // Function to clear all messages from local storage.
  const clearMessages = async () => {
    setMessages([]);
    localStorage.removeItem("chatMessages");
  };

  useEffect(() => {
    // Fetch the voices from the getVoices() utility and store them.
    getVoices()
      .then((voices) => {
        setVoices(voices ?? []);
      })
      .catch((error) => {
        console.error("Error fetching voices:", error);
      });
  }, []);

  return (
    <main className="flex flex-col min-h-screen items-center justify-between py-4 px-4 lg:px-0">
      {voices.length === 0 ? (
        <p className="text-white text-9xl animate-ping">...</p>
      ) : (
        <>
          <ChatVoice {...{ voices, selectedVoice, setSelectedVoice }} />
          <ChatMessages {...{ messages }} />
          <div className="flex flex-col items-center w-full fixed bottom-0 pb-3 bg-gray-900">
            <ChatControls
              {...{
                audioRef,
                savedAudio,
                messages,
                clearMessages
              }}
            />
            <ChatInput
              {...{
                input,
                setInput,
                loading,
                sendMessage
              }}
            />
          </div>
        </>
      )}
    </main>
  );
}

In summary, we use the useState, useEffect, and useRef react hooks to set up some states, fetch data from our API, fetch the voices from the utility function, run some logic to process the data, and render the UI passing in the destructed prop values to the ChatVoice, ChatMessages, ChatControls, and ChatInput components.

Composing the Nextjs UI (Components)

Now let's add the code for all the components we used earlier in the /chat page.

1️⃣: In the /app/components/chatVoice.tsx file, add the code below:

import { ChatVoiceProps } from "@/app/types/chat";

export default function ChatVoice({ voices, selectedVoice, setSelectedVoice }: ChatVoiceProps) {
  return (
    <div className="flex flex-col w-full z-10 fixed top-0 text-center items-center bg-gray-900">
      <div className="p-4 lg:p-8 lg:w-3/4 xl:w-2/4 border-0 lg:border-x-2 lg:border-white">
        <label className="mb-2 block text-sm lg:text-base" htmlFor="voices">
          Change Siri&apos;s Voice:
        </label>
        <select
          id="voices"
          name="voices"
          className="p-2 w-4/4 text-sm lg:text-base appearance-none bg-transparent border border-white text-blue-500"
          value={selectedVoice}
          onChange={(event) => setSelectedVoice(event.target.value)}
        >
          {voices && voices
            .sort((a, b) => (a.name!.localeCompare(b.name!))
            .map((voice) => (
              <option key={voice.voice_id} value={voice.name}>
                {voice.name} ({voice.labels?.age} {voice.labels?.accent} {voice.labels?.gender})
              </option>
            ))}
        </select>
      </div>
      <hr className="w-full lg:w-3/4 xl:w-2/4" />
    </div>
  );
}

2️⃣: In the /app/components/chatMessages.tsx file, add the code below.

import Image from "next/image";
import type { ChatMessagesProps } from "@/app/types/chat";

export default function ChatMessages({ messages }: ChatMessagesProps) {
  return (
    <div className="absolute mt-20 lg:mt-40 pt-16 pb-48 px-6 w-full lg:w-3/4 xl:w-2/4 border-0 lg:border-x-2 lg:border-white">
      {messages && messages.length === 0 ? (
        <div className="flex flex-col items-center">
          <Image
            src="/logo.svg"
            className="mt-20"
            alt="Chat With Siri Logo"
            width={650}
            height={10}
            priority
          />
          <h2 className="text-xl text-center mt-12 animate-none lg:animate-bounce">
            Hi there! How can I help you today?
          </h2>
        </div>
      ) : (
        messages.map((message, index) => (
          <div key={index} className="my-6 lg:my-10">
            {message.role === "assistant" ? (
              <div className="flex mb-2 lg:mb-4">
                <Image src="/bot.svg" alt="Robot Icon" width={20} height={20} priority />
                <span className="ml-2 text-md lg:text-lg font-semibold text-blue-500">Siri:</span>
              </div>
            ) : (
              <div className="flex mb-2 lg:mb-4">
                <Image src="/face.svg" alt="Face Icon" width={18} height={18} priority />
                <span className="ml-2 text-md lg:text-lg font-semibold text-teal-500">You:</span>
              </div>
            )}
            <span className="text-md lg:text-lg">{message.content}</span>
          </div>
        ))
      )}
    </div>
  );
}

3️⃣: In the /app/components/chatControls.tsx file, add the code below.

import Image from "next/image";
import type { ChatControlsProps } from "@/app/types/chat";

export default function ChatControls({
  audioRef,
  savedAudio,
  messages,
  clearMessages
}: ChatControlsProps) {
  return (
    <div className={`flex ${messages.length > 0 ? `block` : `hidden`}`}>
      <button
        title="Replay audio response"
        disabled={!savedAudio}
        onClick={() => audioRef.current && audioRef.current.play()}
      >
        <Image src="/play.svg" alt="Plus Icon" width={40} height={24} priority />
      </button>
      <button
        title="Start new chat"
        onClick={clearMessages}
        className="p-2 border-white text-black"
      >
        <Image src="/plus.svg" alt="Plus Icon" width={40} height={24} priority />
      </button>
      <audio ref={audioRef} controls className="mb-2 hidden" />
    </div>
  );
}

4️⃣: In the /app/components/chatInput.tsx file, add the code below.

import type { ChatInputProps } from "@/app/types/chat";

export default function ChatInput({ input, setInput, loading, sendMessage }: ChatInputProps) {
  return (
    <form onSubmit={sendMessage}>
      <label className="hidden" htmlFor="message">
        Enter your message here:
      </label>
      <input
        id="message"
        name="message"
        value={input}
        placeholder="What's on your mind?..."
        onChange={(event) => setInput(event.target.value)}
        className="w-56 md:w-72 lg:w-96 p-4 border-2 text-white bg-transparent focus:outline-none"
      />
      <button
        type="submit"
        title="Send message"
        disabled={input.trim() === "" || input.trim().length < 5}
        className="w-24 md:w-24 lg:w-auto px-4 lg:px-8 py-4 border-2 border-white bg-white text-black"
      >
        {loading ? <p className="animate-spin">⏳</p> : "Ask Siri"}
      </button>
    </form>
  );
}

Now visit http://localhost:3000/chat to view the finished and functional UI. The screenshot below shows a breakdown of the four (4) components in different parts of the chat page.

In summary, a user can:

• Ask a question by text and get a text and audio response.

• Change the voice of the audio response (40+ options).

• Start a new chat session (the plus button).

• Replay the last audio response (the play button).

Here’s a quick video where I demoed the finished application and quickly walked through all the moving parts of the code:

Notes and Recommendations

There are a couple of things we can improve in this demo. If your users will be generating responses with a long amount of text, there would be increased latency and some delay before the final audio response is delivered, especially since we have to wait for OpenAI to respond with the full text and then ElevenLabs with the complete audio. A common solution to building conversational UIs like this is streaming the responses. Streaming allows you to receive the responses in chunks and send them to the UI bit by bit, offering a better loading user experience. Both OpenAI and ElevenLabs support streaming. We can then use Server Side Events (SSE) or Websockets to process the chunks of data returned during streaming.

In a future tutorial, I will explain how to extend this demo to support streaming. In that version, we should be able to stream the response from OpenAI and pass the chunks of the stream to ElevenLabs, leading to reduced latency. For now, take some time to study how Server Side Events and EventSource Web API work, just like I would be doing. Vercel has also built an AI SDK you can use to build conversational streaming user interfaces in both JavaScript and TypeScript. The SDK supports multiple frontend frameworks, and they have example templates for different LLM providers (they call them adapters). With their SDK, you can use some wrappers to build the streaming logic without bothering about the underlying moving parts.

For now, I used the ElevenLabs eleven_turbo_v2 model since I’m working with just the English language, and it’s more suitable for tasks demanding low latency like ours (you can read this guide to learn more) and intentionally set the max_tokens OpenAI parameter to 100. I also added a hack in the OpenAI prompt to reduce the number of characters returned like so:

  messages.map((message: Message) => {
    if (message.role === "user") {
      message.content = `Imagine you are Siri, Apple's digital assistant 
and a user asks you the question: "${message.content}". 
Kindly generate a suitable response with less than 100 characters.`;
    }
  });

This way, we reduce the response time, and I also get to maximize API credits 😉. For this demo, this works fine, and GPT will respond to every question with the best response that fits into a hundred characters. Thank you for reading this far! Don’t forget to share this article and give the finished project a star.

Conclusion

So far, we’ve built a simple chatbot using Nextjs App Router, OpenAI, and ElevenLabs. If this is your first time doing this, I’m sure you have learned quite some new things. There’s so much more you can experiment with this, and I’m looking forward to seeing them (please leave a comment if you want). You can now go ahead and fork the project, extend the features for your own ideas, or even contribute to the code.

Further Learning

To learn more about each of the tools we used in this tutorial, kindly take a look at the following helpful resources. I’m sure you’d love them.

In this article, you'll learn how to automate your GitHub README Profile so that it can update itself anytime you want. We will make this possible using a custom script built with Nodejs/TypeScript, markdown-it library, GitHub API, RSS feeds, and GitHub Actions. If you want to see the code, you can head to this repository, but you should read along to learn one or two things you can apply in other use cases (especially if you're new to writing automated scripts).

Prerequisites

To get the best out of this tutorial, you need to know/do the following:

• Have an existing GitHub account.

• Read the first article and create your README profile.

• Have Nodejs and NPM installed on your computer.

• Some prior knowledge of the JavaScript programming language.

The Problem

GitHub allows you to pin only six (6) repositories on your profile. I wanted to highlight more repositories while retaining the existing ones in the most minimal way possible (without having to use these kinds of badges). I also wanted a way to highlight some content from my newsletter so I can get some traffic from there and potentially new subscribers that fit my target audience. I remember seeing some profiles in the past that listed their latest blog posts or music they were listening to. So I researched, found some of those profiles, and discovered they ran a script that automatically generated their markdown file. I then decided to make mine.

The Proposed Solution

Generally, the README file is written in markdown, a markup language for creating formatted text. The goal is to simultaneously generate the entire markdown file, including the static and dynamic sections. This includes the badges, open-source statistics, and text descriptions. The new dynamic sections are the following:

• List of selected GitHub repositories.

• List of my recent blog posts.

• List of my recent newsletters.

Getting Started

We can easily use markdown-it, a markdown parser for rendering a mix of JavaScript and plain text into a markdown file. To get started, kindly create a new directory with the following file structure:

┌── .github
    ┌──  workflows
        ├── build.yml
┌── src
    ├── app.ts
    ├── fetchGitHubData.ts
    ├── fetchRssData.ts
├── package.json
└── tsconfig.json

Next, install the required packages using the command below:

npm install fs markdown-it rss-parser tsc-watch

npm install --save-dev @types/node

I'm using TypeScript and will use ts to compile to JavaScript during the build. My tsconfig.json and package.json scripts file looks looks like this:

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2015",
    "module": "commonjs",
    "strict": true,
    "moduleResolution": "node",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "outDir": "build"
  },
  "include": ["src/*"]
}

// package.json
{
  "name": "bolajiayodeji",
  "version": "1.0.0",
  "description": "Bolaji Ayodeji's GitHub Profile",
  "main": "src/app.ts",
  "scripts": {
    "build": "npx tsc",
    "build:watch": "npx tsc-watch",
    "start": "npm run build && node build/app.js",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
...
}

Fetching the Data from GitHub API

You can fetch different kinds of data with GitHub's API. There are two options: use the API directly or the Octokit.js library (this is the route GitHub recommends). I decided to use the API directly since the Octokit.js library included extra stuff I wouldn't need, which is an overkill for this use case.

To fetch a repository, you will use the https://api.github.com/repos/{owner}/{name} endpoint with some parameters. owner represents my GitHub username and name is the repository's name. A GET request should return a JSON data like so:

{
"id": 278287314,
"node_id": "MDEwOlJlcG9zaXRvcnkyNzgyODczMTQ=",
"name": "BolajiAyodeji",
"full_name": "BolajiAyodeji/BolajiAyodeji",
"private": false,
"owner": {
"login": "BolajiAyodeji",
"id": 30334776,
"node_id": "MDQ6VXNlcjMwMzM0Nzc2",
"avatar_url": "https://avatars.githubusercontent.com/u/30334776?v=4",
"gravatar_id": "",
"url": "https://api.github.com/users/BolajiAyodeji",
"html_url": "https://github.com/BolajiAyodeji",
...
},
"html_url": "https://github.com/BolajiAyodeji/BolajiAyodeji",
"description": "My automated GitHub Profile README built using TypeScript and GitHub Actions.",
...
"created_at": "2020-07-09T06:55:36Z",
"updated_at": "2023-11-11T09:25:16Z",
...
"stargazers_count": 4,
"watchers_count": 4,
"language": "TypeScript",
...
"open_issues_count": 0,
"license": {
"key": "mit",
"name": "MIT License",
...
},
...
"topics": [
"github-actions",
"github-api",
"hashnode",
"javascript",
...
],
"visibility": "public",
"forks": 19,
...
}

You can test this live yourself: api.github.com/repos/BolajiAyodeji/BolajiAyodeji.

If you make a request to GitHub's API using an access token through the Octokit.js library, you can make API requests without passing the owner parameter. GitHub will infer that from your token.

Now, we will create a fetchGitHubData() function in src/fetchGitHubData.ts that will accept an array of repository names as the parameter. This array will look like this:

[
  "BolajiAyodeji",
  "fed-unis-perf-eval",
  "movie_reviews_sentiment_analysis",
  "dotfiles"
];

Here's the function:

export async function fetchGitHubData(repos: Array<string>): Promise<string> {
  const owner = "BolajiAyodeji";

  const list = await Promise.all(
    repos.map(async (repo) => {
      const response = await fetch(`https://api.github.com/repos/${owner}/${repo}`);
      if (!response.ok) {
        throw new Error(`"${owner}/${repo}" not found. Kindy review your list of repositories.`);
      }
      const data = await response.json();

      const {
        html_url: url,
        full_name: name,
        stargazers_count: stars,
        forks_count: forks,
        description: desc
      } = data;

      return `<li><a href=${url} target="_blank" rel="noopener noreferrer">${name}</a> (<b>${stars}</b> ✨ and <b>${forks}</b> 🍴): ${desc}</li>`;
    })
  );

  return `<ul>${list.join("")}\n<li>More coming soon :).</li>\n</ul>`;
}

In the function above, we loop through the array, fetch data for all the repositories, and extract the following fields:

• html_url: link to the repository.

• full_name: name of the repository (including my username attached)

• stargazers_count: number of stars.

• forks_count: number of forks.

• description: description of the repository.

We then use the data to render an HTML list element (<li>) for each repository in the array, join all the lists together, add an additional static list element with custom text, and return an unordered HTML list element (<ul>). The final result should look like this:

This function is useless for now, but we will use it later in src/app.ts to render the markdown. Let's proceed!

Fetching the Data from RSS Feeds

We can use an RSS feed for the blog post and newsletter sections. According to Wikipedia, RSS (Really Simple Syndication) is a web feed written in XML (eXtensible Markup Language) that allows users and applications to access website updates in a computer-readable format. People use RSS to access the latest published content from a website page. Mostly, a user will use an RSS reader to access content from multiple XML files in an organized manner and read them.

My blog runs on Hashnode, which provides an rss.xml file by default on https://blog.bolajiayodeji.com/rss.xml. My newsletter also runs on Substack, which also provides an rss.xml file on https://bawd.bolajiayodeji.com/feed. So, each time a new post is added to my blog or newsletter, the RSS feed automatically includes the page's current data. This makes it a good data source for my GitHub Profile.

Since both RSS feeds are similar in structure, I can create a fetchRssData() function in src/fetchRssData.ts for both. We will first use the rss-parser library to turn the RSS XML feeds into JavaScript objects and then iterate to find the necessary fields.

The XML looks like this (view the image below live for a better experience):

The parsed version looks like this:

{
  "items": [
    {
      "creator": "Bolaji Ayodeji",
      "title": "My Developer Advocate Portfolio",
      "link": "https://blog.bolajiayodeji.com/my-developer-advocate-portfolio",
      "pubDate": "Mon, 28 Aug 2023 13:03:08 GMT",
      "dc:creator": "Bolaji Ayodeji",
      "content": "...",
      "contentSnippet": "...",
      "guid": "https://blog.bolajiayodeji.com/my-developer-advocate-portfolio",
      "isoDate": "2023-08-28T13:03:08.000Z"
    },
    { another item... }
    { more items... }
    {
      "creator": "Bolaji Ayodeji",
      "title": "How to Deploy a Machine Learning Model to the Web",
      "link": "https://blog.bolajiayodeji.com/how-to-deploy-a-machine-learning-model-to-the-web",
      "pubDate": "Sat, 03 Sep 2022 08:49:08 GMT",
      "dc:creator": "Bolaji Ayodeji",
    ...
    }
...
}

This is what the final function will look like:

import Parser from "rss-parser";
const parser = new Parser();

export async function fetchRssData(url: string): Promise<string> {
  const feed = await parser.parseURL(url);

  const list = feed.items.slice(0, 5).map((item) => {
    const date = new Date(item.pubDate as string);
    const publishedDate = `${date.getDate()}/${date.getMonth() + 1}/${date.getFullYear()}`;

    return `<li><a href=${item.link} target="_blank" rel="noopener noreferrer">${item.title}</a> (${publishedDate}).</li>`;
  });

  return `
  <ul>
    ${list.join("")}
  </ul>\n
  ${
    url.endsWith("rss.xml")
      ? `Read more blog posts: ${url.replace(/\/rss.xml$/, "")}`
      : `Read more newsletter issues: ${url.replace(/\/feed$/, "")}`
  }.
  `;
}

In the function above, we use the RSS link to fetch the data, extract just the first five items (posts), and extract the following fields:

• pubDate: timestamp for when the content was published.

• link: link to the post.

• title: title of the post.

We then use the data to render an HTML list element (<li>) for each published post, do some date formatting, join all the lists together, add an additional static list element with custom text, and return an unordered HTML list element (<ul>). The final result should look like this:

Generating the Final Markdown File

Now that we have the fetchGitHubData() and fetchRssData() functions, let's combine everything and generate the README.md file we need. In src/app.ts add the following code:

import * as fs from "fs";
const md = require("markdown-it")({
  html: true, // Enable HTML tags in source
  breaks: true, // Convert '\n' in paragraphs into <br>
  linkify: true // Autoconvert URL-like text to links
});
import { fetchRssData } from "./fetchRssData";
import { fetchGitHubData } from "./fetchGitHubData";

const blogFeedUrl = "https://blog.bolajiayodeji.com/rss.xml";
const newsletterFeedUrl = "https://bawd.bolajiayodeji.com/feed";

const ossProjectRepos = [
  "BolajiAyodeji",
  "fed-unis-perf-eval",
  "movie_reviews_sentiment_analysis",
  "dotfiles"
];
const ossLearningMaterialRepos = ["deploy-ml-web-workshop", "cl-composable-commerce-workshop"];

const githubUsername = "BolajiAyodeji";
const websiteUrl = "https://bolajiayodeji.com";
const blogUrl = "https://blog.bolajiayodeji.com";
const newsletterUrl = "https://bawd.bolajiayodeji.com";
const youtubeUrl = "https://youtube.com/c/bolajiayodeji";
const slidesUrl = "https://slides.com/bolajiayodeji";
const twitterUrl = "https://twitter.com/iambolajiayo";
const linkedinUrl = "https://linkedin.com/in/iambolajiayo";
const githubSponsorsUrl = "https://github.com/sponsors/BolajiAyodeji";
const patreonUrl = "https://patreon.com/bolajiayodeji";

async function generateMarkdown() {
  const websiteBadge = `[![Website Badge](https://img.shields.io/badge/-Website-3B7EBF?style=for-the-badge&logo=amp&logoColor=white)](${websiteUrl})`;
  const hashnodeBadge = `[![Blog Badge](https://img.shields.io/badge/-Blog-3B7EBF?style=for-the-badge&logo=Hashnode&logoColor=white)](${blogUrl})`;
  const substackBadge = `[![Newsletter Badge](https://img.shields.io/badge/-Newsletter-3B7EBF?style=for-the-badge&logo=Substack&logoColor=white)](${newsletterUrl})`;
  const youtubeBadge = `[![YouTube Badge](https://img.shields.io/badge/-Youtube-3B7EBF?style=for-the-badge&logo=Youtube&logoColor=white)](${youtubeUrl})`;
  const slidesBadge = `[![Slides Badge](https://img.shields.io/badge/-Slides-3B7EBF?style=for-the-badge&logo=slides&logoColor=white)](${slidesUrl})`;
  const linkedinBadge = `[![Linkedin Badge](https://img.shields.io/badge/-LinkedIn-3B7EBF?style=for-the-badge&logo=Linkedin&logoColor=white)](${linkedinUrl})`;
  const twitterBadge = `[![Twitter Badge](https://img.shields.io/badge/-@iambolajiayo-3B7EBF?style=for-the-badge&logo=x&logoColor=white)](${twitterUrl})`;
  const githubSponsorsBadge = `[![GitHub Sponsors Badge](https://img.shields.io/badge/-github%20sponsors-3B7EBF?style=for-the-badge&logo=github&logoColor=white)](${githubSponsorsUrl})`;
  const patreonBadge = `[![Patreon Badge](https://img.shields.io/badge/-Patreon-3B7EBF?style=for-the-badge&logo=Patreon&logoColor=white)](${patreonUrl})`;
  const profileCountBadge = `![Profile Views Count Badge](https://komarev.com/ghpvc/?username=${githubUsername}&style=for-the-badge)`;

  const githubStatsCardDark = `[![GitHub-Stats-Card-Dark](https://github-readme-stats.vercel.app/api?username=${githubUsername}&show_icons=true&hide_border=true&include_all_commits=true&card_width=600&custom_title=GitHub%20Open%20Source%20Stats&title_color=3B7EBF&text_color=FFF&icon_color=3B7EBF&hide=contribs&show=reviews,prs_merged,prs_merged_percentage&theme=transparent#gh-dark-mode-only)](https://github.com/${githubUsername}/${githubUsername}#gh-dark-mode-only)`;
  const githubStatsCardLight = `[![GitHub-Stats-Card-Light](https://github-readme-stats.vercel.app/api?username=${githubUsername}&show_icons=true&hide_border=true&include_all_commits=true&card_width=600&custom_title=GitHub%20Open%20Source%20Stats&title_color=3B7EBF&text_color=474A4E&icon_color=3B7EBF&hide=contribs&show=reviews,prs_merged,prs_merged_percentage&theme=transparent#gh-light-mode-only)](https://github.com/${githubUsername}/${githubUsername}#gh-light-mode-only)`;

  const markdownText = `<div align="center">\n

  ${websiteBadge} ${hashnodeBadge} ${substackBadge} ${youtubeBadge} ${slidesBadge} ${linkedinBadge} ${twitterBadge} ${githubSponsorsBadge} ${patreonBadge} ${profileCountBadge}\n

  ---\n

  Hi there 👋🏾! I'm an innovative technology professional with progressive IT, web engineering, data, embedded systems, developer relations, documentation, technical writing, open-source, community building, and entrepreneurship experience in for-profit startups and non-profit technology and education organizations. I create technical content, build open-source projects and learning materials, speak/teach at developer meetups/conferences, and build several technical communities.\n

  ---\n

  ${githubStatsCardDark}\n
  ${githubStatsCardLight}\n

  </div>\n

  ---\n

  ## Highlights

  <details>\n
  <summary>OSS Projects</summary>\n
  <br />
  Here are some of my other projects you might want to check out that are not pinned:\n
  <br />\n<br />
  ${await fetchGitHubData(ossProjectRepos)}\n
  </details>\n

  <details>\n
  <summary>OSS Learning Materials</summary>\n
  <br />
  Here are some of my unique-styled workshop materials you can use to learn key concepts at your own pace:\n
  <br />\n<br />
  ${await fetchGitHubData(ossLearningMaterialRepos)}\n
  </details>\n

  <details>\n
  <summary>Recent Blogposts</summary>\n
  <br />
  ${await fetchRssData(blogFeedUrl)}\n
  </details>\n

  <details>\n
  <summary>Recent Newsletters</summary>\n
  <br />
  ${await fetchRssData(newsletterFeedUrl)}\n
  </details>\n

  <details>\n
  <summary>Quick Tips</summary>\n\n
  - 💬 How to reach me: DM [@iambolajiayo](https://twitter.com/iambolajiayo) on X (Twitter).\n
  - 📬 Where to find me: Subscribe to my [newsletter](https://bawd.bolajiayodeji.com/subscribe) to hear from me bi-weekly or send a game request on [chess.com](https://chess.com/member/bolajiayodeji).\n
  - 📖 Book recommendations: [Knowing God by J. I. Packer](https://bit.ly/3EdCFUW) and [Atomic Habits by James Clear](https://bit.ly/45r1kBH).\n
  - 💙 Fun fact: I'm in a blissful relationship [with Jesus Christ](https://biblegateway.com/passage/?search=1+Corinthians+15%3A1-11&version=NKJV). Check [this](https://bit.ly/3KYYHij) out :).\n
  </details>\n

  ---\n

  <a href="#">Learn how this works.</a> <a href="https://github.com/BolajiAyodeji/BolajiAyodeji/actions/workflows/build.yml"><img src="https://github.com/BolajiAyodeji/BolajiAyodeji/actions/workflows/build.yml/badge.svg" align="right" alt="Rebuild README.md file"></a>\n

  <div align="center">\n
   <a href="https://bolajiayodeji.com" target="_blank" rel="noopener noreferrer"><img src="https://bolajiayodeji.com/favicon.png" width="30" /></a>\n
  </div>`;

  const result = md.render(markdownText);

  fs.writeFile("README.md", result, (error) => {
    if (error) throw new Error(`Something went wrong: ${error}.`);
    console.log(`✅ README.md file was succesfully generated.`);
  });
}

generateMarkdown();

Here, I manually add all the static markdown content that existed before (text, badges, etc.) in the markdownText variable, add the new dynamic sections with the functions, render the markdown file in the result variable, and create the markdown file using Node.js's fs.writeFile() method.

Setting up the CI/CD Pipeline with GitHub Actions

Now, to the cool part! So far, the major work has been done, and if I run npm run build and npm run start locally, a new README.md file will be generated, including any changes that come from the API and RSS feeds. But I shouldn't have to do this manually every time I want to change something, right? So what can we do?

That's where CI/CD and cron jobs come in.

CI/CD Pipeline

If you're new to this, CI/CD (which means Continuous Integration / Continuous Delivery or Deployment) is a process used in software engineering to merge code and automate specific repeated sequence of tasks (e.g., tests) that are required before and/or after deploying a software (e.g., releases) for users to access. In our case, we want to run the npm run start command on the cloud repeatedly on a fixed day/time and push the updated README file to the special GitHub repository using Git. This way, anytime a user views the GitHub profile, they see the latest content (the latest deployed version of the README based on the schedule). If there's an error, the process is expected to fail and return the errors in the log file.

This is a basic use case of CI/CD. For more extensive software, you would have a more complex pipeline (managed mainly by DevOps or SRE engineers) handling things like running unit/integration tests, updating data, release notes, etc.

Cron Jobs Scheduling

The scheduling would be handled with something called a Cron Job. This is the standard method of scheduling specific tasks on a server at fixed times. At the right time or interval, certain tasks (jobs) will be executed. If you're new to this concept, you might be able to visualize how this will work based on our Profile README use case. It doesn't make sense to update the README file every second since I'm not publishing new content every second. To avoid wasting resources, setting up a Cron Job to execute the logic daily or even weekly is ideal. With this, a user will still get the most recent content. You can adjust the schedule to fit your needs if you're doing this for another use case.

Cron jobs are composed of expressions. An expression includes a string of five fields (* * * * *) which will contain numbers and some special characters. The character asterisk (*) represents any value, comma (,) represents a list of values, hyphen (-) represents a range of values, and slash (\) represents a step of values. Each field represents the following:

1. Minute (0 - 59).

2. Hour (0 - 23).

3. Day of the month (1 - 31).

4. Month (1 - 12).

5. Day of the week (0 - 6 with 0 being Sunday).

A cron expression * * * * * will mean run every minute, */30 * * * * will mean run every 30 minutes, */30 7 * * * will mean run every 30 minutes between 07:00 and 07:59, */30 7-10 * * * will mean run every 30 minutes between 07:00 and 10:59, * 12-18 * * * will mean run every minute between 12:00 and 18:00, 0 12-18 * * * will mean run hourly between 12:00 and 18:00, 0 12-18 5 5 * will mean run hourly between 12:00 and 18:00 on the 5th day of March only, 0 12 * * * will mean run daily at 12:00, etc. There are so many permutations, and if you're interested, you can create, test, and practice different cron expressions using services like Cron Expression To Go or Crontab Guru.

GitHub Actions

You can set up a CI/CD pipeline using several tools like CircleCI, Travis CI, GitHub Actions, etc. We will use GitHub Actions for this use case since it's provided by the platform we're already using (but you can achieve the same with the others). GitHub Actions allows you to automate your build, test, and deployment pipeline with workflows inside a GitHub repository. These workflows can run on every pull request to your repository, merged pull requests, cron jobs, etc. You can learn more about GitHub Actions by reading this guide on GitHub Docs.

In the .github/workflows/build.yml, add the following code:

name: Profile README

on:
  push:
  workflow_dispatch:
  schedule:
    - cron: "0 6 * * *"

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repo
        uses: actions/checkout@v4
      - name: Use Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "18"
      - name: Install Dependencies
        run: npm install
      - name: Rebuild README.md File
        run: npm run start
      - name: Commit and Push if Changed
        run: |-
          git add .
          git diff
          git config --global user.email "mailtobolaji+actionsbot@gmail.com"
          git config --global user.name "BA Actions Bot"
          git commit -m "docs: auto-update README.md" -a || exit 0
          git push

Here, I configure GitHub Actions to set the name of the build, set the determinant of the pipeline (a cron schedule), set the cron schedule to run 06:00 AM daily (GitHub’s cron schedule runs with the UTC timezone), add some steps, install all the required dependencies, run the npm start command, generate the new README.md file, and push the changes using Git (if there are any changes in the file). If no changes exist, the process terminates, and no commit is pushed.

If you push the entire code to GitHub, the build will run automatically in GitHub Actions upon each push. But also, it will run on its own every day as scheduled. You can see the log of all builds in the "Actions" tab of the repository.

Also, kindly note that you might experience some delays with GitHub Actions for the first time. Initially, I chose 00:00 as my cron schedule, but it wasn't working. Research showed that sometimes it fails during peak hours, like the first hour of the day when usage is high. I switched to 06:00, which still failed, but started working fine the next day or so. In summary, GitHub Actions can be unpredictable for cron jobs, and you can use a dedicated infrastructure if you need a reliable execution at an exact time. But for this use case, it works just fine once it gets stable (nothing critical is going on here).

Custom GitHub Bot Account

If you observed, I used a custom user.email and user.name when setting up the GitHub actions push step. If you use a random email, it will push to GitHub with a non-existent account (no profile picture will be shown). My first thought was to use my actual GitHub account email that will push the changes as myself. But to make things much more neat, I created a new GitHub account that acts as a bot. This way, I can tell all the commits that were auto-generated from the script from mine.

To create the account, you can use your existing Gmail (if you don't have Gmail, use any email). Google allows you to create email aliases and receive emails from all in your inbox. All you must do is add a plus (+) sign after your email address and some custom text. Generally, I use this hack to create multiple email aliases for my Gmail so I can easily track specific emails based on context (e.g. if the email is bolaji@gmail.com, an alias can be bolaji+actionsbot@gmail.com). You're good to go once you create the account and set a nice name/profile picture. If you use this email to configure Git in the GitHub Actions, it will reflect accordingly.

PS: if you choose to do this with a Gmail alias, ensure to save the password somewhere because if you forget the password and need to log in (maybe to change the profile picture), you won't be able to use the "Forget password" feature with a Gmail alias email address. GitHub's form validation filters it out.

However, to solve this, manually change the "Backup email address" option to "Only allow primary email" in GitHub's dashboard (Settings > Emails).

Conclusion

That's about it! Now, you've learned how to automate scripts with CI/CD. If you're new to many of the concepts discussed in this tutorial, you should have learned some new things you can expand on. You can also extend the ideas here and customize the script to do anything you want it to. Just find a data source and do your thing.

I'm keen to see what you build with this, so please leave a comment with a link to your GitHub README Profile if you do something like this. Remember that this goes beyond markdown files; you can use the automated script idea to do anything else!

I'm happy with the results and I look forward to making more changes in the future as the need arises :). Thanks for reading this far; cheers!

A Little About Me

I’m a Software Engineer (focusing on JavaScript/Python web engineering, data analysis, and embedded systems—Raspberry Pi mainly), Content Creator, Teacher, and Developer Advocate with five (5) years of professional working experience. I’m very passionate about sharing knowledge, developer education, helping them become better at what they do, working with developers/customers, and helping dev-tool companies connect and sustain profitable relationships with their IDPs/ICPs. I’m mostly writing technical articles on my blog, running a bi-weekly newsletter, building open-source projects, organizing/speaking at meetups/conferences, and building technical communities. Being able to solve problems systematically and efficiently is my greatest strength. Using a hands-on technical approach paired with strong communication and management skills, I collaborate with people, establish and lead teams, professionally develop support, enhance operations, and manage information systems, communities, and solutions.

As a developer advocate, I've spent the last years working with outstanding teams, building great developer and API products. This developer relations career portfolio will show you why I would be a valuable addition to your company.

What I Can Offer

Here are a few reasons that make me a great addition to your team:

• I'm keen on doing my best in any responsibility assigned to me. It's a personal principle; I always strive to do my best on any given task using all that is available to me and iterate deliverables based on feedback.

• I enjoy teaching, learning new stuff, and sharing knowledge. This is the foundation of my developer relations/education strengths and my entire career.

• I can adapt to new conditions, company goals/visions, go-to-market strategy requirements, and the overall business needs of your developer product.

• I'm an honest person and don't tell lies. I won't tell developers that your product is the best in the world (unless proven), but I will take my time to understand the key strengths/benefits/limitations of your product and scream the benefits to developers at the top of my voice, show them how those benefits offer them value, help them get comfortable with building with your product, and build a trust relationship with them.

• I have solid experience working with and leading developer communities since my teenage years, with some notable ones being Meta Developer Circles (previously Facebook Developers Circles), GitHub Education Campus Expert, and Open Source Community Africa.

• I have a Bachelor's Degree in Computer Science. While this is usually not an essential determinant for most companies, it is valuable to me. I spent quite some years acquiring theoretical, practical, and research knowledge that impacts some of my current strengths and interests (especially around Human-Computer Interaction (HCI), Data Analysis, Machine Learning, Electronics, and Embedded Systems).

• Aside from my years of solid technical writing experience:

  • I have some experience with academic research writing and published my first paper on Performance and Accessibility Evaluation of University Websites in Nigeria in the 2022 5th Information Technology for Education and Development (ITED). I'm currently working on publishing my second research paper for my undergraduate dissertation.

  • I also actively contribute technical writing efforts to The Good Docs Project, where best practice templates and writing instructions for documenting OSS projects are created. I worked last on the Installation Guide Template alongside a partner in the Capilano and Dragon release, and I'm currently working on a new API Use Cases Template.

• I'm mostly humorous, and people enjoy working with me :).

My key strengths are:

• Writing code for things that work on the web using JavaScript, TypeScript, Reactjs, Nextjs, Python, Flask, and other frameworks.

• Writing code for things that work on embedded systems using Python, OpenCV, and other related libraries.

• API documentation.

• Technical content creation.

• Content production/marketing.

• Community/programs management.

• Data analysis and reporting.

• Developer events organization.

• Educational programs management.

• Educational curriculum development.

• Memes collection and efficient distribution :).

As the next member of your team, I will bring my software engineering and developer relations experience to:

• Build trust relationships with developers and customers using your product.

• Stand as a mediator between your product and developers using the products—helping them be successful with your product offerings.

• Talk to your prospective technical or non-technical customers in different engineering teams and help them understand the value of your product.

• Build tools, code demos, integrations, content, educational materials, and documentation to ensure developers can fully utilize your products.

• Work with strategic partners to show the power of your product when composed with other tools and services developers love (including both open-sourced and commercial) by building brilliant/creative integration ideas and templates.

• Educate developers on your product via open-source, public speaking/technical workshops at conferences or local developer meetups, documentation, and published tutorials/videos.

• Lead conversations around the latest technology advancements and best practices around and outside your product in the developer community at in-person events, online events, or social forums.

• Build, grow, and nurture a community of developers who use your product.

• Work closely and collaborate with your engineering, product, marketing, sales, customer success, and other existing internal teams to improve your product's developer experience.

• Test your new product features and give early feedback that will aid improvements.

• Gather feedback from the developer community on old/new product features for further planning, prioritization, and shipping.

• Track and measure the success and failure of the activities and responsibilities you assign to me, showing the business value of developer relations at your company.

DevRel Career Achievements

Here are some notable and publicly available samples of my DevRel, content creation, open-source work at my previous companies, non-profit educational commitments, and community engagements.

• All technical writing content: https://blog.bolajiayodeji.com.

• Archive of my weekly newsletter: https://bawd.bolajiayodeji.com.

• All public speaking slides: https://slides.com/bolajiayodeji.

• All writings on freeCodeCamp: https://freecodecamp.org/news/author/bolajiayodeji.

• All writings on opensource․com: https://opensource.com/users/bolajiayodeji.

Code and Integration Samples

• You can find all my code, documentation, and other contributions to personal and external OSS projects on GitHub.

• chat-with-siri — A text-to-speech audio chatbot built using Nextjs, OpenAI, and ElevenLabs. I worked on the code, documentation, and supporting tutorial to show how developers can leverage generative AI models to provide LLM audio chat solutions to consumers.

• commercelayer-sanity-template — A multi-country ecommerce template built using Commerce Layer API, JavaScript, TypeScript, Nextjs, and Sanity Studio. In my previous role, I worked on the code and documentation to show the strengths of Commerce Layer's API when composed with a headless CMS for managing both commerce and content data in an ecommerce store. I worked on the first version of the project alongside a colleague (Ale!) and began maintaining the project afterwards to ensure it was up-to-date. My recent contributions were:

  • Refactoring the components and UI logic, implementing the use of a single locale for product slugs, code cleaning, and migrating to the pnpm package manager in PR #74.

  • Upgrading to the latest Sanity version (v3) and Nextjs 13, fixing all breaking changes, updating the groq queries to use createClient in next-sanity, adding French translations for i18n, and introducing schemas type-checking with TypeScript in PR #67.

• nextjs-contentful-store — A multi-country ecommerce store built using Commerce Layer API, JavaScript, TypeScript, Nextjs, and Contentful. I worked on the first version of the project and documentation. I improved the initial sanity-template code here, introducing a new cart implementation using Commerce Layer's hosted-cart and other additions in PR #5.

• pay-with-tweet — A demo external payment gateway that enables customers to pay for an order by just making a tweet without any cash transaction built using Commerce Layer API, Twitter API, JavaScript, TypeScript, and Nodejs. I worked on the code, documentation, and supporting tutorial to show the strengths and flexibility of Commerce Layer's external payment gateway.

• commercelayer-slackbot — A Slackbot that responds with orders/returns summaries upon request and allows users to checkout pending orders directly from a Slack channel built using Commerce Layer API, JavaScript, TypeScript, Slack Boltjs library, and Supabase. I worked on the code, documentation, and supporting tutorial.

• sendgrid-templated-emails — A Nodejs script for sending templated order confirmation (or any type) emails to customers using Commerce Layer Webhooks, SendGrid API, and Zapier Code Runner. I worked on the code, documentation, and supporting tutorial.

• twilio-sms-notification — A Nodejs script for sending an SMS notification to customers when an SKU that had finished is back in stock using Commerce Layer Webhooks and Twilio SMS API. I worked on the code, documentation, and supporting tutorial.

Content and Documentation Samples

• A step-by-step manual configuration CLI reference guide.

• Commerce Layer Core Concepts.

• Commerce Layer Data Model.

• How to build a Commerce Layer Slackbot with Node.js and Slack API.

• Building an external payment gateway with the Twitter API.

• A comprehensive guide to Commerce Layer webhooks.

• How to send templated emails with Commerce Layer and SendGrid.

• She Inspires Series on Hashnode.

• Product overview video recording: Introducing Commerce Layer Postman Collection

Teaching/Workshops/Podcast/Public Speaking

• 👨🏾‍🏫 Deploying Machine Learning Models to the Web (workshop material).

• 👨🏾‍🏫 Building an Ecommerce Solution with Commerce Layer Demo Stores (workshop material).

• 👨🏾‍🏫 Anatomy of the Web and Version Control (workshop slides).

• 👨🏾‍🏫 Version Control with Git and GitHub (workshop slides | video).

• 🎤 Effective Documentation: The Key to Open Source Growth (slides | video).

• 🎤 What is Headless eCommerce? feat. Bolaji Ayodeji - Effective Product Development #0005 (video).

• 🎤 This Dot Media State of Web Performance 2/22/22 (video).

• 🎤 Building Composable Commerce on the Cloud for Emerging Markets (slides).

• 🎤 Headless Commerce done right, with Commerce Layer (slides | video).

• 🎙️ Sustain OSS Episode 131: Bolaji Ayodeji on Open Source Community Africa (podcast).

• 🎙️ Web Standards and Future Trends: Staying Ahead in the Evolving Web Landscape (podcast).

Courses and BootCamps

I organized a Software Engineering BootCamp at Thomas Adewumi University in 2022 for their university and high school students that introduced them to key areas of Software Engineering, such as Data Science, Machine Learning, and Full-stack Web Development. Aside from organizing and managing the entire BootCamp/Curriculum, I taught the Anatomy of the Web and Version Control class.

Although not publicly visible (only visible to registered students), I partnered with AltSchool Africa in the past to teach an Introduction to Open Source and Version Control with Git and GitHub course for their School of Engineering Class of 22” and 23". I have since received good feedback from students who took the course (most of which were verbal, but you can find some written ones below).

Extra Community and Open Source Contributions

I'm currently a core team member and the community manager for Open Source Community Africa, a community for open source lovers, enthusiasts, advocates and experts within and across Africa with the sole aim of increasing the rate of credible contributions by African software developers, designers, writers and everyone involved in the sphere of technology to open source projects both locally and globally. I manage the digital community on Discord of 4000+ members, co-organizing and facilitating virtual community events, managing communications via newsletters and blog posts, preparing fiscal year budgets, preparing community/event data visualization/reports, facilitating community partnerships with companies like GitHub, Google OSPO, SustainOSS, Propel, TalentQL, etc., supporting community members to participate in OSS programs like Hacktoberfest, GSOC, GSOD, Outreachy, etc., and running the Chapters program that spans 30+ chapters in three continents of Africa. Over the years, we have had commendable community growth and results of members contributing to OSS, creating OSS projects, and advancing their careers.

I have also been co-organizing the yearly Open Source Festival and Sustain Africa with other core team and committee members for three years now. The festival is a conference that attracts student delegates, developers, designers and corporate organizations on a large scale with a series of talks, workshops, and awareness of open-sourced developer tools (the biggest of its kind in Africa and Nigeria). Sustain, on the other hand, is a one-day conversation for open-source maintainers and contributors where we talk about Sustainability—the sustainability of resources and the sustainability of its people, the comprehensive overview of how FOSS is developed, maintained, utilized with the aim of providing a roadmap for solving the cultural, financial, and institutional issues among open-source project maintainers. You can read the 2023 community report to learn more.

Testimonials

Here's what a couple of my previous colleagues and industry leaders have to say about my work:

Contact Me

Please feel free to share any opportunity you find or referrals; I'd be happy to share my resume on demand. While I look forward to settling somewhere full-time, I'm open to doing short-term contract or consultation work for you or your company/project if your needs fit into any of my strengths. So, if you have anything for me, you can email me at mailtobolaji@gmail.com or DM me on LinkedIn or X (Twitter). Thank you 💙!

:).

Prerequisites

1. Some JavaScript, command-line, and API knowledge are required.
2. A working programming IDE (I use vscode; you can also try it).
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.

Introduction to Composable Commerce

Before we proceed, let’s understand what the concept “composable” means. Before now, ecommerce websites were built with a monolithic architecture where all components (frontend, backend, content, and commerce data) were coupled into one system. Over time, this approach posed different weaknesses related to speed, flexibility, scalability, security, modularity, etc. Most importantly, it became difficult for different sub-teams in an engineering team to effectively build in development and collaborate on the product—leading to a poor developer experience. All these weaknesses directly affect the sales and customer retention part of an ecommerce business, which shouldn’t be the case. Hence, there was the rise of a better approach that allows for an independent and agnostic setup for all teams (frontend, backend, content, etc.) and effective product development flow. This approach, called “composable commerce,” allowed for a better developer experience, more room for creativity and innovation from each team, more room for adapting to new market opportunities, and eventually, customer satisfaction, increased revenue, and customer retention.

Composable commerce allows developers to review, select, and utilize various available commerce solutions as required to satisfy specific business needs in the different sub-teams of the engineering team. Developers can compose their development stack by selecting best-of-breed tools from API-first solutions, headless solutions, composable microservices, or even microfrontends. If any of these terms are unfamiliar, you can do a quick Google search to learn more about them. Generally, a composable commerce solution includes:

• The front-end presentation layer decoupled from the backend logic.
• Individual components (autonomously developed, deployed, and managed) targeted toward specific business requirements.
• APIs connecting each of these individual components.
• Integration with reliable API-first external services.
• SAAS and cloud computing services.
• Real-time data shared between applications with webhooks.
• Possibilities to build an independent and agnostic internal application on top of the existing data and composable architecture.

The beauty of the composable commerce architecture is that you can distribute your ecommerce service anywhere your customer wants them (either on mobile, web, smart devices, CLIs, etc.) so long the envisaged sales channel allows API mechanisms. For brands and developers, the options are numerous; for example, you can go as easy as making a static HTML website shoppable using a dropin library to power certain transactional functionalities or building a fully functional ecommerce website with commerce platforms like Commerce Layer and dev tools like the Demo Store project (which we will do in this article!).

Getting Started

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— a composable commerce API for developers and brands that you can use to build an international ecommerce website to process millions of orders. All the amazing API resources, Nextjs, TypeScript, and other tools were used in building the Demo Store ecommerce project. You can explore 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 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 clientSecret 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:

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

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

git clone <your-repository-url> my-new-demo-store
cd my-new-demo-store
git submodule update --init
npm install

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

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

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

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

→ Create a .env.local file and add the following variables, including your previously created sales_channel application credentials (Client ID and Base endpoint):

SITE_URL=http://localhost:3000
NEXT_PUBLIC_CL_CLIENT_ID=coF7ofOKxTlbYfN...
NEXT_PUBLIC_CL_ENDPOINT=https://your-demo-store.commercelayer.io

NEXT_PUBLIC_JSON_DATA_FOLDER=../../../data/json/
NEXT_PUBLIC_LOCALES_DATA_FOLDER=../../../data/locales/
NEXT_PUBLIC_CONFIG_FOLDER=../../../config/

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:

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

npm install -g @commercelayer/cli

or

yarn global add @commercelayer/cli

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

cl plugins:install seeder
cl plugins:install imports

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

cl applications:login \
  --clientId Oy5F2TbPYhOZsxy1tQd9ZVZ... \
  --clientSecret 1ZHNJUgn_1lh1mel06gGDqa... \
  --organization your-demo-store \
  --alias cli-admin

→ 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.):

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

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

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

→ 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).

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

npm run dev

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 that everything is correct by running the command:

npm run test:data

You can look at the finished code to see all the extra pages and translation changes added to the demo conference swag ecommerce website. Alternatively, if you need to fully customize your store (behavior, UI, UX, etc.), then all you have to do is fork the demo-store-core repository, which contains the source code, follow the instructions to set things up locally and configure it as earlier discussed.

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)

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

NEXT_PUBLIC_DATA_FETCHING=ssg

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

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

Server-side rendering (SSR)

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

NEXT_PUBLIC_DATA_FETCHING=ssr

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

→ 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:

[build]
  command="npm run export"
  publish="demo-store-core/packages/website/out"

[build.processing]
  skip_processing = true

[build.environment]
  NEXT_PUBLIC_JSON_DATA_FOLDER="../../../data/json/"
  NEXT_PUBLIC_LOCALES_DATA_FOLDER="../../../data/locales/"
  NEXT_PUBLIC_CONFIG_FOLDER="../../../config/"

[template.environment]
  SITE_URL="https://your-demo-store.netlify.app"
  NEXT_PUBLIC_CL_CLIENT_ID="coF7ofOKxTlbYfNNe..."
  NEXT_PUBLIC_CL_ENDPOINT="https://your-demo-store.commercelayer.io"

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

{
  "version": 2,
  "buildCommand": "npm run build",
  "outputDirectory": "demo-store-core/packages/website/.next",
  "build": {
    "env": {
      "ENABLE_EXPERIMENTAL_COREPACK": "1",
      "NEXT_PUBLIC_DATA_FETCHING": "ssr",
      "NEXT_PUBLIC_JSON_DATA_FOLDER": "../../../data/json/",
      "NEXT_PUBLIC_LOCALES_DATA_FOLDER": "../../../data/locales/",
      "NEXT_PUBLIC_CONFIG_FOLDER": "../../../config/",
      "SITE_URL": "https://conf-swag-demo-store.vercel.app",
      "NEXT_PUBLIC_CL_CLIENT_ID": "coF7ofOKxTlbYfNNe...",
      "NEXT_PUBLIC_CL_ENDPOINT": "https://your-demo-store.commercelayer.io"
    }
  }
}

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. I added mine 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 the Commerce Layer free Developer plan) 😃.

I’d also love to see what you build with this, so please feel free to share what you’ve built and let me know what you think about the tutorial in the comment section or in Commerce Layer's Slack community!

GitHub recently introduced a new feature that allows you to create default files like CONTRIBUTING.md, CODE_OF_CONDUCT.md, or even ISSUES templates in a public organization. These default files will be used for any repository owned by the organization that does not contain its file of that type. So if you have open-sourced projects in your company, project, or personal GitHub organization, then this is for you!

All you have to do is create a .github repository and put all the files and templates in it (here's a perfect example). Then, you can find all the supported files here in the GitHub docs. I've also attached a screenshot below to save you some time (but feel free to click the link above to learn more about how to set up health files properly on GitHub). Cheers! 💙

Let's roll!

Prerequisites

• Basic programming knowledge

• A working laptop running on any operating system

• An IDE and required tools for programming

• A smile on your face :)

What Exactly is Open Source?

According to Wikipedia, Open Source (also known as OSS) is: “The source code of a software application that is released under a license in which the copyright holder grants users the rights to use, study, change, and distribute the software and its source code to anyone and for any purpose.”

Basically, this is a public code base on the internet that is developed either collaboratively by multiple people or by one person. OSS allows users to adapt software to their personal needs and publish any modification for users with similar needs either on the original project or as another project.

Why Open Source?

OSS is about collaborating with people from different regions, cultures, and technical backgrounds working remotely. This is why it is an essential practice for anyone working in tech to enable them to learn and build the collaboration skills needed to work effectively with software teams on software products.

Some benefits of contributing to open-source projects include:

• Opportunity to build technical work experience.

• Opportunity to gain experience with collaborating with people.

• Opportunity to build communication and soft skills.

• Opportunity to gain domain-specific industry knowledge.

• Possibility to earn money or certain financial rewards.

• Access to mentorship and network opportunities.

• Ultimately, career growth.

Fields in Open Source

Here are several ways you can contribute to open-source with your existing skills:

1. Software Engineering

• Writing code

• Writing tests for code

• Reviewing code

• Fixing bugs

• Beta testing

• QA testing

2. Data Engineering

• Writing code

• Data collection and cleaning

• Data analysis

• Data visualization

• Research

3. Content Writing

• Writing documentation

• Writing tutorials

• Writing translations

• Writing newsletters

• Creating or editing content

4. Design

• Designing designs 🥹

• UX surveys and research

• Creating styles guides

• Producing brand materials

5. Marketing

• Promoting projects

• Engaging users on the internet

• Converting new users through certain means

• Developing marketing strategies

• Running Producthunt launches

6. Project Management

• Managing the development phases of the project

• Managing the allocation of resources and funds

• Tasks and issues organization

• Tooling and automation

7. Community Management

• Managing people and contributors

• Organizing events

• Organizing programs

• Enforcing the code of conduct

8. Reporting bugs

9. Research

10. Idea suggestions

11. Funding

12. Et. Cetera

Getting Started with Open Source

The first thing you need to do is to understand what your skills and strength are. The fields in the OSS section should have given you ideas of certain things you can do. This is very important because it gives you the right perception and confidence about who you are and what you can do. Then you can use this knowledge to search for projects matching your skills. For example, Ruth has some intermediate experience with the JavaScript programing language, advanced understanding of the Python programing language, some technical writing experience, and can write some unit tests. With this, Ruth can contribute code to some JavaScript and Python projects based on the complexities of the tasks (offering her an opportunity to gain more experience) and can contribute to writing documentation for any project.

Next, you can decide to find some projects that you're interested in (this is optional but something you can consider and use as a guide to finding projects). For example, you might be interested in general developer toolings for a specific language, projects related to e-commerce, climate change, education, UI components, web performance, etc.

Once you have completed the first and second phases, it's time to find projects. Here are some places:

• GitHub Showcase: A collection of projects with a history and reputation for being welcoming to new open source contributors.

• GitHub Explore: a recommendation of projects on GitHub based on your interests.

• GitHub Topics: a collection of projects on GitHub categorized based on popular topics.

• Good First Issues: a collection of open issues on GitHub with the ability to filter by programming language, issue label, or repository.

• Pull Request Roulette: a list of pull requests submitted for review belonging to open-source projects hosted on Github.

• Ovio Projects: a curated list of projects and issues with the ability to filter by programming language, topic, and activity.

• Code Triage: a collection of different GitHub repositories to pick from, and you receive a different open issue in your inbox every day.

• Up For Grabs: a curated list of projects which have curated tasks specifically for new contributors.

• 24 Pull Requests: a program that allows you to find open-source projects to contribute to and gift them your contribution as a Christmas gift.

...and lots more. With these, I believe you can begin finding projects to contribute to.

I'd recommend you check out the Open Sauced tool created by @bdougie. With this, you can find projects and manage your OSS contributors on a dashboard with project intelligence, community insights, and contributor analytics (this is very useful for maintainers too). You should also join the Open Source Community Africa to network and collaborate with over 3,200+ contributors and creators across Africa.

Git and GitHub

Before we proceed to the main stuff, you will need some knowledge of version control to contribute to open-source. For some kinds of contributions, you might not need this, but it won't hurt to learn it once and for all. Version control is the process of tracking and managing changes to software code or a set of files over time. Git is the most widely used modern version control system in the world today. It's A distributed and actively maintained open source project initially developed in 2005 by Linus Torvalds (the famous creator of the Linux kernel). GitHub, on the other hand, is a web-based hosting service for version control using Git that is mostly used for software code (there's also GitLab or Bitbucket if you prefer those, but most OSS projects are hosted on GitHub). If you want to learn everything about Git from start to finish, then take this course, read the docs, or read the Pro Git book. If you're a student at AltSchool Africa's School of Engineering, you should have access to the Introduction to Open Source course I taught, which covers most of the foundational concepts of Git and all.

Anyways, download Git for your most preferred operating system here, configure it like so:

git config --global user.name "Bolaji Ayodeji"
git config --global user.email <your_email>@gmail.com
git config --global init.defaultBranch main

Now you can use Git to manage your code locally for your projects as a practice (if you don't know how to use it already). It's nothing too serious; these are the basic commands you will often use while contributing to OSS projects:

git clone <url>
git add <filename> or git add * or git add . or git add --all
git status
git commit -m "commit description"
git commit --amend
git push origin <branch name>
git push <remote> <localBranch:<remoteBranch>
git push origin main or git push origin --set-upstream <branch name>
git log
git pull
git branch -a
git branch staging
git checkout -b <branch name>
git checkout main

You can always run the git help command to learn more or git help <command name> to learn about a particular command, e.g., git help branch. As a bonus; if you’re a student (at any level), you can apply to get the GitHub Student Developer Pack and access the best developer tools and courses for FREE.

The Anatomy of an Open Source Project

Generally, open source projects are built on four main components, the Source code, a Licence, Documentation, and People. These sets of people can further be broken into more parts:

• Creator(s): Those who created the project.

• Maintainer(s): Those who actively manage the entire project.

• Contributor(s): Those who contribute to the project (someone like you).

• Users: Those who use the project (developers or customers).

• Working group(s): A collection of contributors split into domain-specific groups to focus on a discussion or activity around a specific subject area (e.g., testing group, DevOps group, documentation group, code reviews group, performance group, etc.).

• Sponsor(s): Those who contribute to the project with financial support.

OSS projects usually include the following files (usually in text or markdown format) and documents:

• License: the legal document that explains how and to what extent the project can be freely used, modified, and shared (example).

• Code of conduct: the document that outlines the rules, norms, acceptable practices, and responsibilities of anyone who decides to participate in the project in any way—including what happens when someone violates any of the rules (example).

• README: the markdown file that displays under any repository on GitHub. This is usually the entry point to any project, so you might find the documentation here and links to other necessary documents. (example).

• Documentation: the file that contains all documentation resources for the project, including guides, API references, tutorials, data models, etc. (example).

• Contributing docs: the document that explains how to get started with contributing to the project, including installation guides, configuration, etc. (example).

• Security: the file that explains how to submit vulnerability reports or any security issue (example).

• Issues: the board with a collection of tasks and bug reports awaiting someone like you to fix them (example).

• Pull requests: the board with a collection of solutions submitted to fix certain issue(s) (example).

• Discussions: the place where maintainers, contributors, and users discuss on GitHub. Usually, you'd report bugs here or ask the community for help when you encounter an issue with the project (example).

And that's pretty much it. Most projects will also have a communication channel on maybe Discord or Slack for conversations and interactions between community members.

The Phases of Contributing to Open Source

Now you have some background knowledge, know how to use Git, have a GitHub account, and you have found some projects you would like to delve into. Here's what to do next in the exact order:

1. Indicate interest under the issue you want to work on or send a message in the project chat communication channel to declare you want to work on XYZ. It's wise to do this to ensure someone else isn't working on the issue. If you don't get feedback quickly (different projects have different response rates depending on the number of requests), you can begin working on your solution slowly but try not to do anything serious till you get approval, or the issue is assigned to you.

2. Request for assignment to an issue.

3. Open an issue and clearly explain what you want to contribute, your thought process, and how you intend to build your solution. Try to wait for some feedback here in order to validate your idea against the requirements of preferences of the project owner (remember it isn't your project, the same way the company you work at isn't yours, so you can't make business decisions for them but can only suggest project features and all).

4. Read the documentation and contributing guidelines.

5. Fork the repository to your GitHub account.

6. Clone the forked repository to your local computer.

7. Set up locally following the contributing guidelines.

8. Create a new branch locally.

9. Work on your changes locally, versioning along the way.

10. Test your changes locally.

11. Push your branch and changes to your fork on your GitHub account.

12. Submit a pull request to the original repository and await feedback.

13. Review feedback, process the feedback, respond kindly, and make necessary changes.

14. Done! ✅

Conclusion

We've come to the end of this guide, and I hope you find it helpful. This is a pocket guide you can keep close whenever you intend to contribute to a project, and you've forgotten something. If you're new to open-source, this can also be a good starting guide. Likewise, frequent contributors can use this guide to refresh their knowledge or fill up missing parts. In summary, this guide is for everyone, and I hope it helps you become a better open-source contributor. Cheers! 💙

Useful Resources

• Git Cheat Sheets (in different languages)

• Open Source Guides

• A collection of recommended OSS resources, tools, and communities

• Software to make running OSS projects a little bit easier

In this tutorial, I will introduce model deployment by showing you the basic steps and processes of deploying a model on a web application built with Python and Flask. Then, I'll share an already-built model and show you how you can export yours (if you have any). We will build the app, integrate the model, and deploy it to Heroku with Git and GitHub. I'd also share some alternative tools and frameworks to consider based on your use case.

Sounds like something you want to learn? Then read on :)

Prerequisites

• A working computer running on any operating system.
• Some HTML, CSS, JavaScript, and Python knowledge.
• Basic knowledge of navigating around the command-line.
• A smile on your face :)

What's a Machine Learning Model?

A machine learning model is a file that has been trained using specific data to recognize certain types of similar patterns and make informed predictions. You provide a model with a set of data and train it with some algorithms. When you introduce a new set of data, the model will use learned knowledge to recognize the new data set. This is typically what happens with Face recognition security systems, where the device recognizes your face as a human face, not an object. Another example is a recommendation system, like in the demo I built for this tutorial. You will provide the model with multiple words associated with an output class (either positive or negative). The model will then learn from them so that when you provide a new sentence, the model can determine if it is positive or negative.

There are three paradigms used to develop models, namely:

• Supervised Learning (this is a type of ML where an algorithm is given a large input dataset with corresponding output or event/class, usually prepared in consultation with the subject matter domain expert).
• Unsupervised Learning (this is a type of ML where an algorithm is given some input dataset without the desired output or event/class and subject matter domain expert consultation).
• Reinforcement Learning (this is a type of ML algorithm that maps situations to actions that result in the highest possible reward).

You can learn more by clicking on the links of each category.

Building a Machine Learning Model with Python

You can build machine learning models with Python and other frameworks. To get started, I recommend you take this Machine Learning crash course from Google that will teach you the fundamental machine learning concepts with a series of video lectures, real-world case studies, and hands-on practice exercises.

Serializing a Machine Learning Model

Serialization is the process of converting an object to a stream of bytes which is then stored or transmitted to memory or a file. You can learn more in this Wikipedia article.

Now I'll assume you have learned how to build stuff with Machine Learning, or you have already created some model(s) that you would like to integrate with a user interface and deploy to the web. The first step you need to do is to export and save your model in a file format so you can use it while integrating with other technologies. Doing this will serialize your machine learning algorithms and save the serialized format to a file you can de-serialize later. There are several ways to do this based on the algorithms/frameworks used in developing your model or the requirements of your model. Some tools or file formats you can use include Pickle (Pkl format), Joblib (Pkl or Joblib format), Tensorflow Keras (H5 or JSON format), etc.

Building the Web Application with Flask

I built a basic machine learning model to predict whether a movie review is positive or negative. I used four classification models (Support Vector Machine, Decision Tree, Naive Bayes, and Logistic Regression) and then evaluated each of them to find the one with the best accuracy. I then optimized the model with GridSearchCV and serialized it to a .pkl file using Pickle like so:

import pickle

filename = 'movie_reviews_sentiment_analysis.pkl'

# Save model (serialize)
pickle.dump(svc_grid, open(filename, 'wb'))

# Load model (de-serialize)
pickle.load(open(filename, 'rb'))

You can view the notebook for the machine model here:

Now that we have a working model, let's build a basic web application using Flask, HTML, CSS, and some JavaScript in the following sections.

Project Folder Directory Setup

Create a new directory on your computer and create the following subfolders, files, and subfiles. If you want to use the same model and files I used, you can fetch everything from this repository on GitHub.

├── data
  ├── dataset.csv (the dataset for your model)
  ├── <any other required data files>
├── webapp
  ├── model
     ├── movie_reviews_sentiment_analysis.pkl
     ├── vectorizer.pkl
  ├── static
     ├── main.css
     ├── main.js
  ├── templates
     ├── main.html
  ├── app.py
├── <your model notebook>.ipynb

Flask Installation and Setup

Flask is a lightweight Python micro framework for building web applications (if you want to learn more about Flask, you can check this out). To get started, we will install Python, Flask, and Pickle using PIP if you haven't already, like so:

pip install python3

pip install flask

pip install pickle

Create the Required Flask Templates

Add the following markup code with some Tailwind styling to the main.html file in webapp/templates to create a form with a <select> field, a <textarea> field, and a submit button:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Movie Reviews Sentiment Analysis</title>
    <link
      href="https://unpkg.com/tailwindcss@^2/dist/tailwind.min.css"
      rel="stylesheet"
    />
    <link rel="stylesheet" href="{{ url_for('static',filename='main.css') }}" />
  </head>

  <body class="font-mono">
    <div class="flex items-center justify-center h-screen">
      <div class="p-12 max-w-lg bg-white rounded-lg overflow-hidden shadow-lg">
        <div class="font-bold text-xl mb-2">
          Movie Reviews Sentiment Analysis
        </div>
        <hr />
        <br />

        <form id="review-form" action="{{ url_for('main') }}" method="POST">
          <label class="block text-gray-700 text-sm font-bold mb-2" for="movie">
            Select a movie:
          </label>
          <select
            id="movie"
            name="movie"
            class="block appearance-none w-full bg-white border border-gray-400 hover:border-gray-500 px-4 py-2 pr-8 rounded shadow leading-tight focus:outline-none focus:shadow-outline"
            required
          >
            <option></option>
            <option value="The Good Doctor">The Good Doctor</option>
            <option value="Money Heist">Money Heist</option>
            <option value="Blacklist">Blacklist</option>
            <option value="The Return of Kibi">The Return of Kibi</option>
            <option value="The Imitation Game">The Imitation Game</option>
            <option value="The Dark Knight">The Dark Knight</option>
            <option value="Blindspot">Blindspot</option>
            <option value="Ozark">Ozark</option>
            <option value="Vincenzo">Vincenzo</option>
          </select>

          <br />

          <label
            class="block text-gray-700 text-sm font-bold mb-2"
            for="review"
          >
            Enter your review:
          </label>
          <textarea
            name="review"
            id="review"
            class="shadow appearance-none border rounded w-full py-2  px-3 text-gray-700 leading-tight focus:outline-none focus:shadow-outline"
            rows="5"
            required
          ></textarea>

          <br />

          <input
            type="submit"
            value="Submit"
            class="w-full bg-blue-500 text-white font-bold mt-8 p-4 rounded focus:outline-none focus:shadow-outline"
          />
        </form>

        <div class="result mt-12" align="center">
          <span id="predict_text">{{ predict_text }}</span>
          <span id="selected_movie" class="text-gray-700">{{ movie }}</span>
          <p class="text-blue-700 text-lg font-bold border rounded mt-4">
            {{ result }}
          </p>
        </div>
      </div>
    </div>

    <script
      src="{{ url_for('static',filename='main.js') }}"
      type="text/javascript"
    ></script>
  </body>
</html>

Each input element has an ID with the name of the feature required by the model. The form has a POST method set, and upon successful form submission, the data is sent to main.py file for processing. The last section displays the results from the processing done in main.py. The variables in {{ }} represents the dynamic data to be expected upon successful form submission.

For some extra fancy background, add the following code to the main.css file in webapp/static:

body {
  background-color: #4267b2;
  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='192' height='192' viewBox='0 0 192 192'%3E%3Cpath fill='%239C92AC' fill-opacity='0.4' d='M192 15v2a11 11 0 0 0-11 11c0 1.94 1.16 4.75 2.53 6.11l2.36 2.36a6.93 6.93 0 0 1 1.22 7.56l-.43.84a8.08 8.08 0 0 1-6.66 4.13H145v35.02a6.1 6.1 0 0 0 3.03 4.87l.84.43c1.58.79 4 .4 5.24-.85l2.36-2.36a12.04 12.04 0 0 1 7.51-3.11 13 13 0 1 1 .02 26 12 12 0 0 1-7.53-3.11l-2.36-2.36a4.93 4.93 0 0 0-5.24-.85l-.84.43a6.1 6.1 0 0 0-3.03 4.87V143h35.02a8.08 8.08 0 0 1 6.66 4.13l.43.84a6.91 6.91 0 0 1-1.22 7.56l-2.36 2.36A10.06 10.06 0 0 0 181 164a11 11 0 0 0 11 11v2a13 13 0 0 1-13-13 12 12 0 0 1 3.11-7.53l2.36-2.36a4.93 4.93 0 0 0 .85-5.24l-.43-.84a6.1 6.1 0 0 0-4.87-3.03H145v35.02a8.08 8.08 0 0 1-4.13 6.66l-.84.43a6.91 6.91 0 0 1-7.56-1.22l-2.36-2.36A10.06 10.06 0 0 0 124 181a11 11 0 0 0-11 11h-2a13 13 0 0 1 13-13c2.47 0 5.79 1.37 7.53 3.11l2.36 2.36a4.94 4.94 0 0 0 5.24.85l.84-.43a6.1 6.1 0 0 0 3.03-4.87V145h-35.02a8.08 8.08 0 0 1-6.66-4.13l-.43-.84a6.91 6.91 0 0 1 1.22-7.56l2.36-2.36A10.06 10.06 0 0 0 107 124a11 11 0 0 0-22 0c0 1.94 1.16 4.75 2.53 6.11l2.36 2.36a6.93 6.93 0 0 1 1.22 7.56l-.43.84a8.08 8.08 0 0 1-6.66 4.13H49v35.02a6.1 6.1 0 0 0 3.03 4.87l.84.43c1.58.79 4 .4 5.24-.85l2.36-2.36a12.04 12.04 0 0 1 7.51-3.11A13 13 0 0 1 81 192h-2a11 11 0 0 0-11-11c-1.94 0-4.75 1.16-6.11 2.53l-2.36 2.36a6.93 6.93 0 0 1-7.56 1.22l-.84-.43a8.08 8.08 0 0 1-4.13-6.66V145H11.98a6.1 6.1 0 0 0-4.87 3.03l-.43.84c-.79 1.58-.4 4 .85 5.24l2.36 2.36a12.04 12.04 0 0 1 3.11 7.51A13 13 0 0 1 0 177v-2a11 11 0 0 0 11-11c0-1.94-1.16-4.75-2.53-6.11l-2.36-2.36a6.93 6.93 0 0 1-1.22-7.56l.43-.84a8.08 8.08 0 0 1 6.66-4.13H47v-35.02a6.1 6.1 0 0 0-3.03-4.87l-.84-.43c-1.59-.8-4-.4-5.24.85l-2.36 2.36A12 12 0 0 1 28 109a13 13 0 1 1 0-26c2.47 0 5.79 1.37 7.53 3.11l2.36 2.36a4.94 4.94 0 0 0 5.24.85l.84-.43A6.1 6.1 0 0 0 47 84.02V49H11.98a8.08 8.08 0 0 1-6.66-4.13l-.43-.84a6.91 6.91 0 0 1 1.22-7.56l2.36-2.36A10.06 10.06 0 0 0 11 28 11 11 0 0 0 0 17v-2a13 13 0 0 1 13 13c0 2.47-1.37 5.79-3.11 7.53l-2.36 2.36a4.94 4.94 0 0 0-.85 5.24l.43.84A6.1 6.1 0 0 0 11.98 47H47V11.98a8.08 8.08 0 0 1 4.13-6.66l.84-.43a6.91 6.91 0 0 1 7.56 1.22l2.36 2.36A10.06 10.06 0 0 0 68 11 11 11 0 0 0 79 0h2a13 13 0 0 1-13 13 12 12 0 0 1-7.53-3.11l-2.36-2.36a4.93 4.93 0 0 0-5.24-.85l-.84.43A6.1 6.1 0 0 0 49 11.98V47h35.02a8.08 8.08 0 0 1 6.66 4.13l.43.84a6.91 6.91 0 0 1-1.22 7.56l-2.36 2.36A10.06 10.06 0 0 0 85 68a11 11 0 0 0 22 0c0-1.94-1.16-4.75-2.53-6.11l-2.36-2.36a6.93 6.93 0 0 1-1.22-7.56l.43-.84a8.08 8.08 0 0 1 6.66-4.13H143V11.98a6.1 6.1 0 0 0-3.03-4.87l-.84-.43c-1.59-.8-4-.4-5.24.85l-2.36 2.36A12 12 0 0 1 124 13a13 13 0 0 1-13-13h2a11 11 0 0 0 11 11c1.94 0 4.75-1.16 6.11-2.53l2.36-2.36a6.93 6.93 0 0 1 7.56-1.22l.84.43a8.08 8.08 0 0 1 4.13 6.66V47h35.02a6.1 6.1 0 0 0 4.87-3.03l.43-.84c.8-1.59.4-4-.85-5.24l-2.36-2.36A12 12 0 0 1 179 28a13 13 0 0 1 13-13zM84.02 143a6.1 6.1 0 0 0 4.87-3.03l.43-.84c.8-1.59.4-4-.85-5.24l-2.36-2.36A12 12 0 0 1 83 124a13 13 0 1 1 26 0c0 2.47-1.37 5.79-3.11 7.53l-2.36 2.36a4.94 4.94 0 0 0-.85 5.24l.43.84a6.1 6.1 0 0 0 4.87 3.03H143v-35.02a8.08 8.08 0 0 1 4.13-6.66l.84-.43a6.91 6.91 0 0 1 7.56 1.22l2.36 2.36A10.06 10.06 0 0 0 164 107a11 11 0 0 0 0-22c-1.94 0-4.75 1.16-6.11 2.53l-2.36 2.36a6.93 6.93 0 0 1-7.56 1.22l-.84-.43a8.08 8.08 0 0 1-4.13-6.66V49h-35.02a6.1 6.1 0 0 0-4.87 3.03l-.43.84c-.79 1.58-.4 4 .85 5.24l2.36 2.36a12.04 12.04 0 0 1 3.11 7.51A13 13 0 1 1 83 68a12 12 0 0 1 3.11-7.53l2.36-2.36a4.93 4.93 0 0 0 .85-5.24l-.43-.84A6.1 6.1 0 0 0 84.02 49H49v35.02a8.08 8.08 0 0 1-4.13 6.66l-.84.43a6.91 6.91 0 0 1-7.56-1.22l-2.36-2.36A10.06 10.06 0 0 0 28 85a11 11 0 0 0 0 22c1.94 0 4.75-1.16 6.11-2.53l2.36-2.36a6.93 6.93 0 0 1 7.56-1.22l.84.43a8.08 8.08 0 0 1 4.13 6.66V143h35.02z'%3E%3C/path%3E%3C/svg%3E");
}

Now, add the code below to the main.js file in webapp/static. This will prevent the form from storing state from the previous form sessions:

if (window.history.replaceState) {
  window.history.replaceState(null, null, window.location.href);
}

Now you can use the command flask run to start the Flask server on http://127.0.0.1:5000 to preview the UI you have developed so far (PS: ensure you run the command inside the webapp directory).

Model Integration with Python and Flask

In the main.py file located in webapp, add the following Python code:

import flask
import pickle
import pandas as pd

# Use pickle to load in the pre-trained model.
with open(f'model/movie_reviews_sentiment_analysis.pkl', 'rb') as f:
    model = pickle.load(f)

# Use pickle to load in vectorizer.
with open(f'model/vectorizer.pkl', 'rb') as f:
    vectorizer = pickle.load(f)

app = flask.Flask(__name__, template_folder='templates')

@app.route('/', methods=['GET', 'POST'])
def main():
    if flask.request.method == 'GET':
        return(flask.render_template('main.html'))

    if flask.request.method == 'POST':
        review = flask.request.form['review']
        predict_text = "Prediction sentiment for movie: "
        movie = flask.request.form.get("movie")
        prediction = model.predict(vectorizer.transform([review]))
        return(flask.render_template('main.html', predict_text=predict_text, movie=movie, result=prediction))

if __name__ == '__main__':
    app.run()

This code will import the pre-trained model and create a new route with the desired request methods (GET and POST). Then, inside the main() function, we will write the functionality for both requests, make predictions based on the input variables and return the result values to the / route (homepage). With this, our previously developed model can now take in new data from the input fields and return output data.

Deploying to the Cloud

Now, the most crucial part of this tutorial. How do we make the web application we have built accessible to anyone on the web? Well, we deploy it to the web using cloud services. For example, you can deploy to Heroku by following the steps below:

1. Set up Git in your working directory and push your code to a hosting service like GitHub.

2. Download and install the Heroku CLI using the command:

brew tap heroku/brew && brew install heroku

//or

curl https://cli-assets.heroku.com/install.sh | sh

You can download for Windows or use other methods by reading the official docs.

3. If you haven't already, log in to your Heroku account and follow the prompts to create a new SSH public key using the command:

heroku login

4. Create a Procfile and add the following:

web: gunicorn app:app

5. Create a requirements.txt file in the webapp directory and add the following:

flask==2.0.1
pandas==1.2.4
sklearn==0.0
gunicorn==20.1.0

6. Deploy your application to Heroku with Git using the commands below:

git add .
git commit -m "deploy to heroku"
git push heroku main

And that's pretty much it! You can explore the demo using this link. As you may already know, Heroku is shutting down free dynos soon, which means you'd have to pay some $$ to deploy to Heroku. If you want, you can consider alternatives, like Clouddley, Railway, Fly, Deta Cloud, Firebase, etc. All the alternatives have similar deployment steps using their CLIs; for example, you can get up and running with Fly with a few commands.

Conclusion

You can build a web application for your machine learning model using any web framework of your choosing, depending on the technology your model is built with. For Python, you can also consider other frameworks like Django, or if you're building with Tensorflow—a library that lets you create, train, and use trained machine learning models in Javascript, you can use frameworks like Reactjs (web) or React Native (mobile) to deploy your stuff to your end users.

If you want to stick with Python completely, you can also build a REST API using Fast API and consume that in your JavaScript, Reactjs, Vuejs, etc. application (like we just did). @Youngestdev wrote the perfect book for you on how to build Python Web APIs with FastAPI; you should get a copy and read it :winks:. Another exciting alternative is Gradio—the fastest way to demo your machine learning model with a friendly web interface so anyone can use it anywhere. @abdulsamodazeez wrote an insightful piece around how to deploy to Gradio; you should read it.

And that should be all! I hope you've learned something new or found a link to another resource that can help you become a better Machine Learning Engineer. You should use this tutorial as a guide to building a web app for your use case, so be sure to explore the code anytime and rewrite it to suit your needs using your HTML, CSS, JavaScript, and Python knowledge. If you have any further questions, feel free to leave them in the comments, and I'll respond as soon as possible. Cheers! 💙

Prerequisites

• You already know how to use Google Analytics.
• You've built or you're building a project with Nextjs.
• You already know some JavaScript and Reactjs.

Step One

Read this guide from Google's documentation to create a new GA4 property and data stream. Once successfully, you should have a generated MEASUREMENT ID that looks like: G-YQR79670LO. In the next steps, you will use this to configure your Nextjs web progress to track user interactions on your website and send streams of data back to Google Analytics.

Step Two

Create a .env file and add the MEASUREMENT ID as an environment variable like so:

NEXT_PUBLIC_MEASUREMENT_ID="<add_your_measurement_id_here>"

Step Three

Open your _app.js or _app.ts or _app.tsx file in /pages, import the variable created earlier, and Next Script component (Nextjs's extension of the HTML <script> element) like so:

import Script from "next/script";
const GA_MEASUREMENT_ID = process.env.NEXT_PUBLIC_MEASUREMENT_ID;

Step Four

Now add the code below after your <Head> component.

<Script
  src={`https://www.googletagmanager.com/gtag/js?id=${GA_MEASUREMENT_ID}`}
  strategy="afterInteractive"
/>
<Script id="google-analytics" strategy="afterInteractive">
  {`
    window.dataLayer = window.dataLayer || [];
    function gtag(){window.dataLayer.push(arguments);}
    gtag('js', new Date());
    gtag('config', '${GA_MEASUREMENT_ID}');
  `}
</Script>

The afterInteractive strategy on the Script component loads the script immediately after the page becomes interactive. Now you can deploy your changes to your desired host (maybe Netlify, Vercel, or Cloudfare Pages). Although, before deploying, ensure to add the environment variable (NEXT_PUBLIC_MEASUREMENT_ID) you created earlier in your deployment service. Most hosting services provide this option, so you can easily add variables via their dashboard. Once done, you should be good to go. It might take hours to reflect on your GA dashboard completely, but you should be getting hits already.

To confirm if you did everything right when you deployed your website, inspect the website's elements and you should see the script tags below at the bottom of the served HTML page.

Conclusion

I hope you learned something and you found this article useful. Tracking user activities on your website is a great way to learn more about your users and how to serve them better or serve those you're not serving yet. In all, it's essential for all kinds of projects on the web. Cheers! 💙

In this tutorial, you will learn how we built the Commerce Layer Starter with Nextjs, Sanity studio, and deployed it to Netlify. At the end of the tutorial, you should be able to set up and build your own 1-click sanity starter with ease or integrate with Commerce Layer.

Prerequisites

• Git installed (Learn how to install Git here if you haven't already).
• Node and NPM installed (Learn how to install Nodejs here if you haven't already).
• Basic knowledge of how to use the terminal.
• Basic knowledge of NPM.
• A grin on your face 😉.

Introduction to Commerce Layer

Commerce Layer is a transactional commerce API and order management for international brands. It lets you make any digital experience shoppable, anywhere. You can build a multi-language website with Shopify, Contentful, WordPress, or any other CMS you already love. Then, add Commerce Layer for multi-currency prices, distributed inventory, localized payment gateways, promotions, orders, subscriptions, and more.

Unlike traditional solutions, Commerce Layer was built for the new era. It natively supports the most modern development workflows, such as the Jamstack. Ecommerce businesses can integrate Commerce Layer with a single backend and serve on multiple presentation layers enabling them to build outstanding shopping experiences, go headless, and scale their business globally. You can check out our developer resources to learn more and get started.

Introducing Sanity Studio

The Sanity studio is an open-source content management system built with React.js. It offers rapid configuration, free form customization, reusable structured content, a comfortable editor, real-time collaboration, toolkits, plugins, and more features to enable you to create the best content workflow.

Sanity provides the possibility to create starter templates that can be re-used by developers easily. The starter is primarily a repository hosted on GitHub that contains some meta-information, demo content, schema, and frontend(s) that will end up in a new repository when a developer installs the starter through sanity.io/starters. When a developer installs the starter, Sanity creates a new project on Sanity and a new repository on GitHub with the starter code, attaches a new Sanity datasetId to the starter, and deploys the project to Netlify simultaneously.

Generally, a sanity starter can include a Sanity studio, a frontend application, both or multiple frontends and studios. For the purpose of this tutorial, we will create a starter that will include a studio and frontend. Our starter will include:

• An ecommerce storefront built with Nextjs and Commerce Layer react components library.
• International shopping capabilities powered by Commerce Layer APIs.
• Some ecommerce data imported using the Commerce Layer CLI.
• Structured content on Sanity studio.
• Localization support.
• Deployment configuration settings to Netlify.

Sanity Starter Project Structure

Sanity has a defined specification for starters which includes some required files and directories. These specifications provide information about the starter to developers using the starter and make the project function as a reusable starter. Below is the folder structure of a Sanity project with required files and directories (without any frontend added):

├── .sanity-template
├── .sanity-template/assets
├── .sanity-template/data
├── .sanity-template/manifest.json
├── README.md

• .sanity-template is the root directory where all meta-information for using this repository as a template on sanity.io/starters is stored.
• .sanity-template/assets is the directory for storing assets related to displaying information about the starter. In this case, preview images for the overall project and for each site the starter contains.
• .sanity-template/data is the directory to store a Sanity dataset export if you want the starter to launch with some demo content.
• .sanity-template/manifest.json is the JSON file containing details about the Starter as well as deployment information.
• README.md is the markdown file for this project that will be displayed on the Create page.

For a finished starter project, the root of the project should contain all deployable code, including the frontend and studio. Generally, a project spun from a starter is split into three parts:

1. The root for all frontend code
2. The /studio directory for all studio code.
3. The .sanity-template for all starter meta-information.

Here is a sample from the Commerce Layer sanity starter as seen in the image below:

How We Built the Commerce Layer Sanity Starter

In this section, you will learn how we built a starter with an ecommerce application with transactional functionalities powered by Commerce Layer APIs, structured content on Sanity, imported seed data, and deployment configuration to Netlify. If you want to follow along with the guide, you can take a look at the finished project on GitHub here or even install the starter here.

Here is a sequential breakdown of all the steps taken to develop a starter:

1️⃣ Setup a new Sanity project using the Sanity CLI

Sanity has a command-line interface that we can use to interact with Sanity, create new projects, manage datasets, import data, and much more from the CLI. We'll use this CLI to set up a new sanity project following the steps below:

1: Install the CLI

Run the command below to install the Sanity CLI.

npm install -g @sanity/cli

2: Create a new project

Run the command below to bootstrap a new project which will log you into Sanity, create a new project, set up a dataset, and generate the files needed to run the studio environment locally.

sanity init

3: Run the studio

Run the command below to build the initial JavaScript code required to run the studio, and start a local web server.

sanity start

The studio should now run on [localhost:3333](http://localhost:3333). You can always run sanity help to get an overview of other available and useful commands in the Sanity CLI.

2️⃣ Content modeling for the created Sanity studio

Now that we understand how Sanity works and have set up a new sanity project, let's structure our sanity studio schema. Sanity schema defines how your content should be modeled, and this structure reflects in the studio UI. The schema describes the different field types a document consists of. Sanity uses the schema.js file in the /schemas directory to determine the content model of the project.

With Sanity, you define a block of content as a document or split your documents into modules and import them into the parent schema.js file. Generally, there are three categories of Sanity schema types:

• Document types (document and other published custom schemas)
• Primitive types (e.g., boolean, string, text, number, array, datetime, and URL)
• Object types (e.g., object, block, span, reference, slug, image, and file)

You can find all of the Sanity’s types in this reference documentation or learn how to structure your content model based on your needs by reading this comprehensive guide.

For the Commerce Layer starter, our schema.js looks like so in the snippet below with imports of several other module documents. You can view the schema code for each module here in the GitHub repository.

import createSchema from 'part:@sanity/base/schema-creator'
import schemaTypes from 'all:part:@sanity/base/schema-type'

// We import object and document schemas
import product from './product'
import country from './country'
import variant from './variant'
import size from './size'
import taxon from './taxon'
import taxonomy from './taxonomy'
import catalog from './catalog'
import blockContent from './blockContent'

import productImage from './productImage'
import localeString from './locale/String'
import localeText from './locale/Text'
import localeSlug from './locale/Slug'
import localeBlockContent from './locale/BlockContent'

// Then we give our schema to the builder and provide the result to Sanity
export default createSchema({
  // We name our schema
  name: 'default',
  // Then proceed to concatenate our document type
  // to the ones provided by any plugins that are installed
  types: schemaTypes.concat([
    // The following are document types which will appear
    // in the studio.
    product,
    country,
    variant,
    size,
    taxon,
    taxonomy,
    catalog,
    // When added to this list, object types can be used as
    // { type: "typename" } in other document schemas
    productImage,
    blockContent,
    localeString,
    localeText,
    localeSlug,
    localeBlockContent,
  ]),
})

3️⃣ Add content to Sanity studio

If you are working on a new project like we did when we began developing the starter, you will have to manually add content to your project using the Sanity studio running on [localhost:3333](http://localhost:3333). The studio should now have the content fields populated with the configured content schemas in the “Desk” view. You can use that to add content to your project, as seen in the screenshot below.

If you are starting a new project using a starter or a previously saved project, then you can easily import a dataset with saved data following the steps below:

• Extract the production.tar.gz file in /.sanity-template/data directory using the command below:

tar -xf production.tar.gz

The extracted folder name should look like production-export-2021-02-26t14-15-56-557z.

• Run the command below in /studio to import the data.ndjson file in the extracted folder.

sanity dataset import ../.sanity-template/data/<name of extracted folder>/data.ndjson <your_dataset>

You should check the running Sanity studio now to preview the imported content.

4️⃣ Add frontend and integrate with Sanity

Before you add all frontend code to the root directory, you should move the Sanity studio code into a directory named /studio.

At this stage, you will add the frontend code of your project, which can either be a blog, marketing website, CRM, or storefront. The major thing to do here is to use any of the Sanity client libraries to integrate Sanity into your frontend and fetch data. In our case, we used the official Javascript client that works in Node.js and modern browsers.

import sanityClient from '@sanity/client'

const client = sanityClient({
  projectId: process.env.SANITY_PROJECT_ID as string,
  dataset: process.env.SANITY_DATASET as string,
  useCdn: process.env.NODE_ENV === 'production', // `false` if you want to ensure fresh data
})

Here’s an example of how we query Sanity to fetch the country and product data:

import _ from 'lodash'
import {
  SanityCountry,
  SanityProduct
} from './typings'

//Countries
const sanityAllCountries = async (locale = 'en-US') => {
  const lang = parseLocale(locale, '_', '-', 'lowercase')
  const query = `*[_type == "country"]{
    name,
    code,
    marketId,
    defaultLocale,
    "image": {
      "url": image.asset->url
    },
    'catalog': {
      'id': catalog->_id
    }
  } | order(name["${lang}"] asc)`
  const countries = await client.fetch<SanityCountry[]>(query)
  return countries.map((country) => {
    const localization = {
      name: country?.name[lang],
    }
    return { ...country, ...localization }
  })
}

//Products
const sanityGetProduct = async (slug: string, locale = 'en-US') => {
  const lang = parseLocale(locale, '_', '-', 'lowercase')
  const query = `*[_type == "product" && slug["${lang}"].current == "${slug}"]{
    name,
    description,
    reference,
    slug,
    'images': images[]->{
      'url': images.asset->url
    },
    'variants': variants[]->{
      label,
      code,
      name,
      size->,
      'images': images[]->{
        'url': images.asset->url
      }
    }    
  }`
  const item: any[] = await client.fetch(query)
  return parsingProduct(_.first(item), lang)
}

You can explore all our queries for the Commerce Layer starter project here in the GitHub repository. Also, here’s the major code powering our frontend alongside some hooks, utils, components, and dependencies.

Now that you have a Sanity Starter set up, we’ll show you the foundation principles needed to integrate commerce data from Commerce Layer. This is where you will begin to see the powerful combination of Commerce Layer data with Sanity content. And by the end of the tutorial, you will see not only the benefits of this integration, but you will also be able to experiment with your commerce data next to Sanity to see the power of both tools together.

5️⃣ Get Commerce Layer API Credentials

In the starter we built, transactional functionalities of your ecommerce platform are managed by Commerce Layer, while the content is managed by Sanity studio. This will result in better order management and content management. To get started with using Commerce Layer, you will need to create an organization, perform some configurations and settings for your business, seed some demo data, and get your API credentials. The API credentials will allow you to interact with Commerce Layer in your presentation layer (frontend) and the CLI. To get the required credentials, kindly follow the steps below:

1. Create a free developer account here. If you already have an account, kindly skip to Step 3.
2. Upon successful sign-up, skip the onboarding tutorial for the purposes of this article (we'll set up and seed the organization manually through the CLI shortly).
3. Create a new organization for your business.
4. In the Commerce Layer dashboard, click on the Sales channels tab and create an application, with the name: Website. Upon successful creation, you'll get a CLIENT ID , BASE ENDPOINT, and ALLOWED SCOPES. Kindly remember to save that as we'll use it to interact with our application later.
5. In the Commerce Layer dashboard, click on the Integrations tab and create an application, with the name: CLI and role: Admin. Upon successful creation, you'll get a CLIENT ID, CLIENT SECRET, and BASE ENDPOINT. Kindly remember to save that as we'll use it to interact with the CLI later.

6️⃣ Seed Organization with Test Data

The official Commerce Layer CLI helps you to manage your Commerce Layer applications right from the terminal. Installing the CLI provides access to the commercelayer command. You can set it up using the following steps:

• Install the CLI using your favorite package manager:

//npm
npm install -g @commercelayer/cli

//yarn
yarn global add @commercelayer/cli

• Log into your application via the CLI using the previously created integration application credentials like so:

commercelayer applications:login -o <organizationSlug> -i <clientId> -s <clientSecret> -a <applicationAlias>

Now, with the steps below, you can use the CLI to import three demo markets (UK, USA, and Europe), a set of product SKUs, related price lists, related prices, stock locations, and inventory into your organization using the multi_market business model.

• Install the seeder plugin using the command below:

commercelayer plugins:install seeder

• Seed your organization using the command below:

commercelayer seed -b multi_market

7️⃣ Final checklist and Netlify deployment configuration

• In order for a starter to be validated and used through sanity.io/starters, it needs to follow the project name must start with sanity-template-.
• Configure your Sanity metadata in sanity-template.json and add deployment configuration for the frontend web application and Sanity studio like so:

{
  "version": 2.0,
  "title": "Commerce Layer Starter",
  "description": "A multi-country ecommerce starter built with Sanity Studio, Commerce Layer, Next.js, and deployed to Netlify.",
  "previewMedia": {
    "type": "image",
    "src": ".sanity-template/assets/preview.jpg",
    "alt": "Preview image with Commerce Layer, Nextjs, and Netlify's logo"
  },
  "technologies": [
    {
      "id": "nextjs",
      "name": "Next.js",
      "url": "https://nextjs.org"
    },
    {
      "id": "commercelayer",
      "name": "Commerce Layer",
      "url": "https://commercelayer.io"
    },
    {
      "id": "netlify",
      "name": "Netlify",
      "url": "https://netlify.com"
    }
  ],
  "deployment": {
    "provider": "netlify",
    "sites": [
      {
        "id": "studio",
        "type": "studio",
        "title": "Commerce Layer Starter Studio",
        "description": "A multi-country ecommerce starter built with Sanity Studio, Commerce Layer, Next.js, and deployed to Netlify.",
        "dir": "./studio",
        "previewMedia": {
          "type": "image",
          "src": ".sanity-template/assets/studio.png",
          "alt": "A preview image of the Sanity studio."
        },
        "buildSettings": {
          "base": "studio",
          "dir": "/dist",
          "cmd": "npm run build"
        }
      },
      {
        "id": "web",
        "type": "web",
        "title": "Commerce Layer Starter Web",
        "description": "A multi-country ecommerce starter built with Sanity Studio, Commerce Layer, Next.js, and deployed to Netlify.",
        "dir": "./web",
        "previewMedia": {
          "type": "image",
          "src": ".sanity-template/assets/preview.jpg",
          "alt": "A preview image of the web demo."
        },
        "buildSettings": {
          "base": "/",
          "dir": "/out",
          "cmd": "npm run build"
        }
      }
    ]
  }
}

The metadata information is primarily displayed on sanity.io/create as described below by the visual explainer from Sanity docs.

• Test your sanity-template.json file for errors using the sanity-template command:

sanity-template check

• Build your project with the configuration in sanity-template.json using the command:

sanity-template build

• You need to refactor your project's name, projectId and dataset in studio/sanity.json to a dynamic variable so when a user installs your starter via sanity.io/starters, Sanity can populate it with new values. To this, you pass the string value in <#< ... >#> as seen in the snippet below:

 {
  "root": true,
  "project": {
    "name": "<#< sanity.projectTitle >#>",
    "basePath": "/"
  },
  "api": {
    "projectId": "<#< sanity.projectId >#>",
    "dataset": "<#< sanity.dataset >#>"
  }
}

• You can also set up Renovatebot to automatically make and merge pull requests that bump the Sanity dependencies upgrades in studio/package.json. All you need to do is add a renovate.json to the root directory, with the following configuration:

{
  "extends": [
    "github>sanity-io/renovate-presets:sanity-template"
  ]
}

• Run the command below to build the studio to a static bundle and deploy it to Sanity cloud on a <your-project>.sanity.studio URL. You can also deploy anytime you make any change to your studio.

sanity deploy

PS: You can still host a studio on any cloud platform you choose too (here’s how to deploy to Netlify) so you don't have to manually deploy after every change.

• Lastly, push your finished code to GitHub and test it live by **deploying the starter on Sanity following the starter specification:

https://www.sanity.io/create?template=[githubhandle]/sanity-template-[starter-name]

Conclusion

Now that you have built a Sanity starter and integrated Commerce Layer, you can start to add more items and product data stored in Commerce Layer so you can see how your products and prices show up within your content. The power of Commerce Layer is that you can really localize your commerce data to make it work for multiple markets, all of which likely have different prices, SKUs, promotions, and even simple things like item weights and measurements. Commerce Layer gives you tremendous flexibility to sell your products locally and paired with a powerful tool like Sanity, you will be on your way to building the best, most optimized shopping experience for your customers.

You can get started with the Commerce Layer starter by visiting this link, creating a new project and following the instructions in the link. Feel free to join the Commerce Layer Slack community to share what you are able to build after reading this tutorial or showcase the starter on Sanity. For further knowledge, you can learn the central concepts needed to create a 1-click Sanity Starter, learn how to build headless commerce web experiences with Commerce Layer, or learn how to sell internationally with a single Shopify store and Commerce Layer.

Thanks for reading! 🖤

Prerequisites

• Basic knowledge of the command-line interface.
• A working computer with Python installed.
• A notebook created on a registered Google Colab account.

Step One

The first step is to install Jupyter notebook. I recommend you download and install Anaconda for your operating system of choice. This will also install Python, Jupyter Notebook, and other regularly used data engineering packages. Once Anaconda is installed, you automatically have Jupyter installed.

Alternatively, you can install Jupyter using PIP provided you have Python installed already using the command below:

pip3 install --upgrade pip
pip3 install jupyter

Upon a successful installation, you can launch Anaconda and start a Jupyter server using the GUI or use the command line.

Step Two

Install the Colab Jupyter HTTP-over-WebSocket extension that allows you to run Jupyter notebooks using a WebSocket to proxy HTTP traffic. You can achieve that using the command below:

pip install --upgrade jupyter_http_over_ws>=0.0.7

Next, enable the extension:

jupyter serverextension enable --py jupyter_http_over_ws

Step Three

Start a new Jupyter server on port 8888, allowing origin to the Colab domain using the command below:

jupyter notebook \
  --NotebookApp.allow_origin='https://colab.research.google.com' \
  --port=8888 \
  --NotebookApp.port_retries=0

Once the server has started, it will print a backend URL alongside a token for authentication. Kindly copy the entire URL that starts with http://localhost ahead for the next step.

Step Four

In your Google Colab notebook, click on the toggle button at the top right corner showing the RAM and Disk status bar and select the option "Connect a local runtime" as seen in the screenshots below.

You'll then be asked to enter the backend URL you copied earlier. Enter it and click on the "Connect" button. Now you should be connected successfully to your local machine.

Conclusion

If you're running your own personal notebook, you can as well run them locally using Jupyter notebook. However, suppose you're working on a collaborative notebook or want to take advantage of additional Google Colab features like mounting your Google drive directly into the notebook. In that case, the local runtime setup can be useful when your GPU usage reaches its limit. To avoid security issues, make sure you trust the notebook before connecting locally.

I hope you found this helpful; cheers! 💙

In this article, you'll practice the basics of headless commerce by building a simple ecommerce product page with static content, HTML5, and TailwindCSS as seen in the screenshot below. We will then integrate Commerce Layer to make the website shoppable using the Drop-in Javascript library and deploy the application to the cloud. The Drop-in library is a minimal way to get started with headless commerce and Commerce Layer, but if you're building for your business you can opt for a deeper integration using the Commerce Layer SDK.

Prerequisites

• Some HTML, CSS, Javascript, and command-line knowledge.
• A general understanding of how APIs work.
• An IDE and Git installed.

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 device, or IoT device, with ease. You can compose your stack with the best-of-breed tools you want and make any experience shoppable, anywhere, through a blazing-fast, enterprise-grade, and secure API.

The diagram below shows the relationships in an example stack for building a solid ecommerce web application using Commerce Layer and other composable tools.

Getting Started

Let's start by building the static website with HTML and TailwindCSS, all in a single index.html file. We will then integrate Commerce Layer using the Dropin library!

1️⃣ Create the required files

1. Create a new folder somewhere on your computer.
2. Create an index.html file in the root directory.
3. Create a /css directory with a custom.css file in it.

2️⃣ Get your API Credentials

You can create an account to get access to and integrate with Commerce Layer APIs following the steps below:

1. Create a free developer account here. If you already have an account, kindly skip to Step 3.
2. Upon successful sign-up, skip the onboarding tutorial for the purposes of this article (we'll set up and seed the organization manually through the CLI shortly).
3. Create a new organization for your business.
4. In the Commerce Layer dashboard, click on the Sales channels tab and create an application, with the name: Website. Upon successful creation, you'll get a CLIENT ID and BASE ENDPOINT. Kindly remember to save that as we'll use it to interact with our application later.
5. In the Commerce Layer dashboard, click on the Integrations tab and create an application, with the name: CLI and role: Admin. Upon successful creation, you'll get a CLIENT ID, CLIENT SECRET, and BASE ENDPOINT. Kindly remember to save that as we'll use it to interact with the CLI later.

3️⃣ Setup Commerce Layer CLI

The Commerce Layer CLI helps you to manage your Commerce Layer applications right from the terminal. Installing the CLI provides access to the commercelayer command. You can set it up using the following steps:

1. Install the CLI using your favorite package manager:

//npm
npm install -g @commercelayer/cli

//yarn
yarn global add @commercelayer/cli

1. Log into your application via the CLI using the previously created CLI credentials like so:

commercelayer applications:login -o <organizationSlug> -i <clientId> -s <clientSecret> -a <applicationAlias>

You will do the above for both applications (sales_channel and integration). The login command adds the application and sets it as the current one in session. You should log into the sales_channel first, and then the integration. This way, you'll have the integration as the current app (which is required by the seeder).

4️⃣ Seed organization with test data

As we mentioned earlier, you can seed your organization with a merchant, a set of markets, products (SKUs), related prices, shipping methods, inventory, etc. via the CLI.

1. Install the seeder plugin using the command below:

commercelayer plugins:install seeder

1. Seed your organization using the command below:

commercelayer seed

The CLI will use Commerce Layer's default seed data to populate your organization with a set of products (SKUs), related prices, and inventory information.

Build the Static Product Page

Now let's build our product page in a single index.html file which will contain the markup for product details, prices, available variants, available quantity, item availability, shopping bag, and checkout. You can find the full code on GitHub. In this tutorial, we will only highlight the important HTML elements and related data attributes we need for dynamic data. We will replace all style classes with the dummy content [...] so you can focus on the utility classes required to interact with the Drop-in library.

We will be using some data attributes to store extra information that doesn't have any visual representation like data-sku-code to store the SKU code of an item or data-add-to-bag-id to add a selected variant to the shopping bag when the "Add to bag" button is clicked. The Dropin library requires some data attributes to add dynamic data to a static web page. With this mechanism, you're building ecommerce with almost no code required (just HTML tags). Now let's proceed!

1️⃣ Create Static Content

You should add some content to the page, such as product names, descriptions, reviews and images, and more. This content can be created with any CMS and rendered with any language. For this tutorial we're using just plain HTML.

<!DOCTYPE html>
<html>
   <head>
      <!-- Static content -->
      <title>Headless Swag Store</title>
      <link
          href="https://unpkg.com/tailwindcss@^2/dist/tailwind.min.css"
          rel="stylesheet"
        /><div class="mt-10">
                <div class="flex items-center justify-between">
                  <h3 class="text-sm text-indigo-600 font-medium">
                    Choose a size
                  </h3>
                </div>

                <div class="mt-4 flex -mx-2">
                  <div class="flex-1 px-2">
                    <select
                      name="variant"
                      class="clayer-variant-select block appearance-none border-2 border-gray-500 text-base-700 py-3 px-4 pr-8 rounded"
                      data-sku-reference="SWEETHMUB7B7B7000000"
                      data-price-container-id="price"
                      data-availability-message-container-id="availability-message"
                      data-add-to-bag-id="add-to-bag"
                      data-add-to-bag-quantity-id="add-to-bag-quantity"
                    >
                      <option value="" disabled selected>Select variant</option>
                      <option
                        class="clayer-variant"
                        data-sku-code="SWEETHMUB7B7B7000000SXXX"
                        data-sku-name="Sport Grey Unisex Hoodie Sweatshirt with Black Logo (S)"
                        data-sku-image-url="https://img.commercelayer.io/skus/SWEETHMUB7B7B7000000.png?fm=jpg&q=90"
                      >
                        Small
                      </option>
                      <option
                        class="clayer-variant"
                        data-sku-code="SWEETHMUB7B7B7000000MXXX"
                        data-sku-name="Sport Grey Unisex Hoodie Sweatshirt with Black Logo (M)"
                        data-sku-image-url="https://img.commercelayer.io/skus/SWEETHMUB7B7B7000000.png?fm=jpg&q=90"
                      >
                        Medium
                      </option>
                      <option
                        class="clayer-variant"
                        data-sku-code="SWEETHMUB7B7B7000000LXXX"
                        data-sku-name="Sport Grey Unisex Hoodie Sweatshirt with Black Logo (L)"
                        data-sku-image-url="https://img.commercelayer.io/skus/SWEETHMUB7B7B7000000.png?fm=jpg&q=90"
                      >
                        Large
                      </option>
                      <option
                        class="clayer-variant"
                        data-sku-code="SWEETHMUB7B7B7000000XLXX"
                        data-sku-name="Sport Grey Unisex Hoodie Sweatshirt with Black Logo (XL)"
                        data-sku-image-url="https://img.commercelayer.io/skus/SWEETHMUB7B7B7000000.png?fm=jpg&q=90"
                      >
                        Extra Large
                      </option>
                    </select>
                  </div>
                  <!-- Add to bag quantity -->
                  <div class="flex-1 px-2">
                    <label for="add-to-bag-quantity" class="sr-only"
                      >Add to bag quantity</label
                    >
                    <input
                      id="add-to-bag-quantity"
                      type="number"
                      min="1"
                      class="clayer-add-to-bag-quantity block appearance-none border-2 border-gray-500 text-base-700 py-3 px-4 pr-2 rounded"
                    />
                  </div>
                </div>
              </div>
      <link
          rel="icon"
          href="https://data.commercelayer.app/assets/images/favicons/favicon.ico"
      />   
     </head>
   <body>
      <!-- Static content -->

      <!-- Image gallery -->
      <div class="mt-6 max-w-2xl mx-auto sm:px-6 lg:max-w-7xl lg:px-8 lg:grid lg:grid-cols-3 lg:gap-x-8">
         <div class="hidden aspect-w-3 aspect-h-4 rounded-lg overflow-hidden lg:block" >
            <img
               src="./assets/img/01.png"
               alt="Model wearing the gray men hoodie"
               class="w-full h-full object-center object-cover"
               />
         </div>
         <div class="hidden lg:grid lg:grid-cols-1 lg:gap-y-8">
            <div class="aspect-w-3 aspect-h-2 rounded-lg overflow-hidden">
               <img
                  src="./assets/img/02.png"
                  alt="The gray men hoodie"
                  class="w-full h-full object-center object-cover"
                  />
            </div>
            <div class="aspect-w-3 aspect-h-2 rounded-lg overflow-hidden">
               <img
                  src="./assets/img/03.png"
                  alt="The gray men hoodie"
                  class="w-full h-full object-center object-cover"
                  />
            </div>
         </div>
         <div class="aspect-w-4 aspect-h-5 sm:rounded-lg sm:overflow-hidden lg:aspect-w-3 lg:aspect-h-4" >
            <img
               src="./assets/img/04.png"
               alt="The gray men hoodie"
               class="w-full h-full object-center object-cover"
               />
         </div>
      </div>

      <!-- Product info -->
      <div class="max-w-2xl mx-auto pt-10 pb-8 px-4 sm:px-6 lg:max-w-7xl lg:pt-16 lg:px-8 lg:grid lg:grid-cols-3 lg:grid-rows-[auto,auto,1fr] lg:gap-x-8" >
      <div class="lg:col-span-2 lg:border-r lg:border-gray-200 lg:pr-8">
         <h1 class="text-2xl font-extrabold tracking-tight text-gray-900 sm:text-3xl" >
            Sport Grey Unisex Hoodie Sweatshirt
         </h1>

         <!-- Description and details -->
         <div class="py-4">
            <h3 class="sr-only">Description</h3>
            <div class="space-y-6">
               <p class="text-base text-gray-900">
                  This comfortable hoodie is made of 100% combed ring-spun
                  cotton except for heather black logo, which contains
                  polyester. Our premium Unisex Sport Hoodie Sweatshirt is
                  everything you could ask for: it's warm and cozy,
                  heavyweight, unique, roomy, and it's built to last. Sign up
                  for our subscription service and be the first to get new,
                  exciting colors, like our upcoming "Charcoal Gray" limited
                  release.
               </p>
            </div>
         </div>
      </div>
   </body>
</html>

2️⃣ Add Configuration

Add the code below to <body> section of the index.html file just before the </body> tag and add the required publishable configuration data.

<!-- Config -->
<div
  id="clayer-config"
  data-base-url="<yourOrganizationUrl>"
  data-cache="true"
  data-client-id="<yourClientId>"
  data-market-id="<yourMarketId>"
  data-country-code="US"
  data-language-code="en"
  data-cart-url="<https://example.com/cart>"
  data-return-url="<https://example.com/return>"
  data-privacy-url="<https://example.com/privacy>"
  data-terms-url="<https://example.com/terms>"
  data-dev-settings-debug="true"
  data-dev-settings-console="true"
  data-dev-settings-trace="true"
></div>

<!-- JS Library -->
<script
  type="text/javascript"
  src="<https://cdn.jsdelivr.net/npm/@commercelayer/js-dropin@1.5.12/lib/index.js>">
</script>

• clayer-config — stores all the data attributes with your credentials and page preferences.
• data-base-url — stores your organization base endpoint as defined on Commerce Layer (something like https://yourdomain.commercelayer.io).
• data-client-id — stores your sales channel application's client ID.
• data-market-id stores the number of the market you want to work on as defined in Commerce Layer.
• data-country-code — stores the country code of the country assigned to an order (e.g US)
• data-language-code — stores the language assigned to an order (e.g en-US).
• data-cart-url, data-return-url, data-privacy-url, data-terms-url — store the links to external pages that Commerce Layer should redirect your user to upon certain requests (we don't need these for this tutorial, so we'll add some dummy links).

3️⃣ Add a Price

Add the markup below to fetch the selling price (amount) and original price (compare-at-amount) of an SKU. You should add an element with clayer-price class and data-sku-code data attribute wherever you want to show a product price. The child element with class amount gets populated with the price that has been defined in Commerce Layer for that SKU code (for the market defined in the configuration step above). The child element with class compare-at-amount gets populated only if compare-at-amount is defined and is higher than the amount. The price ID is used to match the data-price-container-id in the variant options (as seen in the next section).

<!DOCTYPE html>
<html>
   <head>
      <!-- Static content [...] -->
   </head>
   <body>
      <!-- Static content [...] -->

      <!-- Price -->
      <div class="...">
      <h2 class="...">Product information</h2>
      <div
         class="... clayer-price"
         id="price"
         data-sku-code="SWEETHMUB7B7B7000000XLXX"
         >
         <span class="... amount"></span>
         <span class="... compare-at-amount"></span>
      </div>

      <!-- Config [...] -->

      <!-- JS Library [...] -->
   </body>
</html>

4️⃣ Add Variants Selection

If your product has many variants, add an element with clayer-variant class and data-sku-code data attribute for each variant option. This will fetch the SKU for each variant from Commerce Layer. You can use either a select tag or a list of radio buttons (appending the class clayer-variant-select or clayer-variant-radio respectively). You can also add other data attributes that will be used in the shopping bag based on a user's variant selection such as:

• data-sku-name — the name of the selected SKU to be displayed in the shopping bag.
• data-sku-reference — the reference of the selected SKU to be displayed in the shopping bag.
• data-sku-image-url — the URL to an image of the SKU to be displayed in the shopping bag.
• data-price-container-id — the ID of the DOM element that contains the price for this SKU, in the current market (potentially different variants can have different prices; when selecting a new variant, the price will be updated accordingly).
• data-availability-message-container-id — the ID of the DOM element that contains the availability message for this SKU, in the current market (more on this later).
• data-add-to-bag-id: the ID of the "Add to bag" DOM element (when clicking the "Add to bag" button with the specified ID, the selected variant will be added to bag).
• data-add-to-bag-quantity-id — the ID of the "Add to bag quantity" DOM element (when clicking the "Add to bag" button with the specified ID, the selected quantity of the variant will be added to bag).

<!DOCTYPE html>
<html>
   <head>
      <!-- Static content [...] -->
   </head>
   <body>
      <!-- Static content [...] -->

      <!-- Price  [...] -->

      <!-- Variants (select sizes) -->
    <div class="...">
      <div class="...">
        <h3 class="...">Choose a size</h3>
      </div>

      <div class="mt-4 flex -mx-2">
        <div class="flex-1 px-2">
          <select
            name="variant"
            class="clayer-variant-select ..."
            data-sku-reference="SWEETHMUB7B7B7000000"
            data-price-container-id="price"
            data-availability-message-container-id="availability-message"
            data-add-to-bag-id="add-to-bag"
            data-add-to-bag-quantity-id="add-to-bag-quantity"
          >
            <option value="" disabled selected>Select variant</option>
            <option
              class="clayer-variant"
              data-sku-code="SWEETHMUB7B7B7000000SXXX"
              data-sku-name="Sport Grey Unisex Hoodie Sweatshirt with Black Logo (S)"
              data-sku-image-url="https://img.commercelayer.io/skus/SWEETHMUB7B7B7000000.png?fm=jpg&q=90"
            >Small
            </option>
            <option
              class="clayer-variant"
              data-sku-code="SWEETHMUB7B7B7000000MXXX"
              data-sku-name="Sport Grey Unisex Hoodie Sweatshirt with Black Logo (M)"
              data-sku-image-url="https://img.commercelayer.io/skus/SWEETHMUB7B7B7000000.png?fm=jpg&q=90"
            >Medium
            </option>
            <option
              class="clayer-variant"
              data-sku-code="SWEETHMUB7B7B7000000LXXX"
              data-sku-name="Sport Grey Unisex Hoodie Sweatshirt with Black Logo (L)"
              data-sku-image-url="https://img.commercelayer.io/skus/SWEETHMUB7B7B7000000.png?fm=jpg&q=90"
            >Large
            </option>
            <option
              class="clayer-variant"
              data-sku-code="SWEETHMUB7B7B7000000XLXX"
              data-sku-name="Sport Grey Unisex Hoodie Sweatshirt with Black Logo (XL)"
              data-sku-image-url="https://img.commercelayer.io/skus/SWEETHMUB7B7B7000000.png?fm=jpg&q=90"
            >Extra Large
            </option>
          </select>
        </div>
      </div>
    </div>

           <!-- Other variant input elements [...] -->

      <!-- Config [...] -->

      <!-- JS Library [...] -->
   </body>

5️⃣ Add to Bag

When an option (variant) is selected and the "Add to bag" button is clicked, the selected variant is added to the shopping bag using the clayer-add-to-bag class and ID that matches the variants' data-add-to-bag-id. You can also optionally add a quantity field to let the customer add more than one item to the shopping bag using the clayer-add-to-bag-quantity attribute.

<!DOCTYPE html>
<html>
   <head>
      <!-- Static content [...] -->
   </head>
   <body>
      <!-- Static content [...] -->

      <!-- Price  [...] -->

      <!-- Variants (select sizes) -->

      <!-- Add to bag quantity -->
      <div class="...">
          <label for="add-to-bag-quantity" class="...">Add to bag quantity</label>
        <input
              id="add-to-bag-quantity"
              type="number"
              min="1"
              class="clayer-add-to-bag-quantity ..."
        />
      </div>

      <!-- Add to bag button -->
      <a
         href="#"
         class="clayer-add-to-bag ..."
         id="add-to-bag"
         data-availability-message-container-id="availability-message"
         >
      Add to bag
      </a>

      <!-- Config [...] -->

      <!-- JS Library [...] -->
   </body>
</html>

6️⃣ Add Availability Message Templates

Add an element with clayer-availability-message-available-template ID as the template tag to be displayed when the selected SKU is available. All the child elements will be populated with the delivery lead time and shipping method information related to the selected variant.

Add an element with clayer-availability-message-unavailable-template ID as the template tag to be displayed when the selected SKU is not available. This element will be appended to a specific container when customers will try to add an SKU to the shopping bag and that SKU’s stock item has a quantity of zero or doesn’t exist at all. If you try to create a line item, you will get an "out of stock" error. The clayer-availability-message-unavailable-template is used to store an "out of stock" message.

<!DOCTYPE html>
<html>
   <head>
      <!-- Static content [...] -->
   </head>
   <body>
      <!-- Static content [...] -->

      <!-- Price  [...] -->

      <!-- Variants (select sizes) -->

      <!-- Add to bag quantity -->

      <!-- Availability message templates -->
      <div
         class="... clayer-availability-message-container"
         id="availability-message"
         ></div>
      <template id="clayer-availability-message-available-template">
         <p class="...">
            Available in
            <span class="clayer-availability-message-available-min-days"></span>
            -
            <span class="clayer-availability-message-available-max-days"></span>
            days with
            <span class="clayer-availability-message-available-shipping-method-name"></span>
            (<span class="clayer-availability-message-available-shipping-method-price"></span>)
         </p>
      </template>
      <template id="clayer-availability-message-unavailable-template">
         <p class="...">The selected SKU is not available.</p>
      </template>
      </div>
      </div>

      <!-- Config [...] -->

      <!-- JS Library [...] -->
   </body>
</html>

7️⃣ Add Shopping Bag Summary

The shopping bag includes a list of all items added to the bag alongside a summary of the current shopping bag details. Add an element with clayer-shopping-bag-container ID wherever you want to show the shopping bag. The clayer-shopping-bag-items-container is used as the parent element of the shopping bag line items, built from the clayer-shopping-bag-item-template template tag. The lists below explain what each child data attribute does.

The line item template elements:

• clayer-shopping-bag-item-name — will be populated with the name of the SKU.
• clayer-shopping-bag-item-unit-amount — displays the unit amount of the SKU.
• clayer-shopping-bag-item-qty-container — displays an input field with the quantity of the SKU added to the bag (you can use this to update the quantity too).
• clayer-shopping-bag-item-availability-message-container — displays an “out of stock” message (contained in clayer-availability-message-unavailable-template) when you change a quantity and that quantity is not available.
• clayer-shopping-bag-item-total-amount — displays the total amount of a line item.
• clayer-shopping-bag-item-remove — displays a link to remove an item from the shopping bag.

The order summary elements:

• clayer-shopping-bag-subtotal — displays the subtotal amount of the entire shopping bag.
• clayer-shopping-bag-shipping — displays the shipping cost of the order.
• clayer-shopping-bag-payment — displays the selected payment method charge (if any).
• clayer-shopping-bag-discount — displays the discount amount of the order (if applied).
• clayer-shopping-bag-taxes — displays the cost of tax (if present).
• clayer-shopping-bag-total — displays the grand total summing up all the above costs for the order.

By default, the shopping bag container is always closed. The clayer-shopping-bag-toggle element toggles an open class (attached to a button) on the shopping bag container.

<!DOCTYPE html>
<html>
   <head>
      <!-- Static content [...] -->
   </head>
   <body>
      <!-- Static content [...] -->

      <!-- Price  [...] -->

      <!-- Variants (select sizes) -->

      <!-- Add to bag quantity -->

      <!-- Availability message templates -->

      <!-- Shopping bag -->
      <div class="...">
      <h2 class="...">Shopping bag</h2>
      <p class="...">
         Your shopping bag contains
         <span class="... clayer-shopping-bag-items-count">0</span>
         items worth
         <span class="... clayer-shopping-bag-total"></span>
      </p>
      <button class="... clayer-shopping-bag-toggle">
      Toggle Bag &#8645;
      </button>
      <div id="clayer-shopping-bag-container">
      <table class="...">
         <thead class="...">
            <tr>
               <th class="...">
                  SKU
               </th>
               <th class="...">
                  Unit price
               </th>
               <th class="...">
                  Q.ty
               </th>
               <th class="...">
                  Total
               </th>
               <th class="...">
               </th>
            </tr>
         </thead>
         <tbody class="..." id="clayer-shopping-bag-items-container"></tbody>
         <template id="clayer-shopping-bag-item-template">
            <tr>
               <td class="...">
                  <span class="clayer-shopping-bag-item-name"></span>
               </td>
               <td class="... clayer-shopping-bag-item-unit-amount"></td>
               <td class="... clayer-shopping-bag-item-qty-container">
                  <input
                     type="number"
                     min="1"
                     class="..."
                     />
                  <span
                     class="... clayer-shopping-bag-item-availability-message-container"></span>
               </td>
               <td class="... clayer-shopping-bag-item-total-amount"></td>
               <td>
                  <a href="#" class="... clayer-shopping-bag-item-remove">❌</a>
               </td>
            </tr>
         </template>
      </table>
      <hr />
      <div class="...">
         <div class="...">
            <p class="...">
               Subtotal:
               <span class="clayer-shopping-bag-subtotal"></span>
            </p>
            <p class="...">
               Shipping:
               <span class="clayer-shopping-bag-shipping"></span>
            </p>
            <p class="...">
               Payment:
               <span class="clayer-shopping-bag-payment"></span>
            </p>
            <p class="...">
               Discount:
               <span class="clayer-shopping-bag-discount"></span>
            </p>
            <p class="...">
               Taxes:
               <span class="clayer-shopping-bag-taxes"></span>
            </p>
            <p class="...">
               Total:
               <span class="clayer-shopping-bag-total"></span>
            </p>
         </div>
      </div>

      <!-- Config [...] -->

      <!-- JS Library [...] -->
   </body>
</html>

8️⃣ Add Checkout Button

Add an element with clayer-shopping-bag-checkout class wherever you want to show the checkout button. This button will link to a dedicated checkout page where a customer can complete their purchase and place the order. We'll explain how this works soon.

<!DOCTYPE html>
<html>
   <head>
      <!-- Static content [...] -->
   </head>
   <body>
      <!-- Static content [...] -->

      <!-- Price  [...] -->

      <!-- Variants (select sizes) -->

      <!-- Add to bag quantity -->

      <!-- Availability message templates -->

      <!-- Shopping bag -->

      <!--Checkout button-->
      <a href="#" class="... clayer-shopping-bag-checkout">
      Proceed to checkout
      </a>

      <!-- Config [...] -->

      <!-- JS Library [...] -->
   </body>
</html>

Coupled together, we get a nice-looking product page with some static content and some elements updated dynamically. In summary, once a user selects a variant and clicks the "Add to bag" button, we pass the data down with help from the specified data attributes and create an order associated with some line items. If there are any errors, we display them in the availability message container. The customer can then decide to check out the order.

Checkout Functionality

The Drop-in library uses the Commerce Layer checkout application to provide a PCI-compliant, PSD2-compliant, and production-ready checkout flow powered by Commerce Layer APIs. The orders API will return the checkout URL using the format <your organization slug>.checkout.commercelayer.app/:order_id?accessToken=<token>. The Drop-in library will then automatically pass that URL to the checkout button (with class clayer-shopping-bag-checkout) alongside the order ID and required access token. When you click on the checkout button, you will be redirected to the checkout application. Upon successful checkout, the order will be sent to and can be managed in the orders management system (OMS), in the Commerce Layer dashboard. So cool, right 🙃?

Deploying the Final Project

Now let's push our project to GitHub and deploy it to Netlify or Vercel. Whenever you push any change to GitHub, both tools will run your build and re-deploy the repository again. You can follow the guidelines in the documentation for Netlify or Vercel to get set up for either tool.

Additional resources

An order can consist of a customer, line items (SKUs, cost of shipping method, cost of payment method, taxes, or gift cards), a billing address, a shipping address, discount(s) calculated from active promotions, redeemed gift card(s), a payment method, and a payment source type. You can read this guide to learn more about the anatomy of an order and check out the Commerce Layer API reference. Also, check out the Commerce Layer data model for an overview of the most relevant API entities, their mutual relationships, and common usage (including E-R diagrams).

Here are some more resources to learn about headless commerce, Commerce Layer, and data attributes:

• Why Commerce Layer?
• Comprehensive Guide to Headless Commerce
• Commerce Layer Core Concepts
• Commerce Layer Developer Resources
• Jamstack Whitepaper
• Using data attributes
• HTMLOrForeignElement.dataset

Conclusion

Yes! You have successfully turned a website into a shoppable website using Commerce Layer and the Drop-in Library; how cool is that?! 😃.

With Commerce Layer, you can manage all transactional parts of your ecommerce business, integrate with any CMS of your choice to manage content, build your user interface/experience with your favorite technologies, and build your business logic without friction. In addition, this will result in more flexibility and autonomy between sub-teams in your engineering team, thereby helping you scale your business globally.

This is a great way to quickly start building with Commerce Layer and can be used for specific use cases such as adding ecommerce to a Jamstack website or transforming a Shopify theme into a multi-market store. To create a comprehensive global shopping platform for your brand, check out our documentation and join our Slack community to learn about the possibilities.

Prerequisites

• Background knowledge of R programming language.
• A computer machine running Windows, Linux, or macOS operating system.
• Ability to use the web browser and command-line interface.
• A little smile? :)

R Installation Guide

To use RStudio, you need to install the R programming language first. R is a free software environment for statistical computing and graphics. Next, you have to choose your preferred CRAN (Comprehensive R Archive Network) mirror from the available options to download R. The Comprehensive R Archive Network (CRAN) is a network of FTP and web servers around the world that store identical, up-to-date versions of R and acts as the primary web service distributing R sources, binaries, extension packages, and documentation.

To save yourself some stress, you can choose the 0-Cloud option, as that will automatically redirect you to the best and closest server.

Installing on Windows

Download the latest version of the base distribution of R here. This should download a file with the name R-4.1.1-win.exe (version name would change in the future) that will work on 32 and 64 bits. You can then run the installer file and install as you normally install .exe files. If you want, you can read the Windows installation guide for more instructions.

Installing on Linux

Download the latest version of R for Debian, Fedora, Redhat, Suse, and Ubuntu here. Alternatively, you can use the commands below to install from your terminal.

For Debian

apt-get update
apt-get install r-base r-base-dev

If you want, you can read the Debian installation guide for more instructions.

For Fedora

sudo dnf install R

If you want, you can read the Fedora installation guide for more instructions.

For Redhat

sudo dnf install R

If you want, you can read the Redhat installation guide for more instructions.

For Suse

VERSION=$(grep "^PRETTY_NAME" /etc/os-release | tr " " "_" | sed -e 's/PRETTY_NAME=//' | sed -e 's/"//g')
zypper addrepo -f http://download.opensuse.org/repositories/devel\:/languages\:/R\:/patched/$VERSION/ R-base

zypper install R-base R-base-devel

If you want, you can read the Suse installation guide for more instructions.

For Ubuntu

# update indices
apt update -qq

# install required helper packages
apt install --no-install-recommends software-properties-common dirmngr

# add the signing key
wget -qO- https://cloud.r-project.org/bin/linux/ubuntu/marutter_pubkey.asc | sudo tee -a /etc/apt/trusted.gpg.d/cran_ubuntu_key.asc

# add the R 4.0 repo from CRAN
add-apt-repository "deb https://cloud.r-project.org/bin/linux/ubuntu $(lsb_release -cs)-cran40/"

apt install --no-install-recommends r-base

If you want, you can read the Ubuntu installation guide for more instructions.

Installing on macOS

Download the latest version of the base distribution of R here. This should download a file with the name R-4.1.1.pkg (version name would change in the future). You can then run the installer file and install as you normally install .pkg files.

If you want, you can read the macOS installation guide for more instructions.

R Studio Installation Guide

There are two versions of RStudio; the RStudio Desktop (the desktop app) and RStudio Server (the server running on a web browser). Both have free and paid editions with several additional features, as seen in the screenshots taken from the R Studio official website below:

To download either of the versions, head to the download page and click on the "download" button for RStudio Desktop or RStudio Server. Alternatively, you can click on the "buy" button if you want to purchase the other editions. Once you click on "download," you will be redirected to the download page, which will automatically detect your operating system and recommend the file to download (this works only for RStudio Desktop. You can find the RStudio Server installation guide here). Below that, you will also find a list of other installers for different operating systems. So, pick what you want and download the file.

Conclusion

Upon successful installation, you can now use RStudio Desktop to write your R programs whilst enjoying all the benefits of R Studio. As seen in the screenshot below from my setup, you'll get the editor at the left-corner, console, terminal, and jobs at the bottom-left-corner, environment at the right-corner, and plots/packages, at the bottom-right corner of the application window. Of course, you can customize the arrangement, change your theme, download R packages, and other settings as you deem fit.

That's all for this tutorial, and I hope it was helpful. I'll be publishing an introductory guide to the R programming language for beginners soon, so ensure to subscribe to my newsletter to get updated. For RStudio product guides and helpful tutorials, you can check out the RStudio documentation page. Cheers! 💙

Attributions

• R Project
• RStudio product website
• R Programming Tutorial - Learn the Basics of Statistical Computing

I trust you're doing well and staying safe.

The past couple of weeks have been challenging and tiring from the fight against police brutality and protests to #EndSars ✊🏾 in Nigeria 🇳🇬.

Amidst all the struggles, I'm excited to share some good news and announce that I have joined the distinguished team at Commerce Layer as a Developer Advocate.

Quick Intro to Commerce Layer

Web development today has shifted from the traditional ways and is completely different from what it was a few years ago. Commerce Layer is a purely transactional engine based platform that integrates with any CMS of your choice, adding international shopping capabilities to ANY presentation layer — the perfect solution to build e-commerce on the JAMstack, providing the highest performance and reducing the cost of infrastructure.

As a headless commerce platform and order management system, Commerce Layer lets you add global shopping capabilities to any website, mobile app, chatbot, or IoT device, with ease via our commerce APIs.

Okay?

I'm passionate about the JAMstack ecosystem and can't wait to do amazing stuff with the community of JAMstack and e-commerce developers at Commerce Layer. You'll find me creating, amplifying & looking for the right examples, messaging, and languages for audiences using our developer's documentation, open-source project's, and a bunch of random DevRel stuff.

If you have any questions about Commerce Layer or any of our services, feel free to DM me on Twitter or join our Slack by requesting an invite here.

Keep trailblazing, and stay safe! 💙

In this article, I'll show you how to combine files or directories in an archive, compress these archives (reducing the final archive file size) alongside how to extract the collected files from the archive using the CLI.

Prerequisites

Before you begin this tutorial, you'll need the following:

• A shell running on your computer (CommandPromt, Bash, Zsh e.t.c)
• Bunch of files and directories on your computer. If you don't have some, you can create some files and directories (if you want to) with the command below:

mkdir folder{1..10}
touch file{1..10}

• How about a small smile? 😊

Introduction to CLI

As opposed to the GUI (Graphical User Interface), which provides users with a user interface with which they can interact with a computer, the CLI (Command Line Interface) allows users to input in some commands meant to initiate some action on the computer in the form of text via a terminal. These commands will run via a shell with the desired result displayed back on the terminal.

One fantastic feature of the operating system is the Command Line Interface (CLI), which allows users to interact with their computer from a shell. This shell is a REPL (Read, Evaluate, Print, Loop) environment where users can enter a command, and the shell runs it and returns a result.

How to Create an Archive (File or Directory) with Tar

Tar (an abbrevation for Tape Archive) is a Linux command used to create a .tar, .tar.gz, or .tar.bz2 archive file (also known as "tarballs").

You can combine files or directories into an archive with the command below like so:

tar -cf archive-name.tar /path/to/file-or-directory

You should now see a file called archive-name.tar containing the files or directories in /path/to/file-or-directory.

Here's a breakdown of the command we used:

• tar is the tape archive command.
• -c is the flag that creates the archive file.
• -f is the flag that allows you to specify the filename for the archive.

Let's run ls -lshS to list the files in our current directory with their file sizes in a readable format and sort the files from biggest to smallest.

The contents of the node_modules directory with the initial 32K size compressed into the archive will result in a 174M size.

How to Create an Archive and Compress with GZIP

By default, we want our archive files to be compressed and produce lesser file sizes (I do, don't you? 😌); however, the previous command only collected the files into the archive. To compress your final archive, you'll append the -z flag, which will use GZIP to automatically compress the archive and produce a .tar.gz file.

gzip is a file format and a software application used for file compression and decompression. The program was created by Jean-loup Gailly and Mark Adler as a free software replacement for the compress program used in early Unix systems, and intended for use by GNU ~ Wikepedia

Let's test this with the same node_modules folder like so:

tar -zcf archive-name.tar.gz node_modules

You should now see a file called archive-name.tar.gz containing the files and directories in node_modules.

Let's run ls -lshS to list the files in our current directory with their file sizes in a readable format and sort the files from biggest to smallest.

The contents of the node_modules directory with the initial 32K size compressed into the archive will result in a 34M size.

Notice that the archive-name.tar.gz is significantly smaller than archive-name.tar? This is because we used gzip compression.

Here's a breakdown of the command we used:

• tar is the tape archive command.
• -z is the flag that compresses the archive with gzip.
• -c is the flag that creates the archive file.
• -f is the flag that allows you to specify the filename for the archive.

How to Create an Archive and Compress with BZIP2

GZIP is the most frequently used compression method; however, there's a BZIP2 method that compresses more than GZIP but takes more time to execute. GZIP is faster, but it generally compresses a bit less (larger file) while BZIP2 is slower, but it compresses a bit more (smaller file).

bzip2 is a free and open-source file compression program that uses the Burrows-Wheeler algorithm. It only compresses single files and is not a file archiver. It is developed by Julian Seward and maintained by Federico Mena. Seward made the first public release of bzip2, version 0.15, in July 1996. ~ Wikipedia

Let's test this with the same node_modules folder like so:

tar -jcf archive-name.tar.bz2 node_modules

You should now see a file called archive-name.tar.bz2 containing the files and directories in node_modules.

Let's run ls -lshS to list the files in our current directory with their file sizes in a readable format and sort the files from biggest to smallest.

The contents of the node_modules directory with the initial 32K size compressed into the archive will result in a 27M size.

Notice that the archive-name.tar.bz2 is significantly smaller than archive-name.tar.gz? This is because we used bzip2 compression.

Here's a breakdown of the command we used:

• tar is the tape archive command.
• -j is the flag that compresses the archive with bzip2.
• -c is the flag that creates the archive file.
• -f is the flag that allows you to specify the filename for the archive.

How to Compress Multiple Files or Directories at Once

You can compress multiple files or directories at once using the same command and specifying the paths of the files or directories with a space separating each path.

tar -cf archive-name.tar /path/to/file /path/to/directory /path/to/file-or-directory

How to List the Contents of an Archive File

You can list the content of an archive-name.tar, archive-name.tar.gz, or archive-name.tar.bz2 file by adding the -t flag to their respective tar command.

If you're familiar with Vim, you can easily list out the contents using vim archive-name.tar. However, let's learn how to do this with the Tar command.

Uncompressed Archive

tar -tf archive-name.tar

Here's a breakdown of the command we used:

• tar is the tape archive command.
• -t is the flag that lists the content of the archive
• -f is the flag that allows you to specify the filename for the archive.

Compressed Archive (GZIP)

tar -ztf archive-name.tar.gz

Here's a breakdown of the command we used:

• tar is the tape archive command.
• -z is the flag that compresses the archive with gzip.
• -t is the flag that lists the content of the archive
• -f is the flag that allows you to specify the filename for the archive.

Compressed Archive (BZIP2)

tar -jtf archive-name.tar.bz2

Here's a breakdown of the command we used:

• tar is the tape archive command.
• -j is the flag that compresses the archive with bzip2.
• -t is the flag that lists the content of the archive
• -f is the flag that allows you to specify the filename for the archive.

How to Extract the Contents of an Archive File

Now you've learned how to create an archive file, compress, and list out its content. Let's extract the archive file (which should be your final destination, yeah?).

tar -xf archive-name.tar

By default, the archive content will be extracted into the current working directory. You can then specify a directory to extract to by appending an additional -C flag and the destination path like so:

tar -xf archive-name.tar -C /destination-path/

Here's a breakdown of the command we used:

• tar is the tape archive command.
• -x is the flag that extracts the file.
• -f is the flag that allows you to specify the filename for the archive.
• -C is the flag that specifies the destination folder to extract the archive.

How to Display Archive Progress

Want to see the progress of the archive process? You can add the -v verbose mode flag, which will display the archive progress in the terminal while creating the archive.

Let's test this like so:

tar -cvf archive-name.tar /path/to/file-or-directory

Conclusion

If you're continually using or contributing to open-source, you'll come across many .tar.gz files, which is mostly used to bundle and compress the installable file of the project. With this article, I hope you'll harness these files effectively, like the boss that you are.

If you forget any command or are unsure about what to do, you can run tar --help or man tar which will display a manual with all possible options for the tar command.

Here are some useful Tar flags for your reference:

Thanks for reading! 💙

In this article, I'll show you an overview of how content management can be optimized using the headless content management system(CMS) to ensure the reusability of content across several digital platforms or presentation layers (web, mobile, smartwatches, VR headsets, or home assistants).

Introduction to Content Management

The Library of Alexandria is one of the world's largest and most significant ancient libraries. (300 BC to about AD 273) and was the first attempt at managing content. Librarians preserved content in the form of scrolls and codices. They were the first content managers who also controlled access to this preserved content.

Image source: Google search

Content is information produced through some editorial process intended to be distributed to and consumed by humans. This content is created and managed; then, it is published and delivered to end-users for consumption. Content management (CM), on the other hand, is some set of tools and processes (from content creation to consumption) that support the collection, structuring, managing, preserving, and publishing of information (content) in any form or type.

Some of these processes can include:

• Editing existing content
• Creating new content
• Creating categories
• Creating tags
• Assigning content to a category or tag
• Sorting content
• Creating permissions and roles
• Assign permissions and roles
• Defining content structures and workflow
• Version control
• Publishing content

The Big Four of Content Management

• Web Content Management (WCM): This is the management of content meant to be distributed as text, images, sounds, videos, or animations on websites.

• Enterprise Content Management (ECM): This is the management of business content not intended for distribution via websites (e.g. business and employee records).

• Digital Asset Management (DAM): This is the management of media files (images, audio, video).

• Records Management (RM): This is the management of transactional records from business operations consciously retained as evidence.

Introduction to Content Management Systems

According to Wikipedia, a content management system (CMS) manages the creation and modification of digital content. These systems support multiple users in a collaborative environment, allowing documents to be managed with different styles of governance and workflows.

A CMS usually allows multiple users to interact with content stored in a repository. This repository might be located on the same server powering the application or in a separate cloud storage service. Content editors can then edit existing content, create new content, perform some editorial processes on content, and make the processed content available for consumption by end-users.

Demo of the popular WordPress CMS

Components of a CMS

A content management system typically has two major components:

• Content management application (CMA): This is the user interface that allows an editor to add, modify, remove and manage content from a website.

• Content delivery application (CDA): This is the component that compiles the managed content and distributes it to the website or final front-end layer.

Introduction to Traditional CMS

Traditional content management systems are "coupled"; the content management application (CMA) and the content delivery application (CDA) come together in a single software application. Here, managing and delivering content to the front-end layer is done on one application, making it difficult for developers and content managers to work independently. The CMS's backend and database are tightly bound within the same system that delivers and presents content to the front-end layer.

Content is created, managed, and stored along with all digital assets on the site’s back-end while providing a content delivery layer on the frontend.

Introduction to Headless CMS

Traditional CMS mixes content with the front-end code (which is usually stack-specific), limiting the content to just the application upon which it is built. With the headless CMS, the front-end component of the CMS is decoupled from the application, content becomes independent, and you don't have to worry about how and where the content gets displayed but instead just storage, structuring, and delivery of the content.

The headless content management system is built as a content repository that makes structured content accessible via a RESTful API, GraphQL API, or the Git Workflow for display on any device while maintaining the speed, security, and scalability of the JAMstack architecture.

• You create and structure your content in the Headless CMS.

• You fetch data from your API endpoint to your website or application.

• You query your content to your website or applications

{
  products {
    id
    name
    date
    tags
    image {
      url
      fileName
    }
  }
}

• You can then render the fetched data in your website or application however you want and on several platforms.

Benefits of Headless CMS

Wondering why you should delve into headless content management systems? Here are some reasons:

• The content created in a headless CMS is "raw" and can be reused across multiple platforms, making it easier for you to scale your application and still satisfy all your users on all platforms.

• Content managers can work in their preferred choice of headless CMS, and developers can build with any front-end framework of their choice in their preferred programming language.

• Headless CMSs are cheaper to set up and easier to use with even less technical expertise after setup.

• A headless CMS promotes an agile way of working since content managers and developers can work independently and simultaneously, resulting in faster development.

• Headless CMS secures your content by providing it in high-performance CDN rather than directly from the database, thereby reducing the risk of distributed denial-of-service attacks (DDoS).

Categories of Headless CMS

You can find a comprehensive list of all Content Management Systems for Jamstack Sites here. However, headless CMSs are generally based on two categories described below.

Git-based Headless CMS

With a git-based CMS, you make and push changes to a git repository on a service like GitHub or GitLab. This service will then serve as your content delivery network, trigger a new build and update your website. Here are some of my favorites:

• Netlify CMS
• Publii
• Forestry
• Hexo Admin
• Jekyll Admin

API-driven Headless CMS

With an API-driven CMS, you manage your content on the CMS and deliver these contents to your application’s front-end with an intermediary API. Here are some of my favorites:

• Strapi
• Contentful
• Hygraph
• Cosmic
• Sanity

Conclusion

Content management is revolving, and there is an increasing demand for more flexible, scalable, and faster ways to deliver content with the right experience to the right user on the right platform. The future is headless!

You should consider checking out the slide of my recent talk: Optimizing Content Management with the Headless CMS.

Attributions

• Google
• Wikipedia
• Encyclopædia Britannica

Further Resources

• What Is A Headless CMS
• A List of Content Management Systems for Jamstack Sites
• Headless CMS explained in 5 minutes
• Headless CMS and SEO: Technical Best Practices

This week's challenge is the #MyFirstInterviewExperience where developers get to share their first interview experience and lessons learned from it. While this is my own story, I look forward to reading yours and hope developers preparing for interviews will learn from these stories.

The Beginning

My first interview experience was for an internship role at Upnepa NG, a company in Lagos, Nigeria. Upnepa is a data-driven platform that gives real-time (On/Off) information and total hours of electricity supply in selected areas, communities, and homes across Nigeria.

I saw the advert for the role of Web Developer Intern in October 2018 posted on Facebook by one of Upnepa's co-founders. As of then, Upnepa just got started and just joined an acceleration program in collaboration with Facebook and CCHUB at NG_HUB from Facebook.

I so much loved their mission to monitor, aggregate, and analyze power supply, power outages, and power distribution in order to improve productivity in young people and students, provide power supply rates insight for SMEs, and foresight for governmental institutions, energy distribution companies, and energy solution projects.

I prepared my resume and applied for the job. This was my first time applying for a job, I was very inexperienced and wasn't sure how it all works. I just kept calm and waited for whatever comes next 🧘🏾‍♂️.

The Interview

Eventually, I got an email that my application was accepted and it was interview time.

The interview was to evaluate my:

• Communication skill
• Personal Development
• Commitment
• Level of expertise in web development

I prepared, read tons of resources online around preparing for interviews and hoped I was ready for it. Fast forward to the interview day, I joined the call (I can't remember all the details now 😬) and answered tons of technical and non-technical questions alongside some test web projects.

After some more time and patiently waiting, I got another email after the interview.

Yayy, I got the job and was super excited! 🤩

Lessons Learned

• Build a killer brand for yourself. Check out Gift's guide on personal branding for developers.
• Prepare a good resume before applying. Here's a great guide for this.
• You don't need to "know it all", you just need to "know it and know-how and where to find more knowledge."
• Ensure you have good people-skills aside from technical skills.
• Do some research about the company before applying and interviewing.
• Get a good internet connection before joining the interview.
• Invest in quality webcams, microphones, or noise cancellation headphones.

Conclusion

Don't spend your entire life waiting for the best time making that move, write that article, build that side-project, apply for that job, or ask that question today. The best time is always now!

Join Hashnode's writing challenges like the #2Articles1Week and #MyFirstInterviewExperience to write, share knowledge, become a better writer, learn in public and win some Hashnode badges.

Here are some of my favorites:

In this article, I'll show you how to create a new GitHub repository and pin your special README file to your profile. That's it 🌚

Prerequisites

• A GitHub account
• Basic markdown knowledge
• Smile dear friend :)

STEP ONE

• Create a new ✨special✨ repository with your username. The special repository is case sensitive, ensure to use the same case as your account's username.

• Click on the checkbox: Initialize this repository with a README. This will create a README.md file inside your / repository.

STEP TWO

A README file contains information about other files in a directory or archive of computer software. A form of documentation, it is usually a simple plain text file called READ.ME, README.TXT, README.md, README.1ST – or simply README. The file's name is generally written in uppercase letters. ~ Wikepedia

Now you have the README.md file in your ✨special✨ repository, that's all you need. Edit the file as you deem fit (add images, text, tables, lists, embeds and anything else markdown supports). The README file will automatically appear on your public GitHub profile!

You also get a free template out of the box, cool right?

Here's my own finished profile page from the special repository:

Conclusion

The special repository is a great way to showcase and summarize yourself and work for potential opportunities and engagements. Get creative and showcase everything about yourself to your friends and GitHub stalkers.

Got your special repository live now? Drop a link to your GitHub account in the comments and let's see how amazing yours look. ✌🏾🙂