However, customization is pretty limited. We can only add some custom CSS hence changing the styles but that is about it. In this article, we go over the following:

1. Understanding how the @solana/wallet-adapter-react-ui package works

2. Using the @solana/wallet-adapter-react package to create a custom Connect Wallet page

You can check out the deployed version of what we are going to build here

Let's get started!

How does @solana/wallet-adapter-react-ui work?

If you go through the source code for the React UI package, then you will notice that it makes use of the useWallet hook from the @solana/wallet-adapter-react package. It also has the required components (buttons, modals, providers) and styling to be an easy-to-use library to implement a connect wallet feature.

The useWallet hook

The useWallet hook returns functions like select, connect, and disconnect to select a wallet, connect to the selected wallet, and disconnect from the connected wallet respectively. It also returns some variables - wallets which is a list of all wallets with their availability status, wallet which is the currently selected wallet, publicKey, connecting, connected, and disconnected telling us about the current connection status.

Using @solana/wallet-adapter-react to create a custom Connect Wallet UI

Let us start by creating a new Next.js project -

npx create-next-app solana-react-wallet-adapter-custom-ui-example --ts

It will ask you for some prompts, you can accept the defaults for this guide.

Now open up the project in your favorite IDE and open up the terminal. Then enter the following command to install the required dependencies -

npm i @solana/web3.js @solana/wallet-adapter-base @solana/wallet-adapter-react @solana/wallet-adapter-wallets

For this guide, I am going to be using Chakra UI for styling. To install the required dependencies for Chakra UI, run the following command -

npm i @chakra-ui/react @emotion/react @emotion/styled framer-motion

Now replace _app.tsx with the following -

import "@/styles/globals.css";
import type { AppProps } from "next/app";
import { ChakraProvider, extendTheme } from "@chakra-ui/react";
import {
  ConnectionProvider,
  WalletProvider,
} from "@solana/wallet-adapter-react";
import { useMemo } from "react";
import {
  GlowWalletAdapter,
  PhantomWalletAdapter,
  SolflareWalletAdapter,
  MathWalletAdapter,
} from "@solana/wallet-adapter-wallets";
import { clusterApiUrl } from "@solana/web3.js";

const theme = extendTheme({
  config: {
    initialColorMode: "dark",
  },
});

export default function App({ Component, pageProps }: AppProps) {
  const wallets = useMemo(
    () => [
      new PhantomWalletAdapter(),
      new SolflareWalletAdapter(),
      new GlowWalletAdapter(),
      new MathWalletAdapter(),
    ],
    []
  );

  const endpoint = useMemo(() => clusterApiUrl("mainnet-beta"), []);

  return (
    <ConnectionProvider endpoint={endpoint}>
      <ChakraProvider theme={theme}>
        <WalletProvider wallets={wallets} autoConnect>
          <Component {...pageProps} />
        </WalletProvider>
      </ChakraProvider>
    </ConnectionProvider>
  );
}

We are setting up the ConnectionProvider and WalletProvider from @solana/wallet-adapter-react with the default Solana mainnet RPC URL and 4 wallets - Phantom, Solflare, Glow and Math Wallet (this is to demonstrate how the wallets list includes the wallet availability status).

Now replace index.tsx with the following -

import { Container, Heading, VStack } from "@chakra-ui/react";
import { useWallet } from "@solana/wallet-adapter-react";

export default function Home() {
  const { wallets } = useWallet();

  console.log(wallets);

  return (
    <Container as="main" mt={32} maxW="3xl">
      <VStack w="full" gap={8}>
        <Heading textAlign="center">
          Solana React Wallet Adapter Custom UI demo with Chakra UI
        </Heading>
      </VStack>
    </Container>
  );
}

Run npm run dev and go to http://localhost:3000/ on your browser. Open up devtools and look at the console -

I have Backpack, Glow, Phantom, and Solflare installed so it shows up with a readyState of Installed. Note that Backpack, Glow and Phantom implement the Solana Wallet Adapter Standard and hence show up with StandardWalletAdapter for the adapter field. As I don't have Math Wallet, the readyState for Math Wallet is NotDetected.

Now make a components directory under src and make a Wallets.tsx file under that with the following code -

import { VStack, Button, Image, Text } from "@chakra-ui/react";
import { useWallet } from "@solana/wallet-adapter-react";

const Wallets = () => {
  const { select, wallets, publicKey, disconnect } = useWallet();

  return !publicKey ? (
    <VStack gap={4}>
      {wallets.filter((wallet) => wallet.readyState === "Installed").length >
      0 ? (
        wallets
          .filter((wallet) => wallet.readyState === "Installed")
          .map((wallet) => (
            <Button
              key={wallet.adapter.name}
              onClick={() => select(wallet.adapter.name)}
              w="64"
              size="lg"
              fontSize="md"
              leftIcon={
                <Image
                  src={wallet.adapter.icon}
                  alt={wallet.adapter.name}
                  h={6}
                  w={6}
                />
              }
            >
              {wallet.adapter.name}
            </Button>
          ))
      ) : (
        <Text>No wallet found. Please download a supported Solana wallet</Text>
      )}
    </VStack>
  ) : (
    <VStack gap={4}>
      <Text>{publicKey.toBase58()}</Text>
      <Button onClick={disconnect}>disconnect wallet</Button>
    </VStack>
  );
};

export default Wallets;

Now, replace index.tsx with the following -

import { Heading, VStack } from "@chakra-ui/react";
import dynamic from "next/dynamic";

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

export default function IndexPage() {
  return (
    <VStack gap={8} mt={16}>
      <Heading>Solana Custom Wallet UI example (Chakra UI)</Heading>

      <Wallets />
    </VStack>
  );
}

Notice that we have to import the Wallets component dynamically using next/dynamic or else you will be faced with a React hydration error.

The webpage should look like this now -

Note that it shows the wallets I have installed. You may have other wallets installed so it will show a different list. Notice how Math Wallet is not shown although I included the adapter. This is because we are filtering the wallets list making sure that readyState is Installed.

We can connect to a wallet simply by using the select method from useWallet. Note that select calls connect automatically. If the wallet is disconnected but a wallet is selected, we can call connect to connect to the currently selected wallet. The selected wallet state is persisted in the local storage. Note that calling disconnect removes the selected state as well but it is persisted between reloads and wallet locks.

Now if I click on any of these buttons, the wallet will pop up and ask me to connect. After connecting, the page should look like this -

Clicking "disconnect wallet" simply calls disconnect and the wallet is disconnected and the wallet state is removed from local storage.

Conclusion

This guide went through how @solana/wallet-adapter-react-ui and then went over how to create a Connect Wallet feature in your React application simply using @solana/wallet-adapter-react and Chakra UI.

Check out the GitHub Repository if you want to take a look at the final code for this guide. You can also check out the deployed version - https://solana-react-wallet-adapter-custom-ui-example.vercel.app/

Now you can try to extend this by creating a modal or a multi-button with a nice dropdown to disconnect or change the wallet just like how the official React UI package does it, but with your styles of course.

That is where CandyPay comes in. CandyPay lets you create NFTs with a no-code builder and also lets users easily claim them via Solana Pay on mobile without worrying about installing any browser extension or connecting their wallet.

Additionally, we are going to be looking at gasless NFTs which do not cost any SOL to the receiver to claim. Instead, we, the creator of the NFT pre-pay the gas. Note that we can get back our SOL if any of the pre-paid SOL remains unused.

Prerequisites

All of these don't require you to pay any real money.

• A Solana wallet with Solana pay support. You can use Phantom or Solflare, both of which are available for Android, iOS, and as a browser extension as well although you will need the mobile app for Solana pay.
• An image to upload as an NFT (you can use anything for this as we are going to be doing it on the devnet anyways). I am going to be using this one, feel free to use it for this tutorial -

• Some devnet SOL. You can get it from a Solana faucet (it is free and no signup is required)

Creating a Gasless NFT collection with CandyPay

First of all, we need to create a CandyPay account. Head over to the CandyPay web app and sign up for an account.

Next, select "Gasless Collection" under the "Create New" dropdown

Here, we have to provide some details about the NFT, and of course, the image itself. Here is an explanation of the various fields -

• NFT Name (required) - The name of the NFT
• NFT Description - You may want to add a description describing what the NFT is about, its importance, etc.
• Wallet Address - Your Solana wallet address
• Symbol - You can provide a symbol for your NFT. This is usually shown in marketplaces and wallet apps
• Royalty Fee - For any subsequent sales after the first one, this much percent of the amount will be given to you as royalty
• Collection size (required) - The number of NFTs the collection is going to have
• External URL - Any URL which you want to associate with your NFT
• Network - The Solana network you want to publish your collection to. When building a production app, you should choose "Mainnet" (and it will cost some real money in the form of real SOL to publish the collection and pre-pay the gas) but for the purpose of this tutorial, we are choosing "Devnet" (we are going to be using the devnet SOL we got from the faucet, which didn't cost us any real money)
• NFT Image (required) - The image that will be used for the NFT

I have entered the values for these fields as follows -

Now click on "Continue". In the next page, we can customize our CandyPay QR code. This will be the QR Code that the receiver of the NFT will scan in order to get the NFT, so let us try to make it beautiful :)

I have changed some of the shapes, and also changed the black CandyPay logo to one with the CandyPay accent color :)

Now again click "Continue". In the next step, we have to pay some SOL to create the collection as well as the gas for the 10 NFTs. Note that we can redeem any unused funds later on.

Scan this QR Code with your mobile wallet app and you should see a Solana Pay popup. If you see an error in Phantom which looks like this, try using Solflare (in Solflare, it is a 2 step process and the UI is a little different but the result is the same) -

After scanning the QR Code, you should see something like this on your mobile wallet app -

Pay the devnet SOL and let the transaction succeed (shouldn't take more than 10 seconds). After that, you should see a success message in CandyPay -

On the collection dashboard, you will be able to see the QR code one can scan to redeem the NFT. There is a link as well which one can open on their phone to redeem the NFT.

Oh, by the way, that QR code in the screenshot actually works so you can try to scan the QR code to get this NFT until supply lasts of course.

Claiming an NFT using the CandyPay QR Code

If I now scan the QR Code, I will be prompted to confirm a transaction but notice that no SOL is getting deducted from my side, so it is gasless! (I had to do it with Solflare this time as Phantom errored out)

Now if I go back to the dashboard, I can see that 1 NFT has been redeemed (ignore the cancelled ones as it was just Phantom being buggy). The gas has been deducted as well!

For more clarity on if I had to pay gas or not, if I check the transaction on Solscan, under the "SOL Balance Change" tab, I can see that there was no change in my SOL balance.

Conclusion

Now it's time for you to ship your gasless NFT collections! Feel free to share them down below, really excited to see what y'all build :)

Important Links

• CandyPay
• CandyPay Discord Server (you can get support here)
• Solana Pay

But, today we are going to look at 5 alternatives that accomplish the same task but are more feature-rich, faster, and cleaner. Coincidentally, these are all written in the rust programming language.

bat

bat is a popular alternative for the cat command, just with a ton of more features. So, what are they?

Syntax highlighting

bat automatically provides syntax highlighting for all major programming languages.

Line numbers

This might not be a big one but bat shows line numbers, and I have found it extremely useful.

Search

We can use / and then enter a query (can be regex) to perform a search operation. This is similar to how it is done in vim, and yes, it supports vim keybindings like n to go to the next result and N to go to the previous result.

zoxide

zoxide behaves like cd at first glance but it has 1 feature which makes it a game-changer. How cool would it be if you did not have to specify the path to a directory every time you wanted to change into it? Zoxide stores paths in a db, and the next time you use it, you can just specify the directory name instead of the full path. Here it is in action (z is the default alias for zoxide) -

You can also use the zi command to interactively select previous paths using fzf -

exa

exa is a modern replacement for the ls command but with more features. First of all, it supports colors and icons (I have aliased ls to exa --icons --color=always) -

This makes distinguishing folders and files extremely easy and the icons are just a great touch. Also, the list view (pass in the -l to see it in the list view) is way cleaner.

Exa also comes with a handy tree feature -

Here, -T is for displaying it as a tree. The --git-ignore flag ignores files and folders mentioned in the .gitignore ignore file.

fd

fd is an alternative to the find command packed with features and is also extremely fast.

The first argument is the term we want to search and any other arguments after that will be directories to search in.

We can also specify an extension with the -e flag -

ripgrep

ripgrep is an alternative to the grep command and the main highlight is its speed. It also automatically ignores files specified in ignore files like .gitignore and .ignore.

Yes, that took just 20 milliseconds!

Ripgrep comes with many other features too, like searching in specific file types and searching inside zips.

Here, we can specify the file type using the -t flag.

BONUS: tealdeer

tealdeer is an alternative to the tldr tool. Both accomplish the same task, that is, showing community-driven help/man pages which are easier to read and understand than the traditional, detailed ones. Here is an example for exa -

Tealdeer installs as tldr and hence tldr is the command and not tealdeer.

Conclusion

I hope you have found this article useful and that it helped boost your productivity. You can leave any suggestions via comments or you can dm them to me on Twitter :)

Well, what if I told you there are tools that can improve this significantly. We are going to be looking at 2 tools today, forgit and lazygit. Both of these tools let us do many of our day-to-day git tasks, interactively and come with a LOT of keyboard shortcuts.

Forgit

Forgit, a simple and lightweight wrapper around git commands which uses fzf to provide interactivity to git commands (and some more goodies :D).

For example, this is how the ga (git add equivalent) looks like -

YES, that is a diff view!

Oh and it is not limited to just staging files, there are many more interactive commands (each with its own alias :D )

Want to explore all the previous git commits? Run glo -

Want to see the list of branches and checkout to the appropriate one? Use gcb -

And there are more! For a full list, you can see the features section in the forgit README

Lazygit

Lazygit on the other hand is a TUI written in Go and is crazy powerful. This is how it looks like -

Yeah those are a lot of panes indeed. Files can be staged/unstaged easily by pressing Space and pressing c brings up a modal for writing a commit message -

Once you are done writing the commit message, press Enter and the changes get committed :D

Oh and we can see a log of everything we do as well as any command output -

And for all of us who hate using the mouse (although lazygit has mouse support), there are a TON of keyboard shortcuts -

You can see look at some more things it can do (like resolving merge conflicts and interactive rebasing) in the lazygit README.

Conclusion

So, which one should you use? This depends on your use case and how you want to use the tools.

I personally use the git CLI, forgit, lazygit, and the vscode source control panel depending on what I'm doing. I always use lazygit inside neovim but when I am using vscode, it is mostly forgit and the git CLI (I rarely use the source control pane).

Links

• Forgit
• Lazygit

What is RainbowKit?

RainbowKit is a React library that provides us with components to build a Connect Wallet UI in a few lines of code. It comes with support for many wallets, including Metamask, Rainbow, Coinbase Wallet, WalletConnect, and many more. It is also extremely customizable and comes with an amazing built-in theme.

RainbowKit uses Ethers.js and Wagmi, both popular libraries in this space, under the hood.

Also, it is developed by the same team behind the beautiful Rainbow Wallet

Creating a new Next.js App

Run the following command to create a new Next.js app (note that you can use it on a regular React app too) -

# With NPM
npx create-next-app rainbowkit-demo
# With yarn
yarn create next-app rainbowkit-demo

Now, move into the project directory and open it in your favorite code editor.

Adding RainbowKit to our React app

Run the following command to install RainbowKit and its peer dependencies -

# With NPM
npm install @rainbow-me/rainbowkit wagmi ethers
# With yarn
yarn add @rainbow-me/rainbowkit wagmi ethers

Now add the following code to pages/_app.js -

import "../styles/globals.css";

import "@rainbow-me/rainbowkit/styles.css";

import {
  apiProvider,
  configureChains,
  getDefaultWallets,
  RainbowKitProvider,
} from "@rainbow-me/rainbowkit";
import { chain, createClient, WagmiProvider } from "wagmi";

const { chains, provider } = configureChains(
  [
    chain.mainnet,
    chain.polygon,
    chain.goerli,
    chain.rinkeby,
    chain.polygonMumbai,
  ],
  [apiProvider.fallback()]
);

const { connectors } = getDefaultWallets({
  appName: "My RainbowKit App",
  chains,
});

const wagmiClient = createClient({
  autoConnect: true,
  connectors,
  provider,
});

function MyApp({ Component, pageProps }) {
  return (
    <WagmiProvider client={wagmiClient}>
      <RainbowKitProvider chains={chains}>
        <Component {...pageProps} />
      </RainbowKitProvider>
    </WagmiProvider>
  );
}

export default MyApp;

Firstly, we import the RainbowKit styles, the RainbowKitPovider and other functions to configure our chains, and the WagmiProvider.

Next, we configure the chains which we want to support. In this example, I have added the Ethereum Mainnet, Polygon Mainnet, Goerli and Rinkeby (both Ethereum test networks), and the Polygon Mumbai testnet. We are using the public fallback RPC URLs for the purpose of this demo for our API providers. RainbowKit also lets us specify our own JSON RPC URLs or Alchemy or Infura URLs for our API providers. You can see the API Providers documentation here.

Next, we create our wagmiClient, passing in the autoConnect and setting it to true. Our app will automatically reconnect to the last used connector this way.

At last, we wrap our application with WagmiProvider and RainbowKitProvider.

Next, let us add the Connect Wallet button to our app. Replace the code in pages/index.js with the following -

import { ConnectButton } from "@rainbow-me/rainbowkit";
import Head from "next/head";
import styles from "../styles/Home.module.css";

export default function Home() {
  return (
    <div className={styles.container}>
      <Head>
        <title>RainbowKit Demo</title>
        <meta
          name="description"
          content="Demo app part of a tutorial on adding RainbowKit to a React application"
        />
        <link rel="icon" href="/favicon.ico" />
      </Head>

      <main className={styles.main}>
        <h1 className={styles.title} style={{ marginBottom: "4rem" }}>
          Welcome to this demo of{" "}
          <a href="https://www.rainbowkit.com/">RainbowKit</a>
        </h1>

        <ConnectButton />
      </main>
    </div>
  );
}

Now run npm run dev or yarn dev and open up localhost:3000 in your browser and you should see this -

Making it dark mode 🌑

Time to make sure our eyes don't burn anymore.

Head over to pages/_app.js and import the midnightTheme function from RainbowKit. (Alternatively, you can also import the darkTheme function, a dimmer version of midnight)

import {
  apiProvider,
  configureChains,
  getDefaultWallets,
  midnightTheme,
  RainbowKitProvider,
} from "@rainbow-me/rainbowkit";

We must also pass in our theme to RainbowKitProvider -

<RainbowKitProvider chains={chains} theme={midnightTheme()}>

RainbowKit supports more advanced theming, you can see the RainbowKit Theming docs here for more information.

Also, add this small piece of code to styles/globals.css to make our app dark mode too -

body {
  background-color: #010101;
  color: #f0f0f0;
}

Now our app should look like this -

A tour of RainbowKit

After authenticating with a wallet, our connect button will automatically change to a network switcher which also show us our balance and wallet address -

Switching the network is as easy as clicking the network switcher and then selecting the network we want to switch to -

Clicking on our wallet address gives us a modal with the option to copy our address or disconnect our wallet -

Cool Mode 😎

Let's make our application a little cooler :) Just add the coolMode prop to RainbowKitProvider -

<RainbowKitProvider chains={chains} theme={midnightTheme()} coolMode>

Now if we click on any of the options in the connect modal, we will get some amazing confetti 🎊

Conclusion

That was a basic demo of what RainbowKit can do, but it can do a lot more like show recent transactions. The best place to learn more about it is RainbowKit docs.

Important Links

• Source Code
• Deployed Preview
• RainbowKit
• RainbowKit GitHub

Thankfully, the React ecosystem is huge and there are many great people who have made amazing libraries to help us with this problem. Today, we are going to focus on React component libraries that are accessible, have a decent base style, have good docs, and come with components like Modals, Popovers, Tooltips, etc.

1. Chakra UI

When I started out with Next.js, Chakra UI was the first component library I ever used, and it was amazing! I was able to make quite complex UIs (with modals and tables and everything) in not much time and that helped me focus on other things like application logic. It is the perfect one to use for Hackathons! It also has a huge community and is extremely popular.

2. Next UI

Next UI is probably the most beautiful out of all 5 in this article. Although it is quite new and still in the beta stage, it comes with all the essentials and looks absolutely amazing out of the box! It also comes with some amazing transitions and animations out of the box, that other component libraries don't come with.

3. MUI

MUI also has been around for a long time and was called Material UI. It is based on Material Design by Google but also comes with an extensive level of customization. Moreover, MUI also provides an unstyled version and a package with some amazing CSS utilities. MUI also provides a set of advanced components under MUI X. Some of these components are free but some require a paid license.

4. Mantine

Mantine also comes with a lot of components and a decent out-of-the-box UI. It is a lot like Chakra UI but has a smaller community. It, however, also comes with some amazing packages like a notification center, a command bar, a rich text editor and much more!

5. React Daisy UI

Daisy UI is an amazing Tailwind CSS component library. React Daisy UI is React component library for Daisy UI. It comes with a huge number of themes out of the box and a lot of components as well. As it is based on Tailwind CSS and comes with it, it is extremely easy to customize it with Tailwind CSS.

Conclusion

Now those were 5 React component libraries that will help you speed up development. Do let me know if you have any other favorites or which one you liked the most of these 5!

What is LQIP?

LQIP simply stands for Low Quality Image Placeholders. They have extremely small file sizes and act as placeholders for the actual image while the actual image is still loading. These extremely small file sizes are obtained by blurring the image, resizing it to a smaller size, or reducing the quality in the case of JPEGs.

Compatibility

WebP is supported by all modern browsers. Also, WebP support is present in Safari on macOS only if one is using macOS 11 (Big Sur) or later. source

If 100% compatibility is the goal, we can use JPEG LQIPs as well (they are almost 2-3 times the size of a WebP image).

Let us now look at how we can use lqip-modern with Next.js

Using LQIP Modern with Next.js

Next.js has an in-built next/image component which can provide preview images for local files without the use of an external library, but it cannot for remote images.

Now, there is also a limitation with our approach here, that is, preview images are created at build time. This means, that if the external image changes, then the preview image will not change.

However, this method will be especially useful if you are fetching the image from a CMS. If the image is ever updated, a build can be triggered which will create a new preview image. A better approach would be to use on-demand Incremental Static Regeneration or regular incremental static regeneration, however, that is out of the scope of this article. You can read my blog post on implementing on-demand incremental static regeneration with Directus to learn more.

In this example, we are going to look at creating preview images for an image from Unsplash. I am going to be using this awesome image of a Vercel mug along with some computer peripherals for this tutorial. However, you can choose any picture you like.

Firstly, let us create a new Next.js application -

npx create-next-app next-lqip-demo
# OR
yarn create next-app next-lqip-demo

After it has been created, open up the project in your favorite code editor.

Now, open up the pages/index.js file and replace it with the following code -

import Head from "next/head";
import Image from "next/image";
import styles from "../styles/Home.module.css";

export default function Home() {
  return (
    <div className={styles.container}>
      <Head>
        <title>LQIP demo with Next.js</title>
        <meta name="description" content="Generated by create next app" />
        <link rel="icon" href="/favicon.ico" />
      </Head>

      <main className={styles.main}>
        <h1 className={styles.title}>
          Welcome to{" "}
          <a href="https://nextjs.org">this demo of LQIP with Next.js!</a>
        </h1>

        <div style={{ marginTop: "4rem" }}>
          <Image
            src="https://images.unsplash.com/photo-1642083139428-9ee5fa423c46"
            alt="Vercel mug with computer peripherals"
            height={480}
            width={320}
          />
        </div>
      </main>
    </div>
  );
}

Also, replace the code inside next.config.js with the following -

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  images: {
    domains: ["images.unsplash.com"],
  },
};

module.exports = nextConfig;

We are using the next/image component to show our image from Unsplash. As the image is from a remote URL, we have to also add the domain in next.config.js.

Now run npm run dev or yarn dev to start a development server and then visit localhost:3000. You will be able to see the page heading with the image -

When you first visited the page, you would have noticed the image took a split of a second to load. Depending on your internet connection, it can be fast or slow. If you have a fast internet connection, open up developer tools and go to the network tab. Here you can throttle your internet connection to simulate a slow loading time -

Using LQIP to optimize our remote image

Firstly, let us install lqip-modern, and sharp. Sharp is an awesome package that helps with image transformations and is used by lqip-modern -

npm install --save lqip-modern sharp
# OR
yarn add lqip-modern sharp

Now, replace the code in pages/index.js with the following -

import lqipModern from "lqip-modern";
import Head from "next/head";
import Image from "next/image";
import styles from "../styles/Home.module.css";

export default function Home({ imageUrl, previewImageUrl }) {
  return (
    <div className={styles.container}>
      <Head>
        <title>LQIP demo with Next.js</title>
        <meta name="description" content="Generated by create next app" />
        <link rel="icon" href="/favicon.ico" />
      </Head>

      <main className={styles.main}>
        <h1 className={styles.title}>
          Welcome to{" "}
          <a href="https://nextjs.org">this demo of LQIP with Next.js!</a>
        </h1>

        <div style={{ marginTop: "4rem" }}>
          <Image
            src={imageUrl}
            alt="Vercel mug with computer peripherals"
            height={480}
            width={320}
            placeholder="blur"
            blurDataURL={previewImageUrl}
          />
        </div>
      </main>
    </div>
  );
}

export const getStaticProps = async () => {
  const unsplashImageUrl =
    "https://images.unsplash.com/photo-1642083139428-9ee5fa423c46";
  const image = await fetch(unsplashImageUrl);
  const imageBuffer = Buffer.from(await image.arrayBuffer());
  const previewImage = await lqipModern(imageBuffer);

  return {
    props: {
      imageUrl: unsplashImageUrl,
      previewImageUrl: previewImage.metadata.dataURIBase64,
    },
  };
};

In getStaticProps, we first fetch the image and convert it to a Buffer. We then give lqip-modern our buffer and it returns us an object called previewImage which contains a buffer and some metadata. Inside the metadata, there is a field called dataURIBase64 which is a base64 URL for our preview image. We pass this in via props to our client-side application.

On the client-side, we have added a new placeholder="blur" parameter to our Image component that will show a blur placeholder. As it is a remote image, we are required to pass in the blurDataURL parameter. We pass in the base64 URL for our preview image we obtained from the metadata earlier, here.

Now if you reload the page, while the image is loading, you should see the preview image.

For those wondering, this is the image lqip-modern made us -

It is tiny at just 11x16 (the next/image component makes it fill the width and height of the original image) and is just 78 bytes!

Using JPEG instead of WebP

If you want to support all browsers, you can add the outputFormat option when making the preview image to get a JPEG preview image, like this -

  const previewImage = await lqipModern(imageBuffer, { outputFormat: "jpeg" });

The JPEG image is the same dimensions as our WebP image but significantly larger in size at 303 bytes -

Note that these file sizes will vary depending on what image you use. The difference in file size between JPEG and WebP can go under double in some cases.

Conclusion

Alright, that is it! Let us go over what we did in this tutorial -

• Learned about LQIP images
• Created a Next.js application and added an image from Unsplash
• Used lqip-modern to create preview images
• Looked at how we can obtain JPEG preview images

Hope you liked this tutorial! Do share it if you have found it useful :)

Important Links

• LQIP Modern
• GitHub Repository with code
• Deployed example

Demo -

Note that incremental static regeneration will be referred to as ISR from now on

Why On-Demand ISR over regular ISR?

Next.js supports ISR for a few years now but on-demand ISR makes it better. Before, we would specify a revalidate property with the number of seconds to cache the data. This had a few disadvantages -

• The cache would be invalidated regularly even if the data in the server had not changed. This would also result in unnecessary API calls.
• Often, the content served would be stale.

On-demand ISR solves both the aforementioned problems with regular ISR. This is done by triggering a cache revalidation via webhooks. So whenever the content is updated on the server (or CMS), a webhook event can be fired which will create or update the required static pages

Setting up a Directus project

Although Directus can be self-hosted, it has a cloud offering with a decent free tier. Go ahead and sign up for an account if you haven't already. Click "Create Project" in the dashboard (you might be prompted to create one during the onboarding process) and give your project a name. Under "Infrastructure", select "Community Cloud" and under "Starting Template", select "Empty Project". Now click "Create Project" and within 2 minutes, it should be created.

After the project has been created, click on it on the dashboard and then click "Open Project". Here, on the login screen, enter the credentials that have been sent to the email address associated with your Directus account.

Setting up our Blog collection

On, Directus, it should say that there are no collections. Let us create a collection called "Blog". Click on the arrow in the top-right corner and check "Status", "Created on" and "Updated On". We will add more fields later on. Now click on the checkmark and we should be able to see our collection's schema -

Let us add a few more fields. Create one called with the type "Input" and give it the key "title". Make it required and hit save.

Add one more field with the type "Markdown" and give it the key "content". Make this required too and hit save.

We need to also add a slug for our blog posts. Create a new field with the "Input" type with key "slug" and make it required. Now click "Continue in Advanced Field Creation Mode". Under "Interface" check the "Slugify" option and click the checkmark to create the field.

Adding some sample data

Adding content in Directus is extremely easy! Go to the content tab in the sidebar (the first one with a 3d box icon) and select the Blog collection. Now click "Create Item". Here add a title and some content and a slug. Also, make sure to change the status to "Published". We will later use this status to manage API access. Note that you can use markdown here. After you are done adding the content, click the checkmark to save it.

Setting up permissions for our API

Go to the settings tab on the sidebar and then click on "Roles & Permissions" in the settings navigation. Next, click on "Public" -

Here we can see our Blog collection. Click on the red not allowed sign under the eye (this denotes view permission). In the dropdown, select "Use Custom".

Unser "Item Permissions", add the following rule allowing public view access to only published items -

Under "Field Permissions", select all and click on the checkmark to save the permissions.

Creating a blog with Next.js and Directus

Let us start by creating a new Next.js app -

npx create-next-app nextjs-directus-on-demand-isr
# OR
yarn create next-app nextjs-directus-on-demand-isr

After it has been created, open the project in your favorite code editor.

Next, install the Directus JS SDK -

npm install @directus/sdk
# OR
yarn add @directus/sdk

Now, make a file called lib/directus.js and add the following code -

import { Directus } from "@directus/sdk";

const directus = new Directus(process.env.DIRECTUS_URL);

export default directus;

Here, we are initializing the SDK with the URL to our Directus backend. We must set this URL as an environment variable. Go ahead and create a new file called .env.local and add the environment variable -

DIRECTUS_URL=<PATH_TO_YOUR_DIRECTUS_INSTANCE_WITHOUT_ANY_OF_THE_PATHS>

Make sure to appropriately replace the URL with the one for your instance.

Now, open the pages/index.js file and replace it with the following code -

import Head from "next/head";
import Link from "next/link";
import directus from "../lib/directus";

import styles from "../styles/Home.module.css";

export default function Home({ posts }) {
  return (
    <div className={styles.container}>
      <Head>
        <title>Create Next App</title>
        <meta name="description" content="Generated by create next app" />
        <link rel="icon" href="/favicon.ico" />
      </Head>

      <main className={styles.main}>
        <h1 className={styles.title}>
          Welcome to A demo of Next.js with Directus
        </h1>

        <div className={styles.grid}>
          {posts.map((post) => (
            <Link key={post.id} href={post.slug} passHref>
              <a className={styles.card}>
                <h2>{post.title}</h2>
              </a>
            </Link>
          ))}
        </div>
      </main>
    </div>
  );
}

export const getStaticProps = async () => {
  const res = await directus.items("blog").readByQuery({
    limit: -1,
    fields: ["title", "slug", "id"],
  });

  return {
    props: {
      posts: res.data,
    },
  };
};

Here, we are fetching all the blog posts but only the title, slug, and id fields. We do this in getStaticProps and pass the data as a prop to the client. Hence, the fetching is done on the server environment, only at build time. (note that in a development environment, getStaticProps runs on every request)

Later on in the article, we are going to be looking at on-demand ISR that will run getStaticProps when a webhook is triggered.

Once you run yarn dev and open up https://localhost:3000 on your web browser, you should be able to see your blog posts -

Now, if we click on the blog post cards, it will lead us to a 404 as we haven't set up our blog post pages yet. Let us do that now.

Create a new file pages/[slug].js and add the following code -

import directus from "../lib/directus";
import styles from "../styles/BlogPost.module.css";

const BlogPage = ({ post }) => {
  return (
    <div className={styles.container}>
      <h1>{post.title}</h1>
      <p>{post.content}</p>
    </div>
  );
};

export const getStaticProps = async ({ params }) => {
  const res = await directus.items("blog").readByQuery({
    filter: { slug: params.slug },
    fields: ["title", "content"],
  });

  return {
    props: {
      post: res.data[0],
    },
  };
};

export const getStaticPaths = async () => {
  const res = await directus.items("blog").readByQuery({
    limit: -1,
    fields: ["slug"],
  });

  return {
    paths: res.data.map((post) => ({
      params: {
        slug: post.slug,
      },
    })),
    fallback: false,
  };
};

export default BlogPage;

Here, in getStaticPaths, we are fetching only the slug for all blog posts. Then we are mapping over it and create an array of params to let Next.js know the paths that exist. Lastly, we set fallback to false so that any path not in the paths array redirects to a 404.

In getStaticProps we do a query where we filter by the slug field. We also specifically ask for only the title and content fields.

Lastly, we pass the data in through props and render it on the client-side.

Also, we can add some CSS for this page. Create a new file called styles/BlogPost.module.css and add the following to it -

.container {
  padding: 0 2rem;
}

.main {
  min-height: 100vh;
  padding: 4rem 0;
  flex: 1;
  display: flex;
  flex-direction: column;
  justify-content: center;
  align-items: center;
}

Now if we see our blog post page, we see that the content is rendering as a string and is not getting parsed as markdown -

Let's fix this

Rendering MDX for content

Although MDX supports more advanced features like the ability to render React components, we are not going to be looking at that in this article. However, let us focus on parsing the markdown and rendering the necessary HTML.

We are going to be using next-mdx-remote for this tutorial. Let us install it -

npm install next-mdx-remote
# OR
yarn add next-mdx-remote

Now, replace the code in pages/[slug].js with the following -

import { serialize } from "next-mdx-remote/serialize";
import { MDXRemote } from "next-mdx-remote";

import directus from "../lib/directus";
import styles from "../styles/BlogPost.module.css";

const BlogPage = ({ post }) => {
  return (
    <div className={styles.container}>
      <h1>{post.title}</h1>
      <MDXRemote {...post.content} />
    </div>
  );
};

export const getStaticProps = async ({ params }) => {
  const res = await directus.items("blog").readByQuery({
    filter: { slug: params.slug },
    fields: ["title", "content"],
  });

  return {
    props: {
      post: {
        title: res.data[0].title,
        content: await serialize(res.data[0].content),
      },
    },
  };
};

export const getStaticPaths = async () => {
  const res = await directus.items("blog").readByQuery({
    limit: -1,
    fields: ["slug"],
  });

  return {
    paths: res.data.map((post) => ({
      params: {
        slug: post.slug,
      },
    })),
    fallback: false,
  };
};

export default BlogPage;

Now, if we navigate to a blog post, we can see the rendered markdown -

Using Next.js On-demand ISR with Directus

If we build the Next.js application and serve a production build and then make changes in Directus, they will not reflect in our website unless we re-build it. Here we got 3 options -

• Trigger a new build every time content is added/updated/deleted
• Use regular ISR with a specified time for which the cache should be retained
• Use on-demand ISR to only re-build that specific page only when it is needed

With the first option, it can be expensive and time-consuming. Re-building also invalidates the cache for all pages in many cases. This might cause issues when you are dealing with larger websites.

With the second option, there will be unnecessary API calls to our server and data might be stale.

This leaves us with the third option. Although setting it up is slightly more complicated than the other 2 methods, it does not have any of the downsides the other 2 methods have. And, I am going to show you how exactly to set it up so it shouldn't be very hard :)

Note: Currently the website is hosted locally but Directus needs a publicly accessible URL as a webhook. You can either host it somewhere and then test it out or start a local tunnel using something like Ngrok

Create a new file under pages/api/revalidate.js and add the following code -

import directus from "../../lib/directus";

const handler = async (req, res) => {
  const { collection } = req.body;
  const headers = req.headers;

  if (!headers["x-webhook-secret"]) {
    return res.status(403).send("Forbidden");
  }

  const receivedSecret = headers["x-webhook-secret"];

  const secret = process.env.REVALIDATE_SECRET;

  if (receivedSecret !== secret) {
    return res.status(403).send("Forbidden");
  }

  if (collection === "blog") {
    const { keys } = req.body;

    for (const key of keys) {
      const directusRes = await directus
        .items(collection)
        .readOne(key, { fields: ["slug"] });

      await res.unstable_revalidate(`/${directusRes.slug}`);
      await res.unstable_revalidate("/");
    }
  }

  return res.status(200).send("Success");
};

export default handler;

This is a simple Next.js API route.

First, we check for the x-webhook-secret header and compare it to a preset webhook secret, set as an environment variable. We should always use a webhook secret to prevent spam. It can also be a security risk in some cases (but here it is not as we are not relying on data sent as an event payload for input).

Directus sends us some event payload and we are destructuring the collection field which contains the name of the collection where the change was made. We check if this is the blog collection and then go ahead with revalidating the pages. Although this does not make much sense here, if our pages had multiple sets of pages that could be revalidated, we could specifically just revalidate a set of pages instead of all sets of pages. (for example, if there was a landing and then a blog page, for changes to the landing collection, we could just revalidate the landing page but for changes to the blog page, we could revalidate only the specific blog page and the blog index).

Now, the event payload does not contain the slug for the blog post but it has the id. We use the Directus SDK to get the slug corresponding to that id and then revalidate that slug page and the home page (as it has the blog index).

Lastly, open up the .env.local file and add the REVALIDATE_SECRET environment variable. For the value, it can be a random string. The easiest way would be to use the output of the following command -

openssl rand -base64 32

To test this out, we cannot use the development environment as getStaticProps runs every time a request is made on the development environment. Either build the site with npm run build or yarn build, serve it locally with npm run start or yarn start, and then use a local tunneling solution like Ngrok or else, deploy it to a hosting platform like Vercel.

Now head over to your Directus instance and go to the settings tab. Now click on "Webhooks" in the side navigation and create a new one. Give it a name and for the URL field, add your Ngrok URL or your hosted instance. Make sure that the slug is /api/revalidate. The URL should look like https://<my-domain>/api/revalidate. Make sure the status is set to active and the "Send Event Data" checkbox is checked.

Now, add a header called x-webhook-secret with the value of the secret you created earlier and set it as an environment variable. Under "Triggers", check all the actions and the blog collection. Now click the checkmark to save it. Here is what it looks like for me -

Conclusion

That has been quite a lot! Let us go over the things we did -

• First, we create a project in Directus and created a schema for our blog posts
• We created a Next.js application and added the Directus SDK
• We displayed our blog posts on the home page and the post with content on its own page
• We used next-mdx-remote to render markdown
• We used Next.js on-demand ISR to revalidate the cache whenever required

Hope you liked this tutorial! Do share it if you have found it useful and you can follow me on Twitter too :)

See you on my next blog 🤞

Important Links

• GitHub Repo with all the code
• Hosted Demo
• Directus
• Next.js on-demand ISR

XdoX is a web application that lets you start challenges and log your progress every day. You are also able to show your progress to the world via your unique profile page. These challenges can be anything from 100DaysOfCode to 30DaysOfRust to even 60DaysOfCooking!

It is also my submission for the Hasura x Hashnode Hackathon

Live Demo / GitHub Repository

❓ What is Hasura?

GraphQL is a query language for APIs with a schema. It comes with multiple features like the ability to query specific fields, do pagination, do aggregation queries, and a lot more.

However, making a GraphQL backend is more complicated than making a simple REST backend and that is where Hasura comes in. Hasura provides us with an easy way to make a GraphQL backend that connects our database with our application without the need to write a single line of code!

Hasura also has a cloud offering with a decent free tier so that we can get started with hosting our GaphQL backend without needing to worry about costs. It is Open Source and Self-Hostable as well.

📚 The Tech Stack

What all technologies did I use for XdoX?

For starters, I used Hasura for my application's backend.

Other than that, I used the following services -

• Clerk to add authentication to my application. It also integrated well with Hasura and I was able to secure my backend by using JWT Auth (more on this later on in this article)

• Heroku Postgres for my database. It also integrated well with Hasura

• Vercel to host my frontend

And, here are the libraries and frameworks I used for the application -

• Next.js for my application's frontend
• TailwindCSS for styling my frontend
• Radix UI for un-styled UI components like Modals and Popovers
• Headless UI for transitions
• Apollo React Client for making GraphQL requests from my frontend. It also takes care of caching.
• Tiptap for the rich-text editor with markdown support that is used to log progress

🧐 How does XdoX work?

It is a simple 3-step process. One signs up for an account using Google or Email and then starts a challenge (e.g. 100DaysOfCode). Then one logs their progress every day.

Next, one can share their unique profile page to the world to show off their progress.

Also, it is not necessary to log your progress every day. The app is built in such a way that lets you be flexible with your challenges. Gone on a vacation? No problem, XdoX won't bug out for not logging your progress.

Securing the backend

Backends have direct access to the database and it is considered a best practice to secure them. I need to use the GraphQL API from my front-end and hence it has to be a public API. However, I must secure it so that only limited unauthorized requests and authorized requests can be made.

As I was using Clerk for user authentication, it didn't take me long to implement this. Clerk integrated with Hasura using JWT templates. Here is the documentation explaining how to implement this.

Here, we create a JWT template from the Clerk dashboard. Here is what mine looks like -

When making a request to the API, we pass in a header called Authorization with a bearer token as the value. This is verified by Hasura using a signing key (this is set in Hasura via environment variables).

This is the code in the frontend that takes care of passing in the bearer token when making requests -

import {
  ApolloClient,
  ApolloProvider,
  from,
  HttpLink,
  InMemoryCache,
} from "@apollo/client";
import { setContext } from "@apollo/client/link/context";
import { useSession } from "@clerk/clerk-react";
import { ReactNode } from "react";

const hasuraGraphqlApi = process.env.NEXT_PUBLIC_HASURA_GRAPHQL_API;

interface IApolloProviderWrapperProps {
  children: ReactNode;
}

export const ApolloProviderWrapper = ({
  children,
}: IApolloProviderWrapperProps) => {
  const { getToken } = useSession();
  const authMiddleware = setContext(async (_, { headers }) => {
    const token = await getToken({ template: "hasura" });

    return {
      headers: {
        ...headers,
        authorization: `Bearer ${token}`,
      },
    };
  });

  const httpLink = new HttpLink({
    uri: hasuraGraphqlApi,
  });

  const apolloClient = new ApolloClient({
    link: from([authMiddleware, httpLink]),
    cache: new InMemoryCache(),
  });

  return <ApolloProvider client={apolloClient}>{children}</ApolloProvider>;
};

We simply get a bearer token by using the getToken function made available to us by the Clerk React SDK and pass it in the Authorization header.

Now, if the bearer token is valid, the X-Hasura-User-Id header is added to the request that contains the user id of the user who is making the request. The headers for the user role are passed in as well. Note that this is taken care of on Hasura's side.

I am also making some unauthenticated requests with a viewer role. This has been set as the unauthorized role in my Hasura instance and is used in the public user profile pages. Here is the code that take cares of making an unauthenticated requests -

import {
  ApolloClient,
  ApolloProvider,
  from,
  HttpLink,
  InMemoryCache,
} from "@apollo/client";
import { setContext } from "@apollo/client/link/context";
import { ReactNode } from "react";

const hasuraGraphqlApi = process.env.NEXT_PUBLIC_HASURA_GRAPHQL_API;

interface IApolloProviderWrapperProps {
  children: ReactNode;
}

export const UnauthenticatedApolloProviderWrapper = ({
  children,
}: IApolloProviderWrapperProps) => {
  const authMiddleware = setContext(async (_, { headers }) => {
    return {
      headers: {
        ...headers,
        "X-Hasura-User-Role": "viewer",
      },
    };
  });

  const httpLink = new HttpLink({
    uri: hasuraGraphqlApi,
  });

  const apolloClient = new ApolloClient({
    link: from([authMiddleware, httpLink]),
    cache: new InMemoryCache(),
  });

  return <ApolloProvider client={apolloClient}>{children}</ApolloProvider>;
};

Setting row-level permissions for the data

Although the API is now secured, no data is accessible by default. We need to set up permissions and this will also let us limit the data one can access. For example, we will let a user only access their own user data and only access private challenges they have created.

Thankfully, Hasura again makes doing this extremely easy. Let us look at an example -

Here, I have setup insert permissions for the user role in such a way that one can insert rows only where the user_id column is equal to the user id of the user making the request (this was passed in as a header).

I am also allowing the user to only update specific columns. Here, the id column is auto-generated with the gen_random_uuid() PostgreSQL function. The created_at and updated_at fields are also being taken care of by the backend.

I am also adding a column preset for the user_id column that will be equal to the X-Hasura-User-Id header. Now, that is crazy powerful!

Similarly, I have set permissions for update, select and delete for the user role where I check that the user_id column matches the X-Hasura-User-Id header.

For the viewer role, I have set it up this way -

Here, the viewer is only able to select rows from the database (that is, only read data). I have additionally added a check that makes sure that the challenge is public.

👓 What I learned from this Hackathon

Although I have used GraphQL in the past, my experience was quite limited. Also, I had never built a GraphQL backend, I was just using public GraphQL APIs. I had also never used Hasura before, nor did I ever use a SQL database for any production project.

This hackathon gave me a chance to explore the backend side of GraphQL through Hasura and understand the deeper concepts. I also had a great time using a PostgreSQL database, learning more about relational data. It is crazy powerful!

✨ Conclusion

Over the past month, I have worked on XdoX and have been exploring and learning a LOT of new things. I'm quite excited to see how XdoX does in the real world!

Bye, and have a nice day 😁🤞

🔗 Important Links

• XdoX
• XdoX GitHub Repository
• My profile on XdoX

Note: Although I am going to be talking about keyboard shortcuts specific to Chrome, they should remain the same across all Chromium-based browsers (Brave, Edge, Vivaldi, etc.)

Moving between tabs

Clicking tabs can be quite a painful and slow process, especially, if you switch between them frequently. Keyboard shortcuts greatly speed things up here.

Ctrl + Tab (for Windows) and ⌘ + ⌥ + → (for macOS) lets you move to the next tab.

Edit: Ctrl + Tab works on macOS too, kudos to Dhruva Srinivas for pointing it out

Bonus: We can also move to the previous tab with Ctrl + Shift + Tab (for Windows) and ⌘ + ⌥ + ← (for macOS)

Re-opening closed tabs

We tend to close tabs by mistake but there is a simple keyboard shortcut that can re-open the last closed tab -

Ctrl + Shift + t (for Windows) and ⌘ + Shift + t (for macOS) lets you re-open recently closed tabs in the order they were closed in.

Bonus: If you close a whole window, the above keyboard shortcut will re-open the whole window with all the tabs.

Searching through open tabs

As the number of tabs open gets larger and larger, it gets difficult to find a tab. Fortunately, from Chrome 87 onwards, we can search through all open tabs, as well as recently closed tabs.

Ctrl + Shift + a (for Windows) and ⌘ + Shift + a (for macOS) opens the tab search dialog.

Close the current tab

After we are done with using a web page on a tab, it is a good idea to close it so that it doesn't clutter our tab bar and keeps the resource usage low.

Ctrl + w (for Windows) and ⌘ + w (for macOS) closes the current tab.

Bonus: Ctrl + Shift + w (for Windows) and ⌘ + Shift + w (for macOS) closes the current window.

Open a new tab or a window

Ctrl + t (for Windows) and ⌘ + t (for macOS) opens a new tab and jumps to it.

Similarly, Ctrl + n (for Windows) and ⌘ + n (for macOS) opens a new window and jumps to it.

All Chrome Keyboard Shortcuts - https://support.google.com/chrome/answer/157179?hl=en&co=GENIE.Platform%3DDesktop

Conclusion

I hope you have found this small article helpful and now you can be more productive while browsing the web. See you in the next one 🤞

Today, we are going to look at a library called Code Hike that provides exceptional features on markdown code blocks. These includes focussing code, adding filenames and displaying them as tabs, annotations, linking text to code, and much more! It also has in-built support for syntax highlighting 🤩

Let us look at adding Code Hike to a Next.js application. Do note that although MDX is supported by a number of frameworks like Vue, Svelte, etc, Code Hike only works with React.

Live Demo / GitHub Repository

Setting up Code Hike in a Next.js application

First of all, let us create a new Next.js application -

npx create-next-app code-hike-example
# OR
yarn create next-app code-hike-example

Now, open up the project in your favorite text editor.

Setting up MDX

Next, we need to add MDX to our Next.js application. For this, we are going to be following the official guide on adding MDX to a Next.js application.

Do note that Code Hike also works with Next MDX Remote and MDX Bundler however, we are going to look at a simple example with the official MDX plugin for Next.js.

First of all, let us install the required packages -

npm install @next/mdx @mdx-js/loader
# OR
yarn add @next/mdx @mdx-js/loader

Now, open up next.config.js and replace it with the following code -

const withMDX = require("@next/mdx")({
  extension: /\.mdx?$/,
  options: {
    remarkPlugins: [],
    rehypePlugins: [],
  },
});

module.exports = withMDX({
  pageExtensions: ["ts", "tsx", "js", "jsx", "md", "mdx"],
})

We are simply telling our bundler to treat .md and .mdx files as pages as well when they are in the pages directory. This also takes care of compiling our MDX.

Now, let us setup Code Hike

Setting up Code Hike

First of all, let us install the Code Hike Package

npm install @code-hike/mdx@next
# OR
yarn add @code-hike/mdx@next

Now, we must add Code Hike as a Remark plugin. Remark is a simple markdown processor that has a huge ecosystem of plugins.

const { remarkCodeHike } = require("@code-hike/mdx");

const withMDX = require("@next/mdx")({
  extension: /\.mdx?$/,
  options: {
    remarkPlugins: [[remarkCodeHike]],
    rehypePlugins: [],
  },
});

module.exports = withMDX({
  pageExtensions: ["ts", "tsx", "js", "jsx", "md", "mdx"],
});

Code Hike uses Shiki under the hood to provide syntax highlighting. We can find a list of all the supported themes here. Let us go with Monokai for this tutorial.

const { remarkCodeHike } = require("@code-hike/mdx");
const theme = require("shiki/themes/monokai.json");

const withMDX = require("@next/mdx")({
  extension: /\.mdx?$/,
  options: {
    remarkPlugins: [[remarkCodeHike, { theme }]],
    rehypePlugins: [],
  },
});

module.exports = withMDX({
  pageExtensions: ["ts", "tsx", "js", "jsx", "md", "mdx"],
});

There is one last thing to do. We need to add the Code Hike CSS to our application. Open up _app.js and add this one line of code to the top

import "@code-hike/mdx/dist/index.css"

Testing out Code Hike

Let us make a new file called code-hike.mdx under the pages directory. Add the following mdx markup in there -

# Just testing out [Code Hike](https://codehike.org/)

Some normal `markdown`

## Annotation Example
```js index.js box=1[25:39]
console.log("Some code. I am annotated!")
```

## Focus Example
```js next.config.js focus=1:2,7
const { remarkCodeHike } = require("@code-hike/mdx");
const theme = require("shiki/themes/monokai.json");

const withMDX = require("@next/mdx")({
  extension: /\.mdx?$/,
  options: {
    remarkPlugins: [[remarkCodeHike, { theme }]],
    rehypePlugins: [],
  },
});

module.exports = withMDX({
  pageExtensions: ["ts", "tsx", "js", "jsx", "md", "mdx"],
});
```

<CH.Section>

## Code Links Example

We are looking at the [console.log](focus://console.js#2) function today

<CH.Code>
```js console.js
console.table(["Hello", "World"])
console.log("Hello World")
```
</CH.Code>

</CH.Section>

Here, we are writing some basic markdown at first and then adding 3 code blocks. In all 3 of them, I have provided a filename just after specifying the language (js in these 3 cases).

In the first code block, we pass in the box attribute after the filename. We set it to 1[25:39] where 1 indicated the line number and 25:39 indicates the range of characters to annotate on that line.

Similarly, in the second code block, we pass in the focus attribute and set it to 1:2,7. Here 1:2 indicates a range of lines to be put on focus. We also add line 7 by adding it as a comma-separated value.

For the third code block, we have to wrap the content and code block in the CH.Section tag. We must also wrap the code block in the CH.Code tag. This is so that Code Hike knows which file we are going to be referring to through the code links when we specify the filename.

We have console.log as a code link here that points to focus://console.js#2. This indicates that whenever we hover over that code link, it will focus the second line in the console.js code block.

At last, this is what it should look like when we navigate to /code-hike

Yes, those box shadows are cool 👀

Conclusion

That was a brief overview of Code Hike. Code Hike supports many more things like Scrollycoding and previews as well. Code Hike is still in a beta stage and many features are still experimental.

Hope everything went well so far and now you can use Code Hike in your blog or documentation to achieve extremely powerful code blocks!

See you in the next one 😁🤞

🔗 Important Links

• Code Hike
• Code Hike GitHub Repository
• GitHub Repository for this tutorial
• Deployed Preview for this tutorial

🍞 Ok, what is a Breadcrumb Navigation?

You must have come across navigation bars, something like this -

The first example is from the Vercel dashboard and the second one is from the Netlify dashboard.

We can see that it gives us a brief idea of what page we are on and also lets us navigate back easily (yes, those breadcrumb items are usually links).

At times, these Breadcrumb Links also have an associated dropdown, something like this -

We will not be building this today as it is a more advanced use case, however, in larger projects, it will be a useful thing to have as it makes navigation easier.

Initializing a NextJS application with TailwindCSS

First of all, let us create a new NextJS application

npx create-next-app breadcrumb-example
# OR
yarn create next-app breadcrumb-example

Now, let us remove some of the boilerplate code and existing CSS (except the global.css file) as we are going to be adding TailwindCSS.

A cleaned up pages/index.js will look like this -

import Head from "next/head";

export default function Home() {
  return (
    <div>
      <Head>
        <title>NextJS Breadcrumb Example</title>
        <meta
          name="description"
          content="A simple example application for a NextJS Breadcrumb tutorial"
        />
        <link rel="icon" href="/favicon.ico" />
      </Head>

      <main>
        <h1>Breadcrumb Navigation Example with NextJS</h1>
      </main>
    </div>
  );
}

Also, delete Home.module.css under the styles directory.

Adding TailwindCSS

We are going to be simply following the office guide on adding TailwindCSS to a NextJS application.

First of all, let us install TailwindCSS, PostCSS, and AutoPrefixer -

npm install -D tailwindcss postcss autoprefixer
# OR
yarn add -D tailwindcss postcss autoprefixer

Also, run the following command to generate the tailwind.config.js and postcss.config.js files -

npx tailwindcss init -p

Now, replace the tailwind.config.js file with the following -

module.exports = {
  content: [
    "./pages/**/*.{js,ts,jsx,tsx}",
    "./components/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

Now, add the following code to the globals.css file under the styles directory -

@tailwind base;
@tailwind components;
@tailwind utilities;

For this example, I am going to go for a dark mode version, just so that the screenshots I take are easy on the eyes. For this, I will add this to my globals.css file -

@layer base {
  body {
    @apply bg-black text-white;
  }
}

I am also going to add some styles to the h1 tag we added earlier in the index.js file -

<h1 className="mx-8 md:mx-16 lg:mx-32 mt-32 text-2xl md:text-3xl lg:text-4xl">
    Breadcrumb Navigation Example with NextJS
</h1>

This is what the website looks like now -

Building the Breadcrumb Navigation

Time for the fun part, let us build the breadcrumb navigation!

Let us make a new directory called components. This is where we will be putting in our Breadcrumb and BreadcrumbItem components.

Now, let us make the Breadcrumb. Create a file called Breadcrumb.jsx and add the following code -

import { Children } from "react";
import { Fragment } from "react/cjs/react.production.min";

const Breadcrumb = ({ children }) => {
  const childrenArray = Children.toArray(children);

  console.log(childrenArray);

  const childrenWtihSeperator = childrenArray.map((child, index) => {
    if (index !== childrenArray.length - 1) {
      return (
        <Fragment key={index}>
          {child}
          <span>/</span>
        </Fragment>
      );
    }
    return child
  });

  return (
    <nav className="mx-8 md:mx-16 lg:mx-32 mt-8">
      <ol className="flex items-center space-x-4">{childrenWtihSeperator}</ol>
    </nav>
  );
};

export default Breadcrumb;

Let us go over this code step by step. First of all, we make a new component called Breadcrumb. We are accepting one prop, that is the children. These children will include the Breadcrumb Items, that is the links to the pages.

We then convert the children into an array using the Children.toArray() function.

If we log the childrenArray variable to the console, we should see something like this -

Here, we can see that it contains all the metadata about the component such as the props, component type, etc.

Next, we take this array and map over it. We check if it is the last element of the array by comparing the index of the element with the length of the array. If it is not the last element, we return it as a React Fragment with the child element itself, as well as a separator (/ in this case as it is the most common one but you can change it as well). If it is the last element of the array, we just return the element, without the separator.

Next, the Breadcrumb component returns a nav element with an order list (ol). The ordered list is a flexbox and the space-x-4 class adds a margin of 1 rem between all children elements (the breadcrumb items in this case).

Lastly, we export the component to be used later.

Now, let us create another file called BreadcrumbItem.jsx and add the following code to it -

import Link from "next/link";

const BreadcrumbItem = ({ children, href, ...props }) => {
  return (
    <li {...props}>
      <Link href={href} passHref>
        <a>{children}</a>
      </Link>
    </li>
  );
};

export default BreadcrumbItem;

Here, we are creating a new component called BreadcrumbItem which takes in a children and a href prop. We also take in additional props which will be passed into the li prop. Do note that each BreadcrumbItem is a list item and hence it fits in the ordered list we created earlier in the Breadcrumb component.

Time to add the Breadcrumb to our application. For the time being, let us add the following code to our index.js file under pages -

<Breadcrumb>
    <BreadcrumbItem href="/">Home</BreadcrumbItem>
    <BreadcrumbItem href="/">Home</BreadcrumbItem>
</Breadcrumb>

Also, don't forget the imports

import Breadcrumb from "../components/Breadcrumb";
import BreadcrumbItem from "../components/BreadcrumbItem";

This is what the home page should look like now -

Right now, we are rendering the breadcrumb on the home page and hardcoding the page names. However, this is not what we should be doing, let us look at a better approach where the routes are inferred using the router component.

Dynamically creating the breadcrumb items

Till now, we were manually passing in the breadcrumb items into the Breadcrumb component. However, this approach is not suitable for larger applications.

I have made some changes to the _app.js file to dynamically create the breadcrumb items -

import { useRouter } from "next/router";
import { useEffect, useState } from "react";
import "../styles/globals.css";
import Breadcrumb from "../components/Breadcrumb";
import BreadcrumbItem from "../components/BreadcrumbItem";

function MyApp({ Component, pageProps }) {
  const router = useRouter();
  const [breadcrumbs, setBreadcrumbs] = useState();

  useEffect(() => {
    const pathWithoutQuery = router.asPath.split("?")[0];
    let pathArray = pathWithoutQuery.split("/");
    pathArray.shift();

    pathArray = pathArray.filter((path) => path !== "");

    const breadcrumbs = pathArray.map((path, index) => {
      const href = "/" + pathArray.slice(0, index + 1).join("/");
      return {
        href,
        label: path.charAt(0).toUpperCase() + path.slice(1),
      };
    });

    setBreadcrumbs(breadcrumbs);
  }, [router.asPath]);

  return (
    <>
      <Breadcrumb>
        <BreadcrumbItem href="/">Home</BreadcrumbItem>
        {breadcrumbs &&
          breadcrumbs.map((breadcrumb) => (
            <BreadcrumbItem key={breadcrumb.href} href={breadcrumb.href}>
              {breadcrumb.label}
            </BreadcrumbItem>
          ))}
      </Breadcrumb>
      <Component {...pageProps} />
    </>
  );
}

export default MyApp;

Let us go through this code. First of all, we are importing the NextJS router, the useEffect hook, the useState hook, the Breadcrumb component and the BreadcrumbItem component. Also, you can remove the Breadcrumb component from the index.js file.

Then, inside the MyApp component, we are initializing the router and creating a state to store out breadcrumbs. Next, we have an useEffect hook which fires when the page loads and whenever router.asPath changes.

In the useEffect hook, firstly, we remove the query parameters from our path (which we get from router.asPath). Next, we split it into an array called pathArray and call the shift() function on it to remove the first element (which is the home route).

Next, we also filter it out so that we don't get any other blank path (this is because the NextJS router returns a blank element at the last index if we are on the home route).

After that, we map over it and generate a new array called breadcrumbs. The breadcrumbs array is an array of objects that contain the href and label for the breadcrumb items.

Lastly, we save it to the breadcrumbs state so that we can use it outside the useEffect hook.

Next, in the JSX, we add the Breadcrumb component and add a BreadcrumbItem for the home route to it.

Then, we make sure that the breadcrumbs array is not null and map over it, adding the other BreadcrumbItem components.

Now, to test it out, create a directory called dashboard under pages and add 2 files - index.js and [id].js.

Add the following code to index.js -

import Head from "next/head";

const Dashboard = () => {
  return (
    <div>
      <Head>
        <title>Dashboard | NextJS Breadcrumb Example</title>
        <meta
          name="description"
          content="A simple example application for a NextJS Breadcrumb tutorial"
        />
        <link rel="icon" href="/favicon.ico" />
      </Head>

      <main>
        <h1 className="mx-8 md:mx-16 lg:mx-32 mt-32 text-2xl md:text-3xl lg:text-4xl">
          Breadcrumb Navigation Example with NextJS - Dashboard Page
        </h1>
      </main>
    </div>
  );
};

export default Dashboard;

Now, add the following code to [id].js -

import Head from "next/head";

const Project = () => {
  return (
    <div>
      <Head>
        <title>Dynamic Route | NextJS Breadcrumb Example</title>
        <meta
          name="description"
          content="A simple example application for a NextJS Breadcrumb tutorial"
        />
        <link rel="icon" href="/favicon.ico" />
      </Head>

      <main>
        <h1 className="mx-8 md:mx-16 lg:mx-32 mt-32 text-2xl md:text-3xl lg:text-4xl">
          Breadcrumb Navigation Example with NextJS - Dynamic Route Page
        </h1>
      </main>
    </div>
  );
};

export default Project;

Now, let us head over to /dashboard

We can see that the breadcrumb works properly and the links work too!

Now let us head over to /dashboard/test and we can see that the breadcrumb displays the dynamic route -

Making it accessible

First of all, let us add an aria-label of value breadcrumb to our Breadcrumb component -

import { Children } from "react";
import { Fragment } from "react";

const Breadcrumb = ({ children }) => {
  const childrenArray = Children.toArray(children);

  const childrenWtihSeperator = childrenArray.map((child, index) => {
    if (index !== childrenArray.length - 1) {
      return (
        <Fragment key={index}>
          {child}
          <span>/</span>
        </Fragment>
      );
    }
    return child;
  });

  return (
    <nav className="mx-8 md:mx-16 lg:mx-32 mt-8" aria-label="breadcrumb">
      <ol className="flex items-center space-x-4">{childrenWtihSeperator}</ol>
    </nav>
  );
};

export default Breadcrumb;

Now, let us make a small change to our _app.js to pass in a prop to the BreadcrumbItem called isCurrent with a boolean value. The value is true for the last breadcrumb item, that is, the current page.

import { useRouter } from "next/router";
import { useEffect, useState } from "react";
import "../styles/globals.css";
import Breadcrumb from "../components/Breadcrumb";
import BreadcrumbItem from "../components/BreadcrumbItem";

function MyApp({ Component, pageProps }) {
  const router = useRouter();
  const [breadcrumbs, setBreadcrumbs] = useState();

  useEffect(() => {
    const pathWithoutQuery = router.asPath.split("?")[0];
    let pathArray = pathWithoutQuery.split("/");
    pathArray.shift();

    pathArray = pathArray.filter((path) => path !== "");

    const breadcrumbs = pathArray.map((path, index) => {
      const href = "/" + pathArray.slice(0, index + 1).join("/");
      return {
        href,
        label: path.charAt(0).toUpperCase() + path.slice(1),
        isCurrent: index === pathArray.length - 1,
      };
    });

    setBreadcrumbs(breadcrumbs);
  }, [router.asPath]);

  return (
    <>
      <Breadcrumb>
        <BreadcrumbItem isCurrent={router.pathname === "/"} href="/">
          Home
        </BreadcrumbItem>
        {breadcrumbs &&
          breadcrumbs.map((breadcrumb) => (
            <BreadcrumbItem
              key={breadcrumb.href}
              href={breadcrumb.href}
              isCurrent={breadcrumb.isCurrent}
            >
              {breadcrumb.label}
            </BreadcrumbItem>
          ))}
      </Breadcrumb>
      <Component {...pageProps} />
    </>
  );
}

export default MyApp;

For the initial home route, we are simply matching router.pathname with /.

Now in the BreadcrumbItem.jsx file, change the code to the following -

import Link from "next/link";

const BreadcrumbItem = ({ children, href, isCurrent, ...props }) => {
  return (
    <li {...props}>
      <Link href={href} passHref>
        <a
          className={isCurrent && "text-blue-500"}
          aria-current={isCurrent ? "page" : "false"}
        >
          {children}
        </a>
      </Link>
    </li>
  );
};

export default BreadcrumbItem;

Here, we are setting aria-current to page if it is the current route.

Conclusion

I hope you have a working Breadcrumb navigation now. Feel free to experiment with it and have a nice day 😁🤞

🔗 Important Links

• Deployed Preview
• GitHub Repository with the code

🤔 What is Notiger?

Notiger is a tool for developers that allows one to fire events from their applications. These events are stored in a database and can be accessed at any time. Also, if one enables notifications, they will get a notification whenever a new event is fired.

Live Demo / GitHub Repository

💡A little bit about how the idea

My portfolio site has got a huge role to play in this idea. I have a contact form through which one can send me messages. Now, storing the messages in a database makes sense but it would be better to have an easier way to view these messages and also get notified when they are sent.

I also figured that many people would like such a solution as not everyone has the time to implement the logic for saving form responses and events to a database. It has many other use cases, I will get to them in a later part in this blog post.

📚 The tech stack

Notiger has got to do everything from authentication to data storage to sending out push notifications. Here is the tech stack it uses -

• NextJS as the frontend framework
• TailwindCSS as a CSS utility class library to style the frontend
• Radix UI for unstyled components like Modals (dialogs) and accordions
• Headless UI for animations
• NextAuth, a simple library to implement authentication
• Firebase Cloud Messaging for sending out notifications
• MongoDB to store user data and events

and of course...

• Netlify for deploying the frontend. It also supports serverless functions and hence I was able to use NextJS API routes as my backend

⚙️ How does Notiger work?

After creating a notiger account, you create a project. Each project can have streams that will receive the events. When an event is received, it is stored in a database, MongoDB in this case and a notification is pushed to all devices with notifications enabled that the user has.

An example event -

As you can see, this event is actually from Netlify. Netlify has this amazing feature that allows us to set up webhook notifications for specific events within Netlify. You can learn more about it here. There are many other applications (like GitHub) that allow us to set up webhook notifications for some events. Notiger can receive these webhooks, store the payload (which usually contains important data regarding the event) in a database, and send out a notification whenever the webhook is fired.

How did I implement authentication with NextAuth?

NextAuth is a JS SDK that allows us to add authentication to our NextJS applications easily. Firstly, we need to set up an API route that will handle all the authentication. Thankfully, NextAuth makes it really easy by providing us with some boilerplate code, and also, we need to only add about 1 file for this. Here is my code - pages/api/auth/[...nextauth].ts -

import NextAuth from "next-auth";
import GoogleProvider from "next-auth/providers/google";
import { MongoDBAdapter } from "@next-auth/mongodb-adapter";
import clientPromise from "../../../lib/mongodb-nextauth";

export default NextAuth({
  adapter: MongoDBAdapter(clientPromise),
  providers: [
    GoogleProvider({
      clientId: process.env.GOOGLE_CLIENT_ID,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
    }),
  ],
  callbacks: {
    async session({ session, token, user }) {
      session.token = token;
      return session;
    },
    async jwt({ token, user }) {
      if (user) {
        token.user = user;
      }
      return token;
    },
  },
  session: {
    strategy: "jwt",
  },
  pages: {
    signIn: "/auth",
    signOut: "/auth",
  },
});

Now, here, I have added social authentication with Google (in just 4 lines of code!) and customized the session and the jwt callbacks. Also, I am storing user data in a database, MongoDB in this case. The JWT callback creates a JWT with the user data object, which is used in other parts of the application. The session callback is customized to include the JWT token when the current session is retrieved. I have also implemented a custom page for authentication, /auth.

Securing pages with middleware

Now, I don't want my users to be greeted with errors by visiting something like the dashboard page when they are not logged in. Thankfully, NextAuth lets us secure pages with just 1 line of code using NextJS Middleware. For example, this is how the dashboard page is secured -

export { default } from "next-auth/middleware";

Yes, that is it!!!

If one is not logged in they, are redirected to the /auth page and once they have logged in, they are redirected to the dashboard page (or any other page from where they were redirected to /auth).

Now, I could have used server-side rendering on my pages to secure them as well, but it requires more code and is also slower and more resource-intensive. Netlify is also one of those hosting providers which support middleware with zero additional configuration which makes using middleware make more sense.

Push notifications with Firebase Cloud Messaging

This was one of the most challenging things to implement. Here is why -

• No official docs on implementing it with React or NextJS
• Guides/videos on how to implement it with NextJS are very less and even then they are outdated or things don't straight-up work at times
• Ran into multiple issues when implementing (mainly because I was using Brave to test Notiger and by default, Brave blocks Firebase Cloud Messaging)

First of all, I added a service worker that would receive the message in the background (that is, when the application is out of focus or closed) and fire a push notification - firebase-messaging-sw.js -

importScripts("https://www.gstatic.com/firebasejs/9.6.7/firebase-app-compat.js")
importScripts("https://www.gstatic.com/firebasejs/9.6.7/firebase-messaging-compat.js")

const firebaseConfig = {
  apiKey: # Retrieve from the Firebase Console,
  authDomain: # Retrieve from the Firebase Console,
  projectId: # Retrieve from the Firebase Console,
  storageBucket: # Retrieve from the Firebase Console,
  messagingSenderId: # Retrieve from the Firebase Console,
  appId: # Retrieve from the Firebase Console
};

const app = firebase.initializeApp(firebaseConfig);
const messaging = firebase.messaging(app);

messaging.onBackgroundMessage((payload) => {
  console.log("Notification payload: ", payload);

  return self.registration.showNotification(payload.data.name || "New Event", {
    body: payload.data.description || "",
  });
})

I have also added a handler for foreground notifications (that is when the application is in focus) that would create a toast -

useEffect(() => {
    import("../lib/firebase").then(({ messaging }) => {
      onMessage(messaging, payload => {
        toast.custom(t => <EventToast t={t} payload={payload} />);
      });
    });
  }, []);

I had to import messaging dynamically on the client-side here as it was getting imported on the server-side during building and was throwing errors.

How are events handled?

I am using NextJS API routes for the backend of the application and any webhooks are posted to the events API routes, /api/events

Here is the code for handling events -

try {
    const apiKey = req.headers["x-api-key"] || req.query.apiKey;
    if (!apiKey) {
        return res.status(400).json({
            error: "Missing API key",
        });
    } else if (!(await ApiKey.exists({
            key: apiKey
        }))) {
        return res.status(400).json({
            error: "Invalid API key",
        });
    } else {
        const streamIdFormatted = new ObjectId(streamId as string);
        const body = req.body;
        if (typeof body === "object") {
            if (sizeof(body) <= 16384) {
                const event = new Event({
                    streamId: streamIdFormatted,
                    ...body,
                });

                event.save((err, event) => {
                    if (err) {
                        res.status(500).json({
                            error: err.message
                        });
                    } else {
                        res.status(200).json(event);
                    }
                });

                const stream = await Stream.findOne({
                    _id: streamIdFormatted,
                });

                const registrationTokens = await FCMToken.find({
                    ownerId: stream.ownerId,
                });

                if (registrationTokens.length > 0) {
                    messaging
                        .sendMulticast({
                            data: body,
                            tokens: registrationTokens.map(token => token.token),
                        })
                        .then(res => console.log(res));
                }
            } else {
                throw new Error("Body too large. Keep it under 16384 bytes");
            }
        } else {
            throw Error("Body must be an object (json)");
        }
    }
} catch (error) {
    res.status(400).json({
        error: error.message
    });
}

First of all, everything is wrapped in a try...catch block so that we return an error in case something goes wrong.

In the try block, we are looking for 2 parameters, the streamId and the apiKey. The streamId must be passed in as a query parameter to the application. The apiKey should be passed in as a the x-api-key header usually but in case it is not possible, it can also be passed in as a query parameter. Here is how the requests will look like -

With the API key passed in as a header -

curl --location --request POST 'https://www.notiger.xyz/api/events?streamId=<STREAM_ID>' \
--header 'x-api-key: <API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Test Event",
    "description": "Test Description",
    "icon": "🎇"
}'

With the API key as a query parameter -

curl --location --request POST 'https://www.notiger.xyz/api/events?streamId=<STREAM_ID>&apiKey=<API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Test Event",
    "description": "Test Description",
    "icon": "🎇"
}'

Do note that you can send this POST request from other programming languages as well. Like with JavaScript, for instance, you can use axios or with Python, you can use requests.

If the API key is valid, we save the event to the database, given that the event payload is under 16 kilobytes in size and is in the form of a JSON object. This is to prevent spam. Checks for streamId is done beforehand itself.

After saving the event to the database, we retrieve the stream associated with the event and then the Firebase Cloud Messaging registration tokens associated with the owner of the stream. This is needed to send the notifications to the devices with notifications enabled the user has. Next, we send the notification.

Understanding the event payload

Whenever a webhook is fired, a payload is passed in as well. Notiger will accept all payloads under 16 kilobytes which are in the form of a JSON object. This payload usually contains more details about an event. For example, in the case of a build success event on Netlify, it contains information about the site, the time it was published, the deployed URL, the serverless functions deployed to AWS Lambda, and many more.

Notiger also adds an _id, __v and streamId field to each event. The _id field is the id of the event stored in MongoDB. In fact, the date it was created can also be retrieved from it.

Code to retrieve created timestamp of a MongoDB document -

const getCreatedAtFromMongoId = (mongoId: string): string => {
  return format(new Date(parseInt(mongoId.substring(0, 8), 16) * 1000), "PPpp");
};

I go over it in more detail in this tweet

The __v field is the version of the document and increments whenever it is updated. The streamId field is the id of the stream the event belongs to.

⚗️ Use cases

What are the applications where Notiger can be used?

I have already gone over the example of the contact form and Netlify build notifications. There are, however, many more use cases, some quite advanced -

IoT Devices

As smart home devices and other IoT devices are getting more popular and common, one is looking for making better use of them. When a specific event occurs, like say when the temperature goes above 30°C in a lab environment, an event can be triggered that will push a notification to, say, the lab owner's phone so that they can take immediate action.

Manufacturing

Many manufacturing tasks often take a long time and notifications can help here too. Say, there is a 3D print going on and as soon as it is done, the 3D printer can fire a webhook notifying the owner that the print is done. It can also be used in cases of mechanical failures etc.

R&D

Complex computational operations take a long time and, here as well, notifications can be fired in case of failures, successes, etc.

SaaS

SaaS owners often want to get a real-time feed of the number of sign-ups, paid users, etc. on their applications. Notifications can be fired on events such as sign-ups, plan upgrades, bug reports, etc.

🖱️ How to use Notiger?

One of my goals with Notiger was to make it as easy to use as possible. Let us go through a mini-guide on how to use it

The first step is to sign up by clicking the login button at the top-right corner or visiting /auth. Here, you will be prompted to sign in with Google.

Next, head over to the dashboard page -

Next, create a project -

Click on the project and you should be taken to the project page. Here is how it should look like -

Now, let us create a stream -

Upon clicking on the stream, we can see that there are no events yet -

We can see the API route by clicking on the button that says "See API Route" -

This will be used when sending webhook notifications.

Now that we have copied the URL, we can head over to generate an API Key -

Copy this value as well.

For this example, I am going to be using Postman to send a webhook but in a real-world scenario, it will likely be sent from code or a shell script.

Here is how we do it from Postman -

Also, don't forget to add a payload. It may look something like this -

Do note that you can pass in the API key as a query parameter called apiKey as well. Now click on "Send".

We will get back a response, somewhat like this -

Also, now if we check our stream in the Notiger projects dashboard, we will be able to see the event -

To enable notifications, click the bell on the bottom-right corner -

✨ Conclusion

It had been an amazing journey building Notiger, squashing bugs, and writing this blog post! Can't wait to see how this side project does in the days to come!

Bye, and have a nice day 😁🤞

🔗 Important Links

• Notiger
• Notiger GitHub Repository
• Netlify

However, Google Analytics has got its own set of issues. One must ask for a cookie consent to use Google Analytics as Google Analytics uses cookies. The Google Analytics script is also quite big and is known to slow down websites. There have been recent allegations against Google Analytics for not being privacy-friendly and many European authorities have also found it breaching GDPR.

So, what is the solution?

Over the years, many privacy-friendly analytics solutions have emerged including Fathom Analytics, Plausible Analytics, and Umami Analytics. The last 2 are open-source and all 3 of them are cookie-less and have a lightweight script that should not affect website load times.

We are going to be focusing on Umami in this article

A little bit about Umami

Umami is an open-source self-hosted analytics service. This means the source code can be accessed by anyone and one must host it themselves. Now, you might say that this costs money and it is not free but today we are going to look at how we can host it for free. Also, Umami uses NextJS API routes for the backend and hence it can run on any serverless architecture. We are going to be looking at setting it up on Railway today, however, it can also be hosted on Vercel or Netlify. We are also going to look at adding analytics to a NextJS application.

You can see a live demo of the platform here

Fun fact: Hashnode also uses Umami and is rolling out an Umami dashboard as advanced analytics 😎

You can see the public analytics for my blog here

Hosting Umami for free on Railway

Railway is an awesome hosting platform that lets you host applications quickly and easily. The free plan allows usage of up to $5/month which should be good enough for a few small to medium-sized websites.

In fact, I have been using it for the past 3-4 months and it has been an amazing experience. My usage costs are usually lower than $2/month and hence I have never paid anything. You don't even need to link your credit card!

My usage this month (3 websites) -

You can also link a credit card to get $10 of usage per month for free (you will be charged for anything above that).

You can sign up here

Setting up the project on Railway

We are going to follow the official guide on hosting it on Railway

First of all, we must fork the repository. This will help us make changes to the source code to fit our own needs and more importantly, receive updates in the future (as we will see later in the tutorial). Head over to the Umami GitHub repository and click on fork on the top-right corner -

You may be asked to select your personal account or an organization if you are in any. I would recommend going for personal account unless it is for an organization.

Once you have signed up for an account, click on "New Project" (note that I already have an existing project and hence the layout looks like this. It may be different for you) -

Now, select "Deploy from Repo" on the new project screen -

Do note that if you didn't sign up with GitHub, you will be prompted to connect your GitHub account.

Search and select Umami there.

Make sure that the master branch has been selected. Now click on deploy -

This might take some time (2-5 minutes).

This is how it should look like after deploying (do note that I am currently using the Metro UI and the layout might look a little different) -

Now, we need to add a database. We are going to be using PostgreSQL for this example. Now, Railway has built-in support for databases and hence we can spin up a PostgreSQL instance within Railway itself for free.

Click on this "New" button -

Select "Databases" and then select "PostgreSQL" -

This might take some time as well.

Do note that if you are using the old UI, you have to select the "Add Plugin" button.

Now, we need to add two environment variables, PORT and HASH_SALT. Click on the card that says "umami" and go to the "Variables" tab -

In the old UI, there will be a button called "Variables" in the sidebar. Click that and then add the following variables under "custom".

We need to put a random string for the HASH_SALT environment variable. Use any random string generator like this one. Let us go with 20 characters including uppercase and lowercase letters, numbers, and symbols -

Now paste that into Railway and click "Add" -

Also, add an environment variable called PORT and set it to 3000 -

Note that Railway will redeploy our application every time we add an environment variable.

Setting up our database schema

Now, we need to make tables in our database. For this, we need to locally clone the project. Go ahead and clone it with git and open a terminal in that repository (I am using the GitHub CLI to clone here but you can use git as well) -

Now, we need to install the Railway CLI. You can install it with NPM with the following command -

npm i -g @railway/cli

You can also install it with Homebrew with the following command -

brew install railwayapp/railway/railway

Now run the following command to authenticate the CLI with your Railway account -

railway login

Note that if you face any issues while doing this, you can also try logging in with the following command -

railway login --browserless

Now run the following command to link the local directory with your Railway project -

railway link

Now head over to Railway and click the PostgreSQL card and go to the "Variables" tab -

Now run the following command in the terminal -

railway run psql -h PGHOST -U PGUSER -d PGDATABASE -f sql/schema.postgresql.sql

Replace the values caps with their corresponding values from the Railway dashboard (from the environment variables tab for PostgreSQL from the previous step)

Now press enter to run the command.

Do note that you need the PostgreSQL CLI for this. If you don't have it, you can follow this guide to install it.

Now run the following command to deploy it -

railway up

Hooray, we have successfully deployed Umami 🥳

Using Umami

After deploying, you will get an URL to deployment logged on to your CLI. You can also retrieve this URL from the Railway web app.

You can also set up a custom subdomain (or even a custom domain) from the Umami dashboard -

You will see a login screen now. The username is "admin" and the default password is "umami" (we will change this).

Our dashboard should look like this now -

Now, there is a banner saying there is a new version out! While writing this tutorial, Mikecao, the creator of Umami, pushed a new version 😅

Now, that is a good thing because now I get to show you how to update Umami 😎

Before that, let us just quickly change our password as "umami" isn't a secure password.

Head over to Settings --> Profile and click on "Change Password"

Enter "umami" in the "Current Password" field and then set a new secure password and click "Save" -

Updating Umami

Head over to the forked Umami repository on GitHub. You should see that our branch is behind by a few commits -

Click on "Fetch Upstream" and then "Fetch and merge" -

That is it! A new deployment will be initiated on Railway and in a few minutes, you should be up and running the latest version -

Adding Umami to a NextJS website

Now, let us look at adding Umami to a NextJS website. For this let us first create a new NextJS application (note that it will work with existing NextJS applications as well) -

npx create-next-app umami-tutorial

Let us now move into that directory -

cd umami-tutorial

Now, open it in your favorite text editor. We will be using VSCode for this tutorial -

code .

Now, open the pages/_app.js file. It should look like this -

import '../styles/globals.css'

function MyApp({ Component, pageProps }) {
  return <Component {...pageProps} />
}

export default MyApp

Now, let us add the script tag for Umami. This is how our _app.js should look like now -

import Script from "next/script";
import "../styles/globals.css";

function MyApp({ Component, pageProps }) {
  return (
    <>
      {process.env.NEXT_PUBLIC_UMAMI_SCRIPT_URL &&
        process.env.NEXT_PUBLIC_UMAMI_WEBSITE_ID && (
          <Script
            src={process.env.NEXT_PUBLIC_UMAMI_SCRIPT_URL}
            data-website-id={process.env.NEXT_PUBLIC_UMAMI_WEBSITE_ID}
            strategy="lazyOnload"
          />
        )}
      <Component {...pageProps} />
    </>
  );
}

export default MyApp;

Here, we are using the NextJS Script component and lazy loading the script so that it doesn't block our website from loading.

We will also need to add the environment variables but before that, we need to add the website to Umami.

Head over to Umami and then to Settings --> Websites -

Now, click on "Add website"

I am naming this "Umami Tutorial" but you can name it whatever you want to. In the next field, make sure to enter the domain and NOT THE URL to the website. Note that I have quickly created a GitHub repository and deployed this NextJS app to Vercel. I have also checked "Enable Share URL" so that I can share the analytics for this website with you guys 😁

Here it is - https://umami-tutorial.up.railway.app/share/3lOPyajp/Umami%20Tutorial

Now, click on "Save" and then "Get tracking code" -

From the modal that appears, just copy the values of data-website-id and src -

Now, create a new file in your NextJS app called .env.local and add the following environment variables -

NEXT_PUBLIC_UMAMI_SCRIPT_URL= # Your script URL, the value under `src`
NEXT_PUBLIC_UMAMI_WEBSITE_ID= # The website's id, the value under `data-website-id`

Now, visit the website on your browser and take a look at the Umami dashboard, it should record a view and a visit under the "Realtime" tab -

We can see more detailed analytics under the details page of the website -

More data will pile up as you start getting visitors on your site

Note: Some browsers like brave have in-built ad-blockers which blocks such scripts from loading in many cases. Even third-party ad-blockers can be responsible for this. If no data is showing up in your Umami dashboard, try a browser without ad-blockers (or private mode), try restarting your development server, and make sure that the values of the environment variables are right.

Woohoo, that was a lot!

Conclusion

We got Umami set up and running and added analytics to a NextJS application. Umami does a lot more like recording events. Take a look at their documentation for more information

I hope everything worked out for you. Do feel free to comment on this article or reach out to me on Twitter and I will help you out 😄

Important Links

• Umami
• Umami Docs
• Official guide on setting up Umami on Railway
• Railway
• Repository for this tutorial
• Demo website for this tutorial
• Public analytics for the demo website

🤔 What is TwNFT?

TwNFT is a simple web application that allows you to mint your tweets as NFTs for free.

It is my submission for the Thirdweb x Hashnode Hackathon.

Live Demo / GitHub Repository

🌐 What is Thirdweb?

Getting started with web3 can be difficult even though it is the hype nowadays. We need to write something called a smart contract, which is required to perform actions on the blockchain. To write smart contracts on the Ethereum blockchain, we need to learn a new programming language called Solidity.

Thirdweb provides us with smart contracts which have been written by professionals in the field. They also provide us SDKs which makes using these easy. This allows people with basic programming knowledge to make web3 applications with ease. Thirdweb also takes care of deploying these smart contracts to the blockchain.

Let us now go back to TwNFT

💡Where did the idea come from?

This hackathon was announced back on the 5th of January, 2022 but I didn't get a solid idea until the 18th of January. So where did it come from?

I came across an application called GitNFT from one of Chris Bongers's articles. GitNFT lets you mint git commits as NFTs and that is when I thought, "How about minting tweets as NFTs?".

I did some research and didn't find any application that did this so it was a golden opportunity for me 🤩

📚 The tech stack

What technologies did I use for TwNFT?

• NextJS for the website
• TailwindCSS for styling
• Firebase for Twitter authentication and data storage
• Vercel for deploying the frontend
• Express for the backend API
• Heroku to deploy the backend

and of course...

• Thirdweb for web3 authentication and minting the NFT

🧐 How does TwNFT work?

One needs to first sign in with Twitter and then put in the tweet URL for the tweet they want to mint. Before minting, the image that will be minted can also be customized. One needs to assign a name to the NFT and optionally add a description (or else, the tweet's content will be used).

Before minting, we have 2 checks to ensure that the person minting the NFT owns that tweet (this is why they are asked to log in with Twitter) and if the tweet has been minted before or not. We don't allow minting the same tweet multiple times, and this is to ensure that every NFT minted is unique.

Now let us take a deeper dive into the web3 part

A deeper dive into web3 authentication with Thirdweb

Setting up authentication with Thirdweb is as easy as adding ~10 lines of code. I am using the @3rdweb/hooks package for this application and it is a breeze. The @3rdweb/react package is easier to implement as it also packs in the UI. However, if you want a custom UI (which I wanted), the hooks package is a better choice.

Do note that you need to be using ReactJS to use any of the aforementioned packages.

Coming to the code, firstly, you need to add the Thirdweb Provider to the application -

import { ThirdwebWeb3Provider } from "@3rdweb/hooks";

const connectors = {
  injected: {},
  walletconnect: {},
};

const supportedChainIds = [1, 4, 137, 250, 43114, 80001];

function MyApp({ Component, pageProps }) {
  return (
    <ThirdwebWeb3Provider
      connectors={connectors}
      supportedChainIds={supportedChainIds}
    >
      <Component {...pageProps} />
    </ThirdwebWeb3Provider>
  );
}

Then, it is as easy of using the useWeb3() hook provided to us by either packages to retrieve the connectWallet function. We have to now just call this function with the wallet type -

<button
  onClick={() => {
    connectWallet("injected");
  }}
  >
  Login with Metamask
</button>

Here injected is for the wallet injected in the browser. This is Metamask in most cases.

For a detailed guide on implementing web3 authentication with Thirdweb, check out their official guide.

A deeper dive into minting the NFT with Thirdweb

I am using the Thirdweb Typescript SDK for minting the NFT on the server-side. Minting should take place on the server-side for security reasons.

Minting with the Thirdweb SDK is extremely easy. Let us see how it works -

First, we initialize the SDK with our private key. Do keep this secret as anyone who has your private key can gain access to your wallet. I am using ethers for initializing a wallet here.

const SDK = new ThirdwebSDK(
  new ethers.Wallet(
    process.env.PRIVATE_KEY,
    ethers.getDefaultProvider("https://rinkeby-light.eth.linkpool.io/")
  )
);

Next, we initialize the NFT Module that will let us mint the NFT -

const nftModule = sdk.getNFTModule(process.env.NFT_MODULE_ADDRESS);

At last, we call the mintTo function asynchronously -

const result = await nftModule.mintTo(
  payload.receiverAddress,
  nftMedatada
);

Here the result gives us the NFT's tokenId. The tokenId is a unique identifier for the NFT in that collection.

Now, that is it. We have minted an NFT!!!

For a more detailed guide, you can check out Thirdweb's official guide on minting an NFT.

❓ What was this NFT Module?

Thirdweb provides us with many modules and the NFT Collection module is one of them. It allows you to mint an NFT in an NFT collection and that is what we just did!!! The official collection for this project can be found on OpenSea here.

🖱️ Using TwNFT

To get started, log in with Twitter and head over to the /mint page.

Next, put in the URL to the tweet you want to mint in the textbox on the top and click the arrow -

You should now see a preview of the NFT, something a bit like this -

Feel free to customize the image by clicking on the buttons on the options bar -

Next, click on the "Connect Wallet" button and connect your Metamask wallet. Walletconnect support is coming soon.

You should now see a button saying "Mint NFT" instead of "Connect Wallet" on the options bar. Clicking that should bring up this modal where you can fill out the name of the NFT, and optionally add a description -

After some time, you should get the option to go to the tweet page -

The tweet page will look somewhat like this (do give the image some time to load for the first time) -

Notice that it says the NFT is still being minted and it is going to take 5-10 minutes. Check back after 5-10 minutes and this is what the page should look like -

The NFT is now under your wallet and you can do anything with it, including listing it for sale, selling it, and even transferring it to another wallet.

🖊️ Sidenote

Currently, TwNFT is running on the Rinkeby Test Network. This means all NFTs minted will be on the test network and not on the main network.

However, this is subject to change in the future.

✨ Conclusion

It has been a great journey over the last 13 days making TwNFT, squashing bugs, and implementing features. Excited to see how it goes 😆

Bye, and have a nice day 😁🤞

🔗 Important Links

• TwNFT
• TwNFT GitHub Repository
• TwNFT Backend GitHub Repository
• TwNFT OpenSea collection

This article was first posted on Freecodecamp on the 21st of December, 2021. Link - https://www.freecodecamp.org/news/back-to-top-button-and-page-progressbar-with-html-css-and-js/

You've probably seen a "back-to-top" button at the bottom-right corner on many websites when you're scrolling around. Clicking on that button takes you back to the top of the page.

This is a great feature to have on any website, and today we are going to see how to build it with nothing but HTML, CSS, and JavaScript.

We are also going to look at how to add a page progress bar, one at the top which will increase in progress as we scroll down and decrease as we scroll up.

Note that you can add this to any website, whether it's an existing one or something you have just started working on. The only requirement is that the website should have enough content (or a big enough body height) to be scrollable, or else it will not make sense to add this.

Here is the CodePen of what we are going to build (scroll to see the magic):

How to Make a Back to Top Button for Your Website

First of all, I am going to make the body of the website huge so that it can be scrolled:

body {
  height: 5000px;
}

I am also going to add a linear gradient to the document body so that we can know that the document is being scrolled:

body {
  height: 5000px;
  background: linear-gradient(#00ff04, #09aad3);
}

Let's also quickly add the Back To Top button to the markup:

<button class="back-to-top">Back To Top</button>

Let's also position the button like this:

.back-to-top {
  position: fixed;
  right: 2rem;
  bottom: 2rem;
}

Here, we are giving it a fixed position so that it remains in view even if the document is scrolled. We are pushing it 2rem from the bottom and right side of the screen as well.

This is how our document should be looking like now:

Now, it is time for the fun part – adding the logic.

How to only show the Back To Top button on scroll

Now, we don't want the Back To Top button to be visible all the time – like when the user is at the top of the page. So we are going to show it conditionally. For this example, we are only going to show it when the user has scrolled at least 100 pixels.

First of all, we need to hide the button whenever the user opens the site. We also need to make sure that we add this style, separate from the button's base styles, as the button needs to be shown on scroll.

HTML:

<button class="back-to-top hidden">Back To Top</button>

CSS:

.hidden {
  display: none;
}

Here's the code for conditionally showing the button:

const showOnPx = 100;
const backToTopButton = document.querySelector(".back-to-top")

const scrollContainer = () => {
  return document.documentElement || document.body;
};

document.addEventListener("scroll", () => {
  if (scrollContainer().scrollTop > showOnPx) {
    backToTopButton.classList.remove("hidden")
  } else {
    backToTopButton.classList.add("hidden")
  }
})

Here, the scrollContainer function returns document.documentElement, which is nothing but the HTML element of our document. In case that is not available, the document.body element is returned instead.

Next, we are adding an event listener to our document that will trigger the callback function on scroll. The scrollTop (MDN Reference) value that we are getting from the respective scrollContainer is nothing but the number of pixels that element has been scrolled from the top.

Here, when that value is higher than our set showOnPx value, that is 100px, we remove the hidden class from our button. If that is not the case, we add the class to the button (especially useful for when the user scrolls up manually).

Now, let's work on the logic to scroll to the top whenever the user clicks the button.

How to scroll to top whenever the user clicks the Back To Top Button

Let's quickly write a function for this:

const goToTop = () => {
  document.body.scrollIntoView();
};

The scrollIntoView() (MDN Reference) function scrolls the page to bring the element it is being called upon into view. Here we are calling it on the body so the page will be scrolled to the top.

Now, we need this function to be called whenever the Back To Top Button is clicked:

backToTopButton.addEventListener("click", goToTop)

That's it! We have successfully added the Back To Top functionality to our website.

How to make the scroll smooth

Now, that back to top scroll was quite harsh. Let's look at making it smoother. We can do this by passing in the behaviour as smooth to the scrollIntoView() function.

const goToTop = () => {
  document.body.scrollIntoView({
    behavior: "smooth",
  });
};

That's it! Now the scrolling is nice and smooth.

How to style the Back To Top button

Right now, the Back To Top button is a simple HTML button with some text – and that looks quite ugly. So let us style it.

Before that, we are going to replace the text with an SVG so let me quickly grab one from HeroIcons:

<button class="back-to-top hidden">
  <svg
    xmlns="http://www.w3.org/2000/svg"
    class="back-to-top-icon"
    fill="none"
    viewBox="0 0 24 24"
    stroke="currentColor"
  >
    <path
      stroke-linecap="round"
      stroke-linejoin="round"
      stroke-width="2"
      d="M7 11l5-5m0 0l5 5m-5-5v12"
    />
  </svg>
</button>

We give the icon a class called back-to-top-icon. This is important as the icon is not visible right away and so needs to be styled in order to be visible.

.back-to-top-icon {
  width: 1rem;
  height: 1rem;
  color: black;
}

This is how our button should look now:

The button still looks quite ugly, so let's style it:

.back-to-top {
  position: fixed;
  right: 2rem;
  bottom: 2rem;
  border-radius: 100%;
  background: #141c38;
  padding: 0.5rem;
  border: none;
  cursor: pointer;
}

Now, the up arrow in our button is not visible, let us change its color to something lighter so that it is visible:

.back-to-top-icon {
  width: 1rem;
  height: 1rem;
  color: #7ac9f9;
}

We can also add a hover effect just to make it a tad better:

.back-to-top:hover {
  opacity: 60%;
}

Now, this is how our button should look:

How to make the button's entry smoother

The button seems to appear out of nowhere whenever we scroll. Let's change this behaviour by adding a transition to it and instead of changing the display, we are going to change its opacity:

.back-to-top {
  position: fixed;
  right: 2rem;
  bottom: 2rem;
  border-radius: 100%;
  background: #7ac9f9;
  padding: 0.5rem;
  border: none;
  cursor: pointer;
  opacity: 100%;
  transition: opacity 0.5s;
}

.hidden {
  opacity: 0%;
}

This also makes our hover effect smoother.

Now let's focus on the page progress bar.

How to Add a Page Progress Bar to Your Website

We will be making a progress bar by using a div. As the user scrolls through the page, we will determine the percentage scrolled and keep increasing the width. Let's add the div first and give it a class name of progress-bar:

<div class="progress-bar" />

Now we'll add some styles to it:

.progress-bar {
  height: 1rem;
  background: white;
  position: fixed;
  top: 0;
  left: 0;
}

We are making it fixed so that it is visible as the user scrolls. We are also positioning it at the top of the page.

Now, let's add the JavaScript that sets the width of the progress bar:

const pageProgressBar = document.querySelector(".progress-bar")
document.addEventListener("scroll", () => {
  const scrolledPercentage =
      (scrollContainer().scrollTop /
        (scrollContainer().scrollHeight - scrollContainer().clientHeight)) *
      100;

  pageProgressBar.style.width = `${scrolledPercentage}%`

  if (scrollContainer().scrollTop > showOnPx) {
    backToTopButton.classList.remove("hidden");
  } else {
    backToTopButton.classList.add("hidden");
  }
});

Note that we are using our existing document scroll event listener function.

This is how our progress bar should look like when scrolled:

How to calculate the percentage scrolled

Calculating percentage scrolled is actually quite simple. The scrollTop (MDN Reference) property is the number of pixels scrolled as mentioned earlier.

scrollHeight (MDN Reference) is the minimum height required to fit in all its children in the element it is being called upon.

And finally, clientHeight (MDN Reference) is the inner height of the element it is being called upon.

The clientHeight is subtracted from the scrollHeight because if we don't do that, the area visible will be taken into account as well so we would never hit 100% scrolled.

I have put together this diagram to explain it better:

Here, the line without the arrows represents the clientHeight which is the height of the content visible to us. The line with the arrows represents the scrollHeight and shows that this line continues in both directions. This is the height of the view required to fit in all the content.

At last, the scrollTop value is divided by the difference of scrollHeight and clientHeight and we get a decimal value of the amount scrolled. This is multiplied by 100 to get the value in percentage that we use to determine the width of the div, that is the progress on our progress bar.

Conclusion

I hope you have found this article helpful and are able to implement a Back To Top Button and a Page Progress Bar on your website.

Do reach out to me on Twitter if you want to ask me anything. The next step would be to implement this on your website and make changes as you see fit.

Resources

• CodePen for this example
• MDN Reference for scrollIntoView()
• MDN Reference for scrollTop
• MDN Reference for scrollHeight
• MDN Reference for clientHeight

This article was first posted on Freecodecamp on the 21st of December, 2021. Link - https://www.freecodecamp.org/news/back-to-top-button-and-page-progressbar-with-html-css-and-js/

Note: This article was first published in the Freecodecamp publication on the 15th of December, 2021. The link to the original article - https://www.freecodecamp.org/news/how-to-use-the-dot-github-repository/

GitHub has many special repositories. For instance, you can create a repository that matches your username, add a README file to it, and all the information in that file will be visible on your GitHub profile.

You might already be familiar with the .github directory you'll find in many repositories. The .github directory houses workflows, issue templates, pull request templates, funding information, and some other files specific to that project.

But another special repository you can create is the .github repository. It acts as a fallback for all of your repositories that don't have an actual .github directory with issue templates and other community health files.

For example, say I have a repository named .github with generic bug report and feature request issue templates. And say I create another repository called new-project, but I don't add a .github directory with issue templates to it.

Then if someone goes to the new-project repo and opens an issue, they'll be presented with an option to choose from the generic templates already in the .github directory.

Similarly, if I add a code of conduct to my .github repository, it will be shown across all my repositories that don't explicitly have one.

Just note that the files inside a repository's .github directory will be chosen over the ones in the .github directory. For example, if my new-project repo has a .github directory with a feature request issue template inside, that will be used instead of the generic feature request template from the .github repo.

Let's see how this special repository works in action.

Now let us see this in action

How to Use .github on Personal GitHub Accounts

Creating this special repository is as easy as creating any other repository on GitHub. So go ahead and open GitHub on your web browser and create the repository like this:

After you're done creating the repository, you can start adding files to it. The first file I will add is a bug report issue form. I am not going to go over the details of creating an issue form in this article, but you can have a look at a previous article I wrote about GitHub Issue forms.

.github/ISSUE_TEMPLATE/bug_report.yml

name: 🐛Bug Report
description: File a bug report here
title: "[BUG]: "
labels: ["bug"]
assignees: ["AnishDe12020"]
body:
  - type: markdown
    attributes:
      value: |
        Thanks for taking the time to fill out this bug report 🤗
        Make sure there aren't any open/closed issues for this topic 😃

  - type: textarea
    id: bug-description
    attributes:
      label: Description of the bug
      description: Give us a brief description of what happened and what should have happened
    validations:
      required: true

  - type: textarea
    id: steps-to-reproduce
    attributes:
      label: Steps To Reproduce
      description: Steps to reproduce the behavior.
      placeholder: |
        1. Go to '...'
        2. Click on '...'
        3. Scroll down to '...'
        4. See error
    validations:
      required: true
  - type: textarea
    id: additional-information
    attributes:
      label: Additional Information
      description: |
        Provide any additional information such as logs, screenshots, likes, scenarios in which the bug occurs so that it facilitates resolving the issue.

I am also going to create a feature request form.

.github/ISSUE_TEMPLATE/feature_request.yml

name: ✨Feature Request
description: Request a new feature or enhancement
labels: ["enhancement"]
title: "[FEAT]: "
body:
  - type: markdown
    attributes:
      value: |
        Please make sure this feature request hasn't been already submitted by someone by looking through other open/closed issues

  - type: textarea
    id: description
    attributes:
      label: Description
      description: Give us a brief description of the feature or enhancement you would like
    validations:
      required: true

  - type: textarea
    id: additional-information
    attributes:
      label: Additional Information
      description: Give us some additional information on the feature request like proposed solutions, links, screenshots, etc.

I am also going to be adding a pull request template.

.github/pull_request_template.md

<!-- 
Thanks for creating this pull request 🤗

Please make sure that the pull request is limited to one type (docs, feature, etc.) and keep it as small as possible. You can open multiple prs instead of opening a huge one.
-->

<!-- If this pull request closes an issue, please mention the issue number below -->
Closes # <!-- Issue # here -->

## 📑 Description
<!-- Add a brief description of the pr -->

<!-- You can also choose to add a list of changes and if they have been completed or not by using the markdown to-do list syntax
- [ ] Not Completed
- [x] Completed
-->

## ✅ Checks
<!-- Make sure your pr passes the CI checks and do check the following fields as needed - -->
- [ ] My pull request adheres to the code style of this project
- [ ] My code requires changes to the documentation
- [ ] I have updated the documentation as required
- [ ] All the tests have passed

## ℹ Additional Information
<!-- Any additional information like breaking changes, dependencies added, screenshots, comparisons between new and old behavior, etc. -->

The last file I am going to be adding is a code of conduct – but this is going to be on the root of the repository. Despite that, this will work as intended (code of conduct files are usually kept on the root of the repository). Note that I am using the Contributor Convent convention.

CODE_OF_CONDUCT.md -

# Contributor Covenant Code of Conduct

## Our Pledge

We as members, contributors, and leaders pledge to make participation in our
community a harassment-free experience for everyone, regardless of age, body
size, visible or invisible disability, ethnicity, sex characteristics, gender
identity and expression, level of experience, education, socio-economic status,
nationality, personal appearance, race, caste, color, religion, or sexual
identity and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming,
diverse, inclusive, and healthy community.

## Our Standards

Examples of behavior that contributes to a positive environment for our
community include:

* Demonstrating empathy and kindness toward other people
* Being respectful of differing opinions, viewpoints, and experiences
* Giving and gracefully accepting constructive feedback
* Accepting responsibility and apologizing to those affected by our mistakes,
  and learning from the experience
* Focusing on what is best not just for us as individuals, but for the overall
  community

Examples of unacceptable behavior include:

* The use of sexualized language or imagery, and sexual attention or advances of
  any kind
* Trolling, insulting or derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or email address,
  without their explicit permission
* Other conduct which could reasonably be considered inappropriate in a
  professional setting

## Enforcement Responsibilities

Community leaders are responsible for clarifying and enforcing our standards of
acceptable behavior and will take appropriate and fair corrective action in
response to any behavior that they deem inappropriate, threatening, offensive,
or harmful.

Community leaders have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions that are
not aligned to this Code of Conduct, and will communicate reasons for moderation
decisions when appropriate.

## Scope

This Code of Conduct applies within all community spaces, and also applies when
an individual is officially representing the community in public spaces.
Examples of representing our community include using an official e-mail address,
posting via an official social media account, or acting as an appointed
representative at an online or offline event.

## Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported to the community leaders responsible for enforcement at
[INSERT CONTACT METHOD].
All complaints will be reviewed and investigated promptly and fairly.

All community leaders are obligated to respect the privacy and security of the
reporter of any incident.

## Enforcement Guidelines

Community leaders will follow these Community Impact Guidelines in determining
the consequences for any action they deem in violation of this Code of Conduct:

### 1. Correction

**Community Impact**: Use of inappropriate language or other behavior deemed
unprofessional or unwelcome in the community.

**Consequence**: A private, written warning from community leaders, providing
clarity around the nature of the violation and an explanation of why the
behavior was inappropriate. A public apology may be requested.

### 2. Warning

**Community Impact**: A violation through a single incident or series of
actions.

**Consequence**: A warning with consequences for continued behavior. No
interaction with the people involved, including unsolicited interaction with
those enforcing the Code of Conduct, for a specified period of time. This
includes avoiding interactions in community spaces as well as external channels
like social media. Violating these terms may lead to a temporary or permanent
ban.

### 3. Temporary Ban

**Community Impact**: A serious violation of community standards, including
sustained inappropriate behavior.

**Consequence**: A temporary ban from any sort of interaction or public
communication with the community for a specified period of time. No public or
private interaction with the people involved, including unsolicited interaction
with those enforcing the Code of Conduct, is allowed during this period.
Violating these terms may lead to a permanent ban.

### 4. Permanent Ban

**Community Impact**: Demonstrating a pattern of violation of community
standards, including sustained inappropriate behavior, harassment of an
individual, or aggression toward or disparagement of classes of individuals.

**Consequence**: A permanent ban from any sort of public interaction within the
community.

## Attribution

This Code of Conduct is adapted from the [Contributor Covenant][homepage],
version 2.1, available at
[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].

Community Impact Guidelines were inspired by
[Mozilla's code of conduct enforcement ladder][Mozilla CoC].

For answers to common questions about this code of conduct, see the FAQ at
[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
[https://www.contributor-covenant.org/translations][translations].

[homepage]: https://www.contributor-covenant.org
[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
[Mozilla CoC]: https://github.com/mozilla/diversity
[FAQ]: https://www.contributor-covenant.org/faq
[translations]: https://www.contributor-covenant.org/translations

We can add more files like funding information, contributing guides, and much more. For more information, you can look at the GitHub docs regarding community health files

The .github repository in action

My blogs repository doesn't have any issue templates, code of conduct, or any other file except for the markdown files of my blogs and a README. So it's the best repository to test upon if this feature is working or not.

I can already see the code of conduct appearing here:

If I try to create an issue, I am presented with the templates as well:

This will also work when creating a pull request.

How to Use the .github Repository for an Organization/Public Account

The .github repository on an organization account works just like the .github repository on a personal GitHub account – except there is one difference.

Organizations can also have profile READMEs that show up on the organization page on GitHub. This README resides on the profile directory of the organization's .github repository. To demonstrate this, I will quickly create a demo organization.

When creating the .github repository for an organization, you should get this message:

Also when adding the profile README to profile/README.md, you should be getting this message:

Now, I am going to add some content to that README file and commit it. When I visit the organization's home page this is what we should see:

Conclusion

I hope you now know what the .github repository does. You should also know how to set up default community health files for your repositories and a profile README for your organization.

Feel free to reach out to me on Twitter and have a nice day 😃

Resources

• GitHub Documentation on Community Health Files
• My .github repository
• My test organization's .github repository
• Contributor Convent
• Article on getting started with GitHub issue forms

I am currently working on a project called DevKit which is a PWA that will house developer tools in one single application and provide ways to get your work done quickly. Do check it out at https://www.devkit.one/.

Note: This article was first published in the Freecodecamp publication on the 15th of December, 2021. The link to the original article - https://www.freecodecamp.org/news/how-to-use-the-dot-github-repository/

Adding Sandpack to our Project

We are going to be adding Sandpack to a react application (made with create react app) though the process should be quite the same for NextJS or Gatsby.

Create a starter react project and navigate into it -

npx create-react-app sandpack-demo
cd sandpack-demo

Note: Feel free to use the Yarn package manager if that is what you prefer.

Now, let us install Sandpack

npm install @codesandbox/sandpack-react

That is it for dependencies, now let us move on to adding Sandpack to the application.

Go ahead and delete App.css, App.test.js, setupTests.js, and logo.svg. Also remove all the boilerplate code in App.js. It should look like this -

function App() {
  return <div></div>;
}

export default App;

Now, let us import Sandpack in App.js -

import { Sandpack } from "@codesandbox/sandpack-react";
import "@codesandbox/sandpack-react/dist/index.css";

Here, we are also importing a CSS file that contains the styles for the editor and preview.

We should also add the Sandpack component -

<Sandpack />

That is it!!! Now let us start the dev server by running npm start. Navigate to http://localhost:3000/ and this is what you should see -

Custom Templates

The default template that Sandpack uses is vanilla js but we can also use other templates like react, vue, angular, etc. Let us see the react template in action. Just add the template attribute and specify the value as react -

<Sandpack template="react" />

Feel free to go through the Sandpack Custom Content documentation for more templates and information on how to add your custom code.

Custom Theme

We can also customize the theme. Let us look at adding a pre-built theme -

<Sandpack template="react" theme="sandpack-dark" />

This is how the editor should look like -

Feel free to go through the Sandpack Custom UI documentation for more themes and information on building your theme.

At last, this is how our App.js looks like -

import { Sandpack } from "@codesandbox/sandpack-react";
import "@codesandbox/sandpack-react/dist/index.css";

function App() {
  return (
    <div>
      <Sandpack template="react" theme="sandpack-dark" />
    </div>
  );
}

export default App;

Now, that was just getting started with Sandpack but now let us look at it being used in a more real world example. Feel free to go through the Sandpack documentation for more detailed guides and an API reference.

Using Sandpack with Next MDX Remote

Next MDX Remote is a library that parses MDX content (markdown but with support for JSX as well) and helps load them via getStaticProps or getServersideProps in NextJS. It is mainly used for documentation and blog posts. Today, we are going to be adding Next MDX Remote to a NextJS application and customize the code component by replacing it with Sandpack. First of all, let us make a new NextJS application and navigate into it -

npx create-next-app sandpack-next-mdx-remote
cd sandpack-next-mdx-remote

Now, let us delete Home.module.css under the styles directory and remove the boilerplate code in index.js under the pages directory. This is how it should look like -

export default function Home() {
  return <div></div>;
}

Adding Next MDX Remote

The next step is to add and setup Next MDX Remote so let us do that -

npm install next-mdx-remote

Now, let us go to index.js and add the following code -

import { serialize } from "next-mdx-remote/serialize";
import { MDXRemote } from "next-mdx-remote";

export default function Home({ source }) {
  return (
    <div>
      <MDXRemote {...source} />
    </div>
  );
}

export const getStaticProps = async () => {
  const source = "```html\n<h1>Hello World</h1>\n```";

  const mdxSource = await serialize(source);

  return { props: { source: mdxSource } };
};

Note that I am just writing down some basic markdown with a code block. Usually, this markdown is sourced from external files and paired with frontmatter but that is not something I am going to go over in this article.

Now let us start the development server by running npm run dev. Upon navigating to http://localhost:3000/, this is what our page should look like -

Note that a simple HTML code element is being rendered now

Now, I could add syntax highlighting to this using remark prism but as we are anyways going to use Sandpack, let us move onto that instead.

Adding Sandpack to Next MDX Remote

First of all, let us install the Sandpack package -

npm install @codesandbox/sandpack-react

Now let us create a directory called components and add a file named CustomMDXCode.js in there. Add the following code to that file -

import { Sandpack } from "@codesandbox/sandpack-react";
import "@codesandbox/sandpack-react/dist/index.css";

const CustomMDXCode = props => {
  return (
    <Sandpack
      template={props.template}
      files={{ [`/${props.filename}`]: props.children }}
    />
  );
};

export default CustomMDXCode;

Here, we are importing Sandpack, making a custom component, which is passed in some props. These props will contain the filename of the file, the template to use, and of course, the code. Note that we are adding a / to the beginning of the filename through string interpolation as it is required by Sandpack.

Now, let us go back to our index.js file and make some changes to leverage the use of the new component -

import { serialize } from "next-mdx-remote/serialize";
import { MDXRemote } from "next-mdx-remote";
import CustomMDXCode from "../components/CustomMDXCode";

export default function Home({ source }) {
  return (
    <div>
      <MDXRemote
        components={{ code: props => <CustomMDXCode {...props} /> }}
        {...source}
      />
    </div>
  );
}

export const getStaticProps = async () => {
  const source =
    "```js template=react filename=App.js\nexport default function App() {\n  return <h1>Just some text...</h1>\n}\n```";

  const mdxSource = await serialize(source);

  return { props: { source: mdxSource } };
};

Here, we are adding a custom component for the code attribute (reference for all mdx components - https://mdxjs.com/table-of-components/), which is nothing but the Sandpack component we created earlier. We have also changed the markdown source to javascript, added a template attribute and pointed that to react, added a filename attribute and named the file App.js, and wrote a simple function that displays some text for the code part.

This is how our page should look like now -

Conclusion

That is it for this article. I hope you enjoyed it and learned how to add Sandpack to your react application. Feel free to comment on this post or reach out to me via Twitter in case you have any questions.

Links

Sandpack - https://sandpack.codesandbox.io/

Sanpack Documentation - https://sandpack.codesandbox.io/docs/

Sandpack GitHub - https://github.com/codesandbox/sandpack

Next MDX Remote - https://github.com/hashicorp/next-mdx-remote

All MDX Component - https://mdxjs.com/table-of-components/

Toasts are very useful for showing users some information. It has a wide variety of uses from displaying success messages for successful actions, showing error messages in case something goes wrong, and much more. Today we are going to build a simple toast with HTML and CSS. We are going to be using some javascript to add some interactivity.

What we are making -

We are going to be making a toast that shows up when a button is clicked. It can also be closed, which is hidden away, by clicking a close button.

Basic CSS to make a toast

To make a toast animate in or out, we need to make the toast first. For this example, I am going to add a simple icon and some text in a box and that is going to be our toast.

So, in the markup, let us start by adding a div for out toast -

<div class="toast" id="toast"></div>

Now, we need to add an icon. I am going to grab a simple information icon from HeroIcons and put in the SVG -

<div class="toast" id="toast">
  <svg xmlns="http://www.w3.org/2000/svg" fill="none" class="icon" viewBox="0 0 24 24" stroke="currentColor">
    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
  </svg>
</div>

Let us also add a text -

<div class="toast" id="toast">
  <svg xmlns="http://www.w3.org/2000/svg" fill="none" class="icon" viewBox="0 0 24 24" stroke="currentColor">
    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
  </svg>
  <p class="text">Some Information</p>
</div>

This is what our page should look like -

The icon is so big that is doesn't even fit in the view. Let us fix this design with some CSS and then style it.

First, we are going to style the icon by defining a width and a height -

.icon {
  height: 2rem;
  width: 2rem;
}

Let us now make our toast a flexbox and add some margin on the icon. I am also going to position the toast on the top-right using an absolute position.

.icon {
  height: 2rem;
  width: 2rem;
  margin-right: 1rem;
}

.toast {
  display: flex;
  align-items: center;
  position: absolute;
  top: 50px;
  right: 80px;
}

Everything looks good except for the styling. Let us add some colors and other styles -

.icon {
  height: 2rem;
  width: 2rem;
  margin-right: 1rem;
  color: white;
}

.text {
  color: white;
}

.toast {
  display: flex;
  align-items: center;
  position: absolute;
  top: 50px;
  right: 80px;
  background-color: black;
  border-radius: 12px;
  padding: 0.5rem 1rem;
  border: 5px solid #029c91;
}

We have changed the background color of the toast, added a border to it, added some border radius, and changed the colors of the icon and the text so that they are visible on the black background.

This is how our toast should now look like -

Let us also add a button that will trigger the animation, that is, show the toast -

<div class="toast" id="toast">
  <svg xmlns="http://www.w3.org/2000/svg" fill="none" class="icon" viewBox="0 0 24 24" stroke="currentColor">
    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
  </svg>
  <p class="text">Some Information</p>

</div>

<button id="show-toast" class="show-toast">Show Toast</button>

Let us also style this button as it looks quite ugly now

.show-toast {
  background-color: black;
  color: white;
  border-radius: 8px;
  padding: 8px;
  cursor: pointer;
}

Let us also disable any overflow -

html,
body {
  overflow: hidden;
}

This is how everything should look like now -

Adding animations

Now that we have the toast and a button to trigger the animations, it is time to add the animations.

First of all, we are going to give the toast a starting point by putting it outside the view. So let us edit the CSS for the toast -

.toast {
  display: flex;
  align-items: center;
  position: absolute;
  top: 50px;
  right: -500px;
  background-color: black;
  border-radius: 12px;
  padding: 0.5rem 1rem;
  border: 5px solid #029c91;
  opacity: 0%;
}

Now let us make a new class called toast-active that will get added to the toast whenever the button is clicked -

.toast-active {
  right: 80px;
  opacity: 100%;
}

Notice that we are also changing the opacity during the transition. This just makes it look a little better.

Now let us write some javascript to add this class to the toast whenever the button is clicked -

let toast = document.getElementById("toast");
document.getElementById("show-toast").addEventListener("click", function () {
  toast.classList.add("toast-active")
});

Here, whenever the button is clicked, the toast-active class is being added to the toast. Right now the animation is instant, which doesn't look good. Let us add a transition -

.toast {
  display: flex;
  align-items: center;
  position: absolute;
  top: 50px;
  right: -500px;
  background-color: black;
  border-radius: 12px;
  padding: 0.5rem 1rem;
  border: 5px solid #029c91;
  opacity: 0%;
  transition: all 0.25s ease-out;
}

Here the transition goes on for a quarter of a second and we have also eased it out so it isn't harsh.

Adding a close button to the toast

We would like to give the user a close button that they can click to close the toast.

First of all, we need to add a button the the toast in our markup -

<div class="toast" id="toast">
  <svg xmlns="http://www.w3.org/2000/svg" fill="none" class="icon" viewBox="0 0 24 24" stroke="currentColor">
    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
  </svg>
  <p class="text">Some Information</p>
  <button id="close-button" class="close-button">
    &#10005;
  </button>
</div>

<button id="show-toast" class="show-toast">Show Toast</button>

Let us also style it so that it is visible -

.close-button {
  background-color: black;
  color: white;
  border: none;
  cursor: pointer;
}

Now, when this button will be clicked, it will just do the reverse of what the show toast button did, that is, remove the toast-active class -

document.getElementById("close-button").addEventListener("click", function () {
  toast.classList.remove("toast-active");
})

Now, clicking the cross symbol (close button) in the toast should take it away from the screen with a transition.

Conclusion

If everything has worked out well so far, give yourself a pat on the back because you have just built a toast with nothing but HTML, CSS, and JS!!!

If you had any issues, feel free to comment down below or reach out to me via Twitter.

Links

Codepen for this project - https://codepen.io/anishde12020/pen/JjrYMrW

HeroIcons - https://heroicons.com/

My Twitter - https://twitter.com/AnishDe12020

This article was first published on Freecodecamp on the 13th of November, 2021 - https://www.freecodecamp.org/news/how-to-use-commitlint-to-write-good-commit-messages/

We are often in a hurry to commit our changes in Git and so we write something random in our commit messages. In fact, I have seen people putting the date and time or even something like commit 1, commit 2 in their messages.

This is not a good practice, as commit messages should be helpful and make sense so that the people working on the project, reading the code, or contributing to it understand the changes from the message itself.

Now let's look at a simple way to solve this issue.

What is Commitlint?

Commitlint is a simple tool that lints your commit messages and makes sure they follow a set of rules.

It runs as a husky pre-commit hook, that is, it runs before the code is committed and blocks the commit in case it fails the lint checks.

How to Use Commitlint with a Simple JavaScript Project

In this example, we are going to see how we can set up commitlint in a simple JavaScript project. To get started, let's create an empty project first:

mkdir commitlint_example && cd commitlint_example

npm init
# OR
yarn init
# Just accept the defaults when prompted to configure the project

Now, let's initialise an empty Git repository:

git init

We must also add a .gitignore file to prevent some files from being committed:

node_modules/

Now we'll add a file called index.js and just log out something for now:

console.log("Hello, World!!!")

Running node . should print out the text on your terminal like this:

Running node . prints out Hello, World!!!

How to Set Up commitlint

We're going to set up commitlint following the official local setup docs here.

Firstly, we need to install the commitlint CLI and add a commitlint config (in this case the default Conventional Commits Config).

npm install @commitlint/cli @commitlint/config-conventional --save-dev
# OR
yarn add -D @commitlint/cli @commitlint/config-conventional

We need to add some configuration to a file named commitlint.config.js like this:

module.exports = {
    extends: [
        "@commitlint/config-conventional"
    ],
}

Now we need to install husky to run commitlint as a pre-commit hook.

npm install husky --save-dev
# OR
yarn add -D husky

We also need to enable the husky hooks:

npx husky install
# OR
yarn husky install

We can add a prepare step which enables the husky hooks upon installation:

npm set-script prepare "husky install"

Now that we are done installing husky, we need to add a pre-commit hook to run commitlint before the code is committed.

npx husky add .husky/commit-msg "npx --no -- commitlint --edit $1"
# OR
yarn husky add .husky/commit-msg "yarn commitlint --edit $1"

Now we're done setting up commitlint. So let's test to see if it works.

First, we'll stage all files to commit them:

git add -A

Now, let's try to commit the changes, without following the default convention:

git commit -m "set up a basic js project, added commitlint and husky for liniting commit messages"

You should get the above output (or something similar) which errors out. If the commit is successful, you have likely gone wrong somewhere. Make sure that you have run all the commands above and try undoing the commit, running the scripts, and committing again until it fails.

Now it is time to commit properly. Run this command:

git commit -m "ci: initialised basic js project, added commitlint and husky to lint commit messages"

And now it all looks good.

How the Default commitlint Convention Works

The default commitlint convention uses the Conventional Commits Convention where there is a type, optionally a scope, a subject, and optionally a body and footer.

For example I can fix a bug related to UI and then the commit message can be fix(ui): Button was not showing up properly on mobile view. Here the type is fix, that is, a fix for a bug, the scope is ui as the fix was related to the ui, and the subject provides more context about the issue.

Note that I can supply multiple scopes, for example, feat(ui,lang): added an option to save the image as svg and added language support for Spanish. Here we introduce 2 features – a new button to save an image as svg and language support for Spanish. This means that there are 2 scopes. The scopes can be separated by the 3 delimiters - ,, / and \.

Just a quick note here: you should usually keep commits small and specific, and while there might be some edge cases, this is not one. We're just using it for example purposes.

Breaking changes are usually represented with an exclamation ! mark but you can also write them in bold in the footer of the commit message. Doing both is the best practice where the footer gives more information. Here's an example:

refactor(runtime)!: Dropped support for NodeJS v12

BREAKING CHANGE: Support for NodeJS v12 has been dropped due to the latest refactor, please upgrade to the latest LTS version of NodeJS

This brings us to multi-line commit messages. Sometimes we need to give more context on something. In this case, it best to include the info in the commit message to make it clear to anyone trying to understand what all has changed and why it has changed in a commit. Here's an example:

docs: Added an aria-label in the IconButton example
aria-label is a required prop by the IconButton component. If it is not present, the build will fail

• Advantages of using commitlint Automatic changelogs – Due to commits following a standard convention, tools like standard-version can automatically generate changelogs
• Better understanding of commits – A commit with a specific type and scope will help you understand what code the commit changes
• Adherence to a particular convention – When you have a big project and a lot of people committing to it, people might forget to use the convention. commitlint blocks such commits so that the commits adhere to the defined convention. Now you know the basics of commitlint. And in the next part of this article, we are going to dive a little deeper and see how to write custom commitlint rules and how to run a commitlint CI in GitHub Actions.

How to Create Custom commitlint Rules

The Conventional Commits Convention works for most projects. But sometimes you might want to add some more rules specific to your use case.

For a complete reference, please look at the official documentation here.

For our example here, we'll use an application which has a library of buttons made with TailwindCSS. You can add your creation to this application through a pull request.

Now these commits can have different types, so let's take a button for this example. This would require me to override the type-enum rule in the conventional commits convention.

To do this, I will create a rules object in my commitlint config and add button as a type. This is how our commitlint.config.js should look:

module.exports = {
    extends: [
        "@commitlint/config-conventional"
    ],
    rules: {
        "type-enum": [2, "always", ["build", "chore", "ci", "docs", "feat", "fix", "perf", "refactor", "revert", "style", "test", "button"]],
    }
}

Here I have just added the button type on top of the default types. Now let's commit this:

git add -A
git commit -m "ci(commitlint): added button as a type of commit"

Now we'll test our button type. For this example, I am just going to add a new line to our index.js file. This is how it should look:

console.log("Hello, World!!!")
console.log("New Button")

Now, let's commit it:

git add -A
git commit -m "button: added a new console.log to qualify as a button"

You should get the above output.

How to Use Commitlint with GitHub Actions

Commit messages are linted locally, but sadly such checks can be skipped locally. So we can add a step in our CI/CD workflow to double-check.

In this example, we are going to be using GitHub Actions but there are official guides for Travis CI, Circle CI, and GitLab CI as well.

How to Push our Code to GitHub

Firstly, we need to push our code to GitHub to use GitHub Actions. So let's do that real quick.

I am going to be using the GitHub CLI for this but you can do it via the GUI – just don't forget to add the upstream to the repository.

We can push the code using git push origin master.

How to Set Up the Workflow

We are going to be using a pre-built GitHub Action for this example, which you can find here: https://github.com/wagoid/commitlint-github-action.

We need to make a new folder called .github and then a new folder in it called workflows. Then we can add a file called commitlint.yml and add the workflow configuration.

.github/workflows/commitlint.yml

name: Lint Commit Messages
on: [pull_request, push]

jobs:
  commitlint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
        with:
          fetch-depth: 0
      - uses: wagoid/commitlint-github-action@v4

This workflow will run every time code is pushed to GitHub and every time a pull request is opened. To test it, let's commit and push our code.

git add -A
git commit -m "ci(commitlint,workflow): added GitHub action workflow to run commitlint on push and pr"
git push origin master

Now, we can go to the GitHub repository and then the actions tab and we can see the workflow.

I made a typo in the name of the workflows folder so I had to fix that and commit and push again so the commit name is different.

When you look at the details, you can see that the workflow has been successful as all the commits until now have adhered to the convention.

We can also inspect the logs:

What's next? I hope everything has worked well for you so far. If you had any issues, feel free to reach out to me on Twitter and I will be happy to help 😃.

Now that you have commitlint set up, it's a good idea to add automated changelogs. So head over to the standard version repository and try to implement it on your own!

Helpful Links

• Demo Repository - https://github.com/AnishDe12020/commitlint-example
• Commitlint website and docs - https://commitlint.js.org/#/
• Commitlint GitHub action - https://github.com/wagoid/commitlint-github-action
• Standard Version GitHub Repository - https://github.com/conventional-changelog/standard-version
• Husky website and docs - https://typicode.github.io/husky/#/
• Conventional Commits - https://www.conventionalcommits.org