DEV Community: Bolaji Ayodeji

Creating an Automated Profile README using Nodejs and GitHub Actions

Bolaji Ayodeji — Mon, 26 Feb 2024 14:35:05 +0000

Some years ago, GitHub introduced the new Profile README feature that allowed GitHub users to pin a markdown file on their profile using a special repository named after their GitHub username. Since then, developers have used this file as a quick portfolio and for highlighting their achievements. I wrote an article shortly after the release to share how to set it up and highlight some cool profiles I had seen. This tutorial is a sequel to that article, and I will share how I took my GitHub profile to the next level with the power of scripting and CI/CD automation.

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:

Minute (0 - 59).
Hour (0 - 23).
Day of the month (1 - 31).
Month (1 - 12).
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!

Building an Ecommerce Store with Nextjs and Commerce Layer Demo Store

Bolaji Ayodeji — Sun, 22 Jan 2023 17:00:00 +0000

Have you ever wanted to learn how to build an ecommerce website as a developer? Look no further! In this article, I’ll walk you through the process of building a sleek, modern, and user-friendly conference swag digital store using composable commerce APIs, micro-frontends, and the Commerce Layer Nextjs Demo Store project. With the help of this powerful tool, you'll be able to create a visually appealing and functional international ecommerce website that is optimized for success. I'll show you step-by-step how to set up your store, add commerce data, and deploy your website in no time. Let’s get started!

Prerequisites

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

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

Add all the environment variables you currently have in .env.local to the deployment service you'll use to run the build.
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!

How to Build an International Ecommerce Website with Sanity and Commerce Layer

Bolaji Ayodeji — Mon, 11 Apr 2022 13:25:52 +0000

One of the greatest benefits of composable, headless commerce is the flexibility it introduces to the developer experience of building shopping experiences. Decoupling website content and commerce data makes it easier for content and commerce teams of experts to work independently and more efficiently. With Commerce Layer, content managers can work with a best-of-breed headless CMS like Sanity, merchants can build their inventory in Commerce Layer, and developers can build with any stack in their most preferred programming language while utilizing Commerce Layer’s APIs.

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:

The root for all frontend code
The /studio directory for all studio code.
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:

Create a free developer account here. If you already have an account, kindly skip to Step 3.
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).
Create a new organization for your business.
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.
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! 🖤

How to Connect Google Colab to a Local Runtime

Bolaji Ayodeji — Sun, 10 Apr 2022 01:56:55 +0000

Google Colaboratory lets you build "Colab notebooks" on the browser by blending Python executable code with rich text (along with images, HTML, and LaTeX). It is one of the simplest ways to work with Python notebooks, with no configuration required, easy collaboration, and free access to GPUs and TPUs. Unfortunately, while Colab provides access to GPUs, these resources are limited and will eventually run out. For a monthly fee, you can upgrade to Colab Pro or Colab Pro+, which gives you access to more GPUs and memory resources. However, if you're running a minimal collaboratory notebook, you can utilize the alternative option; connecting Google Colab to a local Jupyter runtime to use your local CPU and file storage. In this article, I'll show you how to set up a Jupyter notebook and everything you need to know about connecting to Colab.

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! 💙

How to Make any Website Shoppable with Commerce Layer

Bolaji Ayodeji — Wed, 16 Feb 2022 13:29:03 +0000

Digital commerce has changed, and there is an increasing demand for faster and highly efficient solutions across multiple interaction channels. The rise of headless commerce allows for more creative flexibility, better performance, and efficient software development. Developers can now make any website shoppable, serve customers on several platforms using the same code and content with no interruption to the customer journey using tools like Commerce Layer. As an API-first and stack agnostic platform, Commerce Layer provides commerce APIs for inventory, orders, shopping carts, prices, promotions, shipments, customers, and more. Ecommerce businesses can integrate Commerce Layer to manage the transactional part of their sales channel alongside any architecture or tool of their choice (be it WordPress, Drupal, Headless... anything!) and serve their storefront on multiple presentation layers (desktop, mobile, wearable devices, IoT, etc.).

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

Create a new folder somewhere on your computer.
Create an index.html file in the root directory.
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:

Create a free developer account here. If you already have an account, kindly skip to Step 3.
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).
Create a new organization for your business.
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.
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:

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

Install the seeder plugin using the command below:

commercelayer plugins:install seeder

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:

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.

How to Fix Git Always Asking for User Credentials

Bolaji Ayodeji — Wed, 25 Mar 2020 21:20:10 +0000

Have you ever encountered Git asking you for your username and password every time you try to interact with GitHub even after configuring it? Well, this is a very common problem among users who use the HTTPS clone URL for their repository. In this article, I'll show you how to fix this.

The https:// clone URLs are available on all public and private repositories. These URLs work everywhere, even if you are behind a firewall or proxy.

When you interact with a remote repository using HTTPS URLs on the command line, you'll be asked for your GitHub username and password, this sucks right?

Well using an HTTPS remote URL has some advantages: it's easier to set up than SSH :), and usually works through strict firewalls and proxies. However, it also prompts you to enter your GitHub user credentials every time you pull or push a repository :(.

You can fix this by configuring Git to store your password for you.

Here's how:

Update the URL of origin remote using SSH instead of HTTPS;

git remote set-url origin git@github.com:username/repo.git

Make Git store the username and password and it will never ask for them.

git config --global credential.helper store

Save the username and password for a session (cache it);

git config --global credential.helper cache

You can also set a timeout for the above setting

git config --global credential.helper 'cache --timeout=600'

Bingo, you just fixed it, Git will never ask for your credentials again.

Conclusion

However, due to security reasons, it is advisable that you use SSH to interact with GitHub, especially if you work for a company or you're using a computer that isn't yours.

Using the SSH protocol, you can connect to GitHub without supplying your username or password every time. Learn how to connect to GitHub with SSH here

Git first time setup

Bolaji Ayodeji — Tue, 23 Jul 2019 16:20:55 +0000

Git is a Free and Open Source Distributed Version Control System.

By far, Git is the most widely used modern version control system in the world today. Git is a distributed and actively maintained open source project originally developed in 2005 by Linus Torvalds, the famous creator of the Linux operating system kernel.

Unlike older centralized version control systems such as SVN and CVS, Git is distributed: every developer has the full history of their code repository locally. Git also works well on a wide range of operating systems and IDEs (Integrated Development Environments).

In this article, I'll show you how to install Git, set it up for the first time, useful tips and resources to learn more/ learn advanced git concepts. Let's roll!

I assume you already know what Version control is, if you don't, kindly check out this slide to learn more.

Here's a quick recap of what Version control means:
Version Control is:
the process of managing changes to source code or set of files over time.

Version control is the process of managing changes to source code or set of files over time.

Version control software keeps track of every modification to the code in a special kind of database.
If a mistake is made, developers can restore and compare earlier versions of the code to help fix the mistake while minimizing disruption to all team members or contributors.

Now that you know what Version Control and Git mean, let's install it.

For Mac OS:

Download Git for macOS
or install using Homebrew

brew install git

For Linux OS:

Download Git for Linux or
Install for Debian-based Linux systems

sudo apt-get update
sudo apt-get upgrade
sudo apt-get install git

or Install for Red Hat-based Linux systems

sudo yum upgrade
sudo yum install git

For Windows OS:

Download Git for Windows

Here's a more detailed installation guide for different systems on Git official docs

Now that you have Git on your system, let's set up the Git environment.

Git comes with a tool called git config that lets you get and set configuration variables that control all aspects of how Git looks and operates.

First set your identity, your name and email address like so:

git config --global user.name "bolajiayodeji"
git config --global user.email mailtobolaji@gmail.com

the --global option makes sure these values are used throughout your system

Next set up the default text editor you'll use whenever you need to enter a message in Git. This is not compulsory, if you don't configure this, Git will use your default editor. If you want to use something else, configure like so:

git config --global core.editor emacs

Next, set up colors for your Git console.

For Linux OS users, you can use third pary Zsh configurators like oh my zsh to customize your terminal look with themes :).
To configure this, do this:

git config --global color.ui true

The color.ui is a meta configuration that includes all the various color.* configurations available with git commands.

Now Git is ready for use.

Check your settings

git config --list

user.name=bolajiayodeji
user.email=mailtobolaji@gmail.com
color.ui=true

Want to learn some super Git commands?

I wrote an article: Git Cheat Sheet that covers some important Git commands you'll need.

Find more resources to learn Git here

Conclusion

Version control software is an essential part of the every-day of modern-day software developer practices. Once accustomed to the powerful benefits of version control systems, many developers wouldn’t consider working without it even for non-software projects.

Introduction to Web Accessibility

Bolaji Ayodeji — Tue, 07 May 2019 05:44:09 +0000

As developers, it’s easy to assume that all users can see and use a keyboard, mouse or screen, you feel everyone can interact with your web page the same way you do. This can lead to a user experience that works well for some people but creates issues for others :(

Many developers have only a little or blurred understanding of what
accessibility means, of course, accessibility can be a complex and difficult
topic but understanding it, its scope and its impact can make you a better and
inclusive web developer.

In this article, I’ll introduce you to accessibility, what it means, why you should care, a few tips, tools and resources to get you started.

Gif by Jona Dinges

What is Accessibility?

Let’s start by defining accessibility and inclusion.

According to thesaurus
dictionary, accessibility
simply means: easy to approach, reach, enter, speak with, or use.

Inclusion is a societal ideology regarding individuals with disabilities and
special education. I*nclusion* describes a group that’s particularly welcoming
to all kinds of people irrespective of their differences.

In computer-human interaction, accessibility simply means making the web
accessible and having functionalities that can be operated by literally everyone
including those with all forms of disabilities, limitations and conditions...

Those with Disabilities

According to WHO, there are about 285,000,000 people in the world today. Blind
and visually impaired make up of the 285,000,000 people according to the World
Health Organization (June
2012) with 39,000,000 categorized as legally blind and the remaining 246,000,000
visually impaired. The deaf and hearing impaired make up 275,000,000 (2004) in
the moderate-to-profound hearing impairment category.

Some forms of disabilities include:

Physical disabilities (One that affects a person’s mobility or dexterity)
Intellectual or Learning Disabilities ( People with an intellectual, learning, or cognitive disability have a reduced capacity to read, learn tasks or process information.)
Visual impairments (People with sight challenges, visually impaired individuals and blind people.)
Hearing impairments ( Deafness and hearing loss)
Neurological disabilities ( Disabilities associated with damage to the nervous system that results in the loss of some physical or mental functions.)

Those with limitations/ conditions

Disabilities can also be conditional.

A broken arm
A loud restaurant
Not speaking the local language e.t.c

All these are examples where someone may benefit from accessible practices.

Everybody is a keyboard user when they are eating with their mouse hand.

— Adrian Roselli

How can we help these people?

Web Accessibility comes to the rescue. It is a practice whereby web applications
are designed and developed so that its functionality can be operated by people
with disabilities.

Web Accessibility Guidelines

Throughout this article, I’ll refer to the Web Content Accessibility Guidelines
(WCAG) 2.0, a set of guidelines and best
practices put together by web accessibility experts to address what
“accessibility” means in a methodical way.

WCAG is organized around four principles often called The POUR Principle:

Perceivable Can users perceive the content? This ensures that our applications are perceivable with sight, touch or hearing senses via the browser or assistive technologies e.g Screen readers
Operable Can users use UI components easily and navigate the content? For example, something that requires a hover interaction cannot be operated by someone who can’t use a mouse or touch screen. This means users should be able to control your web apps elements using either the mouse, keyboard or an assistive device.
Understandable Can users understand the content? Can users understand the interface and is it clear and concise? This ensures an easy understanding and smooth user experience.
Robust Can the content be consumed by a wide variety of users on several browsers? This ensures compatibility of your app across several devices, browsers or operating systems.

Web accessibility tips

Now that you understand what Web Accessibility means and why you should care,
let me walk you through a few tips that would help you to build accessible
websites :)

Always add alternative texts to images

This is one thing most developers miss, I used to miss this too when I started
out because I didn’t really understand the essence of alternative texts.

Alternative texts (also known as alt) is a word that can be inserted as an attribute in an HTML document to tell your website, users, the contents of an image. The alt text appears in a blank box that would normally contain the image. Alt text is useful when an image is not available because of a broken link, changed URL or something else.

Alternative texts as the name imply serve as an alternative for screen readers.
They are read aloud to blind users on a screen reader and other screens
assistive technologies.

You add alternative texts to images with the alt attribute

<img src="./school.png" alt="a private school in Kogi State.">

Another important aspect of the alt attribute is that you should be specific
when adding these texts. For example, examine the images below:

Beautiful Aniekan Inyang

<img src="./lady.png" alt="a beautiful lady">

<img src="./lady.png" alt="a beautiful lady smiling in front of a brown door">

Which of the code above would support accessibility more, 1 or 2?

<img src="./dog.png" alt="a cute dog">

<img src="./dog.png" alt="a cute dog sitting beside a pillow on a gray couch">

Which of the code above would support accessibility more, 1 or 2?

Now you should understand the context of being specific when using alternative
texts. You might not see the need, you probably would not need it, but a whole
lot of users with disabilities need it.

Design your forms for Accessibility

Ensure you add <label> to your form elements though they might not be visible.
You can add labels for screen readers and still hide them from displaying to
other users.

<form action="./contact.php" method="POST">
  <label for="fullname">Full name</label>
  <input type="text" name="fullname" id="fullname">
  <label for="email">Email address</label>
  <input type="email" name="email" id="email">
  <label for="phone">Telephone</label>
  <input type="number" name="phone" id="phone">
</form>

Ensure that your for attribute matches the id

Always specify your web app language

<html lang="en-US"> // American english

 <html lang="en-UK"> // British english

 <html lang="fr"> // French

If your app supports multiple languages or translations, ensure to specify that
too.

Don’t use tables for anything except tabular data
Don’t auto-play video, music or other media files (Please avoid this)
Ensure that links are recognizable. Either underlined or with a different colour
Always provide a skip to main content option

Skipping to main content links are useful for users who use keyboard navigation
only

<body>
...
  <a href="#main">Get Started</a>
...
  <p>
   Our story is a story which explains another story. Cut the crap this is too long and I don't want to read it.
  </p>
...
  <main id="main">
    <!-- page specific content -->
   <p> Here's the main stuff bro </p>
  </main>
</body>

Reduce your divs and make use of semantic elements

HTML5 provides additional elements, such as <nav> , section and <aside>,
to better structure your content.

I’d stop here as we have tons of accessibility guidelines, but don’t worry, I’ve
included links for further reading below :)

The A11y project

This is a community-driven effort to make web accessibility easier with tons of
resources, events, patterns, checklists and lots more to help you build more
accessible applications. https://a11yproject.com/

Accessibility can be a complex and difficult topic. The Accessibility Project
understands this and wants to help make it easier to implement on the web.

Web accessibility tools

ally.css

This CSS file intends to warn developers about possible risks and mistakes that
exist in HTML code. It can also be used to roughly evaluate a site’s quality by
simply including it as an external stylesheet.

Get the Ally.css built by Gaël Poupard
here or download the equivalent web
extension (chrome, firefox and opera) Alix built by Ire
Aderinokun
here

Chrome lighthouse

Lighthouse is an open-source,
automated tool for improving the quality of web pages. You can run it against
any web page, public or requiring authentication. It has audits for performance,
accessibility, progressive web apps, and more. Read my previous article:
Introduction to chrome
lighthouse to get
started.

Contrast Checker

Check the contrast of your colour design for accessibility based on Web Content
Accessibility Guideline (WCAG). Check it here.

NoCoffee

A chrome extension which is helpful for understanding the problems faced by
people with slight to extreme vision problems. Download
here

A full list of web accessibility tools can be found

here

Resources

A full list of web accessibility resources can be found

here

Conclusion

Everyone should be able to access and enjoy the web irrespective of their
challenges or limitations. As developers, we’re building solutions for every
user and not just some users. As much as we focus on UI/UX, we should also
put extra focus on accessibility. Thanks for reading!

Like this article? Kindly follow me on twitter
@iambolajiayo

Introduction to JavaScript Switch Cases

Bolaji Ayodeji — Wed, 13 Mar 2019 05:38:46 +0000

In this short article, I will introduce you to JavaScript switch cases and how
to use them with practical examples.

PS: This article is not for those without any JavaScript knowledge, it is
expected that you're taking some tutorial or course and you just got to the
switch cases section.

This article will explain better with more practical examples to help you
understand switch cases in depth.

Prerequisites.

Basic JavaScript knowledge
Code editor
Web Browser
Your brain :)

A switch statement can basically replace multiple if checks in JavaScript.

It gives a more descriptive way to compare a value with multiple variants.

The Switch Syntax

The switch has one or more case blocks and an optional default case.

switch(x) {
  case 'value1':  // if (x === 'value1')
    //code here
    [break]

  case 'value2':  // if (x === 'value2')
    //code here
    [break]

  default:
    //code here
    [break]
}

The value of x is checked for strict equality to the value from the first case (that is, value1) then to the second (value2) and so on.
If the equality is found, switch starts to execute the code starting from the corresponding case, until the nearest break(or until the end of switch).
If no case is matched then the default code is executed (if it exists).

Some few real examples

Simple Play & Pause Switch

The switch statement can be used for multiple branches based on a number or
string:

switch (movie) {
  case 'play':
    playMovie();
    break;
  case 'pause':
    pauseMovie();
    break;
  default:
    doNothing();
}

If you don’t add a break statement, the execution will "fall through" to the
next level. It's essential that you deliberately label the fall through with a
comment if you really meant it to aid debugging:

switch (movie) {
  case 'play': // fallthrough
  case 'pause':
    pauseMovie();
    break;
  default:
    doNothing();
}

The default clause is optional. You can have expressions in both the switch part
and the cases if you like; comparisons take place between the two using the
=== operator:

switch (3 + 7) {
  case 5 + 5:
    correct();
    break;
  default:
    neverhappens();
}

Simple Maths Calc Switch

let average = 2 + 6;

switch (average) {
  case 4:
    alert( 'Too small' );
    break;
  case 8:
    alert( 'Exactly!' );
    break;
  case 10:
    alert( 'Too large' );
    break;
  default:
    alert( "Incorrect values!" );
}

Here the switch starts to compare averagefrom the first case variant that
is 4. The match fails.

Then 8. That’s a match, so the execution starts from case 8until the nearest
break.

If there is no break then the execution continues with the next
case without any checks.

Here is an example without break:

let average = 2 + 6;

switch (average) {
  case 4:
    alert( 'Too small' );
  case 8:
    alert( 'Exactly!' );
  case 10:
    alert( 'Too big' );
  default:
    alert( "Incorrect values!" );
}

In the example above we’ll see sequential execution of three alerts:

alert( 'Exactly!' );
alert( 'Too big' );
alert( "Incorrect values!" );

getDay() method switch case

The getDay() method returns the weekday as a number between 0 and 6.

(Sunday=0, Monday=1, Tuesday=2 , Wednesday=3, Thursday=4, Friday=5, Saturday=6)

This example uses the weekday number to calculate the weekday name:

switch (new Date().getDay()) {
  case 0:
    day = "Sunday";
    break;
  case 1:
    day = "Monday";
    break;
  case 2:
     day = "Tuesday";
    break;
  case 3:
    day = "Wednesday";
    break;
  case 4:
    day = "Thursday";
    break;
  case 5:
    day = "Friday";
    break;
  case 6:
    day = "Saturday";
}

The result of day will be the current weekday in day format

PS: This would change according to when you’re reading this article

I wrote this artcle on 01/04/2019 which is a Friday, so the result would be:

Friday

The default Keyword

The default keyword specifies the code to run if there is no case match,
more like an else statement:

switch (new Date().getDay()) {
  case 6:
    text = "Today is Saturday";
    break; 
  case 0:
    text = "Today is Sunday";
    break; 
  default: 
    text = "Its not weekend yet!";
}

The result of text will be:

Its not weekend yet!

The default case does not have to be the last case in a switch block:

switch (new Date().getDay()) {
  default: 
    text = "Its not weekend yet!";
    break;
  case 6:
    text = "Today is Saturday";
    break; 
  case 0:
    text = "Today is Sunday";
}

If default is not the last case in the switch block, remember to end the
default case with a break.

Conclusion

There are so many practical examples of switch cases, you can head
here to learn more about switch cases.

If this article helped you, show it by sharing!!

Thanks for reading!

You can follow me on twitter @iambolajiayo

Manipulating Arrays in JavaScript

Bolaji Ayodeji — Wed, 13 Mar 2019 05:35:28 +0000

Arrays have become an important part of any programming language. Most times we
need to do several operations on arrays, hence this article.

In this article, I would show you various methods of manipulating arrays in
JavaScript [^^]

What are Arrays in JavaScript?

Before we proceed, you need to understand what arrays really mean.

In JavaScript, an array is a variable that is used to store different data
types. It basically stores different elements in one box and can be later
assesssed with the variable.

Declaring an array:

let myBox = [];   // Initial Array declaration in JS

Arrays can contain multiple data types

let myBox = ['hello', 1, 2, 3, true, 'hi'];

Arrays can be manipulated by using several actions known as methods. Some of
these methods allow us to add, remove, modify and do lots more to arrays.

I would be showing you a few in this article, let’s roll :)

NB: I used Arrow functions in this post, If you don’t know what this means,
you should read
here.
Arrow function is an ES6 feature.

toString()

The JavaScript method toString() converts an array to a string separated by a
comma.

let colors = ['green', 'yellow', 'blue'];
colors.toString();

console.log(colors); // "green,yellow,blue"

join()

The JavaScript join() method combines all array elements into a string.

It is similar to toString() method, but here you can specify the separator
instead of the default comma.

let colors = ['green', 'yellow', 'blue'];
colors.join('-');

console.log(colors); // "green-yellow-blue"

concat

This method combines two arrays together or add more items to an array and then
return a new array.

let firstNumbers = [1, 2, 3];
let secondNumbers = [4, 5, 6];

let merged = firstNumbers.concat(secondNumbers);

console.log(merged); // [1, 2, 3, 4, 5, 6]

push()

This method adds items to the end of an array and changes the original
array.

let browsers = ['chrome', 'firefox', 'edge'];
browsers.push('safari', 'opera mini');

console.log(browsers); 
// ["chrome", "firefox", "edge", "safari", "opera mini"]

pop()

This method removes the last item of an array and returns it

let browsers = ['chrome', 'firefox', 'edge'];
browsers.pop(); // "edge"

console.log(browsers); // ["chrome", "firefox"]

shift()

This method removes the first item of an array and returns it

let browsers = ['chrome', 'firefox', 'edge'];
browsers.shift(); // "chrome"

console.log(browsers); // ["firefox", "edge"]

unshift()

This method adds an item(s) to the beginning of an array and changes the
original array.

let browsers = ['chrome', 'firefox', 'edge'];
browsers.unshift('safari');

console.log(browsers); //  ["safari", "chrome", "firefox", "edge"]

You can also add multiple items at once

splice()

This method changes an array, by adding, removing and inserting
elements.

The syntax is:

array.splice(index[, deleteCount, element1, ..., elementN])

Index here is the starting point for removing elements in the array
deleteCount is the number of elements to be deleted from that index
element1, …, elementN is the element(s) to be added

Removing items

after running splice(), it returns the array with the item(s) removed and
removes it from the original array.

let colors = ['green', 'yellow', 'blue', 'purple'];
colors.splice(0, 3);
console.log(colors); // ["purple"]
// deletes ["green", "yellow", "blue"]

NB: The deleteCount does not include the last index in range.

If the second parameter is not declared, every element starting from the given
index will be removed from the array:

let colors = ['green', 'yellow', 'blue', 'purple'];
colors.splice(3);
console.log(colors); // ["green", "yellow", "blue"]
// deletes ['purple']

In the next example we will remove 3 elements from the array and replace them
with more items:

let schedule = ['I', 'have', 'a', 'meeting', 'tommorrow'];
// removes 4 first elements and replace them with another
schedule.splice(0, 4, 'we', 'are', 'going', 'to', 'swim');
console.log(schedule); 
// ["we", "are", "going", "to", "swim", "tommorrow"]

Adding items

To add items, we need to set the deleteCount to zero

let schedule = ['I', 'have', 'a', 'meeting', 'with'];
// adds 3 new elements to the array
schedule.splice(5, 0, 'some', 'clients', 'tommorrow');
console.log(schedule); 
// ["I", "have", "a", "meeting", "with", "some", "clients", "tommorrow"]

slice()

This method is similar to splice() but very different. It returns subarrays
instead of substrings.

This method copies a given part of an array and returns that copied part as
a new array. It does not change the original array.

The syntax is:

array.slice(start, end)

Here’s a basic example:

let numbers = [1, 2, 3, 4]
numbers.slice(0, 3)
// returns [1, 2, 3]

console.log(numbers) // returns the original array

The best way to use slice() is to assign it to a new variable.

let message = 'congratulations'
const abbrv = message.slice(0, 7) + 's!'; 
console.log(abbrv) // returns "congrats!"

split()

This method is used for strings. It divides a string into substrings and
returns them as an array.

Here’s the syntax:

string.split(separator, limit);

The separator here defines how to split a string either by a comma.
The limit determines the number of splits to be carried out

let firstName = 'Bolaji';
// return the string as an array
firstName.split() // ["Bolaji"]

another example:

let firstName = 'hello, my name is bolaji, I am a dev.';
firstName.split(',', 2); // ["hello", " my name is bolaji"]

NB: If we declare an empty array, like this: firstName.split(''); then
each item in the string will be divided as substrings:

let firstName = 'Bolaji';
firstName.split('') // ["B", "o", "l", "a", "j", "i"]

indexOf()

This method looks for an item in an array and returns the index where it was
found else it returns -1

let fruits = ['apple', 'orange', false, 3]
fruits.indexOf('orange'); // returns 1
fruits.indexOf(3); // returns 3
friuts.indexOf(null); // returns -1 (not found)

lastIndexOf()

This method works the same way indexOf() does except that it works from
right to left. It returns the last index where the item was found

let fruits = ['apple', 'orange', false, 3, 'apple']
fruits.lastIndexOf('apple'); // returns 4

filter()

This method creates a new array if the items of an array pass a certain
condition.

The syntax is:

let results = array.filter(function(item, index, array) {
  // returns true if the item passes the filter
});

Example:

Checks users from Nigeria

const countryCode = ['+234', '+144', '+233', '+234'];
const nigerian = countryCode.filter( code => code === '+234');
console.log(nigerian); // ["+234", "+234"]

map()

This method creates a new array by manipulating the values in an array.

Example:

Displays usernames on a page. (Basic friend list display)

const userNames = ['tina', 'danny', 'mark', 'bolaji'];
const display = userNames.map(item => {
 '<li>' + item + '</li>';
})
const render = '<ul>' + display.join('') + '</ul>';

document.write(render);

another example:

// adds dollar sign to numbers
const numbers = [10, 3, 4, 6];
const dollars = numbers.map( number => '$' + number);
console.log(dollars);
// ['$10', '$3', '$4', '$6'];

reduce()

This method is good for calculating totals.

reduce() is used to calculate a single value based on an array.

The syntax is:

let value = array.reduce(function(previousValue, item, index, array) {
  // ...
}, initial);

example:

To loop through an array and sum all numbers in the array up, we can use the for
of loop.

const numbers = [100, 300, 500, 70];
let sum = 0;
for (let n of numbers) {
sum += n;
}
console.log(sum);

Here’s how to do same with reduce()

const numbers = [100, 300, 500, 70];
const sum = numbers.reduce((accummulator, value) =>
accummulator + value
, 0);

console.log(sum); // 970

If you omit the initial value, the total will by default start from the first
item in the array.

const numbers = [100, 300, 500, 70];
const sum = numbers.reduce((accummulator, value) => accummulator + value);

console.log(sum); // still returns 970

The snippet below shows how the reduce() method works with all four
arguments.

source: MDN Docs

More insights into the reduce() method and various ways of using it can be
found here and
here.

forEach()

This method is good for iterating through an array.

It applies a function on all items in an array

const colors = ['green', 'yellow', 'blue'];

colors.forEach((item, index) => console.log(index, item));
// returns the index and the every item in the array
// 0 "green"
// 1 "yellow"
// 2 "blue"

iteration can be done without passing the index argument

const colors = ['green', 'yellow', 'blue'];

colors.forEach((item) => console.log(item));
// returns every item in the array
// "green"
// "yellow"
// "blue"

every()

This method checks if all items in an array pass the specified condition and
return true if passed, else false.

check if all numbers are positive

const numbers = [1, -1, 2, 3];
let allPositive = numbers.every((value) => {
 value >= 0;
})

console.log(allPositive);

some()

This method checks if an item (one or more) in an array pass the specified
condition and return true if passed, else false.

c*hecks if at least one number is positive*

const numbers = [1, -1, 2, 3];

let atLeastOnePositive = numbers.some((value) => {
 value >= 0;
})
console.log(atLeastOnePositive);

includes()

This method checks if an array contains a certain item. It is similar to
.some(), but instead of looking for a specific condition to pass, it checks if
the array contains a specific item.

let users = ['paddy', 'zaddy', 'faddy', 'baddy'];
users.includes('baddy'); // returns true

If the item is not found, it returns false

There are more array methods, this is just a few of them. Also, there are tons
of other actions that can be performed on arrays, try checking MDN docs
here
for deeper insights.

Summary

toString() converts an array to a string separated by a comma.
join() combines all array elements into a string.
concat combines two arrays together or add more items to an array and then return a new array.
push() adds item(s) to the end of an array and changes the original array.
pop() removes the last item of an array and returns it
shift() removes the first item of an array and returns it
unshift() adds an item(s) to the beginning of an array and changes the original array.
splice() changes an array, by adding, removing and inserting elements.
slice() copies a given part of an array and returns that copied part as a new array. It does not change the original array.
split() divides a string into substrings and returns them as an array.
indexOf() looks for an item in an array and returns the index where it was found else it returns -1
lastIndexOf() looks for an item from right to left and returns the last index where the item was found.
filter() creates a new array if the items of an array pass a certain condition.
map() creates a new array by manipulating the values in an array.
reduce() calculates a single value based on an array.
forEach() iterates through an array, it applies a function on all items in an array
every() checks if all items in an array pass the specified condition and return true if passed, else false.
some() checks if an item (one or more) in an array pass the specified condition and return true if passed, else false.
includes() checks if an array contains a certain item.

Let’s wrap it here; Arrays are powerful and using methods to manipulate them
creates the Algorithms real-world applications use.

Let's do a create a small function, one that converts a post title into a
urlSlug.

URL slug is the exact address of a specific page or post on your site.

When you write an article on Medium or any other writing platform, your post
title is automatically converted to a slug with white spaces removed, characters
turned to lowercase and each word in the title separated by a hyphen.

Here’s a basic function that does that using some of the methods we learnt just
now.

const url = 'https://bolajiayodeji.com/'
const urlSlug = (postTitle, category) => {
let postUrl = postTitle.toLowerCase().split(' ');
let postSlug = `${url}` + category + '/' + postUrl.join('-');
return postSlug;
}
let postTitle = 'Introduction to Chrome Lighthouse'
let category = 'dt'
console.log(urlSlug(postTitle, category));

// https://bolajiayodeji.com/dt/introduction-to-chrome-lighthouse

in postUrl, we convert the string to lowercase then we use the split()
method to convert the string into substrings and returns it in an array

["introduction", "to", "chrome", "lighthouse"]

in post slug we join the returned array with a hyphen and then concatenate it
to the category string and main url.

let postSlug = `${url}` + category + '/' + postUrl.join('-');
postUrl.join('-') // introduction-to-chrome-lighthouse

That’s it, pretty simple, right? :)

If you’re just getting started with JavaScript, you should check this repository
here, I’m compiling a list
of basic JavaScript snippets ranging from

Arrays
Control flow
Dom
Functions
Objects
Operators

Thank you for reading, got any questions or views? Let's discuss in comments.

How to test a Pull Request locally before Merging.

Bolaji Ayodeji — Wed, 13 Mar 2019 05:33:46 +0000

In this article, I would show you how to check, test and make changes to a pull request before merging.

So your repository got a new Pull Request?, You don't want to merge it before testing it out yourself locally on your machine. How do you go about it?

The pull request is available on this git ref pull/{ID}/head which you can fetch using this, where ID is the pull request id.

REQUIREMENTS

Make sure you have a cloned version of the repository on your machine,
Check here to learn how to clone repositories from GitHub.
Have your cloned Repository integrated into your IDE
preferably Visual Studio Code [In this
tutorial, I used VsCode]
Be conversant with git commands
Go to your repository folder
Initialize git (you can do that by right-clicking in the root folder)
Ensure your work tree is clean (you can do that by running git status)
Run the following commands to FETCH the pull request from GitHub where ID is the pull request's ID

git fetch origin pull/ID/head && git checkout FETCH_HEAD

Or, if you only want to cherry pick it, instead of checking it out, you can use

git fetch origin pull/ID/head && git cherry-pick FETCH_HEAD

Open your IDE (VsCode) Your folder structure should change now pending on the contents of the PR.

What you have now is the contents of the pull requests and not your master
branch, run your checks and tests to determine if the pull request is worth merging.

At this point, you can do anything you want with this branch. You can run some local tests, or merge other branches into it, including master. Make modifications as you see fit!

Once satisfied git checkout master to return to the master branch.

You can also make changes to the pull request and push back to GitHub as a new commit or pull request.

After making your changes:

git add --all
git commit -m "Modified PR"
git push origin BRANCHNAME (e.g master or test)

That's it, you have tested the pull request and made changes!

If this article helped you, share!!!

How to convert GitHub Markdown files to a simple website

Bolaji Ayodeji — Wed, 13 Mar 2019 05:32:16 +0000

Introduction

This little guide demonstrates how to turn any Github
repository with a bunch of Markdown
files into a simple website using Github Pages and
Jekyll.

You don't need to use the command line or anything other than your browser.
It doesn't require any knowledge in Jekyll.
It's completely compatible with any bunch of markdown files you already have in any existing repository without any modification to those files. That includes the basic README.mdalmost all repositories contain.
The markdown files will remain just as readable and usable in Github than in your website.

Step by step instructions

Determine the repository where you want to activate GitHub Pages

You can of course create a new repository if you want.

Create the `_.config.yml` file

That file should be created on the root of your repository. Here is some content
to copy-paste in it:



plugins:
  - jekyll-relative-links
relative_links:
  enabled: true
  collections: true
include:
  - CONTRIBUTING.md
  - README.md
  - LICENSE.md
  - COPYING.md
  - CODE_OF_CONDUCT.md
  - CONTRIBUTING.md
  - ISSUE_TEMPLATE.md
  - PULL_REQUEST_TEMPLATE.md

It's basically just a few tuning of GitHub Pages default configuration to have
a better handling of Markdown files.

Activate GitHub Pages in your repository configuration

On the GitHub page of your project go into Settings > Options > Github Pages:

In the Source option, select master branch then Save:

You must also choose a theme:

That's it! Now you can just use the link provided by GitHub to access you
website:

Your site is published at https://bolajiayodeji.github.io/xxxxxx/

Usage guide

Any markdown file in your repository will display in your GitHub Pages website. You just have to use the same path to access it and replace the .md extension by .html.

So if you want to display your README.md file, you have to enter the URL as
README.html

To make links between your Markdown files just use a relative path to the other Markdown file. The configuration you copy pasted in your _config.yml provides a plugin to convert those URLs.

So your Markdown files will have correct links both in GitHub and GitHub Pages.

The index page of your website can be a index.md file or a README.md file. If both exists the index.md file has priority.
You should be able to use any GitHub Flavored Markdown.

Known differences between GitHub and GitHub Pages

No automatic links with GitHub Pages. The GitHub Markdown renderer can automatically detect a simple copy-pasted link and make it a clickable link. GitHub Pages doesn't propose a feature to reproduce that behaviour, so you'll have to braces your links with the []()syntax.