Table of contents

• Introduction

  • Prerequisites

  • Steps

    • Project Initialisation
    • Giscus Setup
    • Giscus Nextjs Integration

  • Conclusion

Introduction

When we started out to build sewb.dev, we knew right from the start that we wanted to integrate commenting and reactions from the get-go. Comments and reactions are important ways to get feedback from our readers and engage and learn from people. We started out by building a solution that looked something like this;

• Comment table with relations to post and user
• Post reaction table with relations to post and user
• APIs to facilitate CRUD operations on the database
• A limited but straightforward UI to connect with these APIs.

This solution really worked, and it would serve us during our initial blogging phase. We wanted to Keep It Simple, Stupid (KISS), and we actually did KISS, but we wanted so much more than our readers making CRUD operations on the comment and reaction APIs. We wanted our readers to

• mention other users
• share code snippets
• react to comments from other users

Following another engineering principle, Do not reinvent the wheel, we sought to find a solution that integrates all these requirements and one that adheres to the KISS principle. Say hello to Giscus.app.

Giscus.app is an application that provides commenting and reaction features powered by GitHub discussions. I love this application because of its ease of integration, open-source support, and customisation. Software engineers are wizards and wizardesses, and I am in constant 😵 of how we solve problems using simple tools. Software engineers 🤝 Ingenio partum.

I never imagined that a commenting system could be built on top of Github issues and discussions until I came across Giscus.app.

So here’s how Giscus.app works in the simplest form;

• You create a repository where you want to store comments
• You enable discussions on that repository in the settings
• You add the giscus.app script to your project as well as the configurations it needs
• Anytime our application loads on a page containing the giscus script, giscus would first check if a discussion already exists. If it does, it’ll load the comments associated with that discussion; else, it’ll create a new discussion topic anytime a reaction or comment is sent.

What are the configurations giscus.app needs?

• the repository where the comments and discussions would be stored
• category of the discussion
• page to GitHub discussion topic mapping. This can be the pathname of the page, title etc.
• the position of the text input
• the language of the comments
• should post-reaction be enabled?
• theme to use for giscus

You can also add advanced configurations like

• allowing only specific origins to load comments
• default comment order
• listening to metadata emitted by giscus

So let’s get down to business, how to implement commenting in a react application using GitHub discussion powered through Giscus.app. Before we proceed, there’s a similar package on which Giscus.app is heavily based on, Uterances. While Giscus.app relies on Github discussion APIs, Uterances relies on Github issues as the data store.

Prerequisites

To follow along with this tutorial, you’d need

• node >= 16.13.0
• Das all 😎.

Steps

So here are the following steps we need to take

1. Initialise the project and install dependencies
2. Setup giscus
3. Integrate giscus with nextjs

Project Initialisation

First, let’s install the packages we need. For the purpose of this tutorial, we’d be using NextJS and typescript, but any react framework would work.

Run npx create-next-app@latest --typescript and give your application a name.

Then run npm I @giscus/react

Open the nextjs application, and let’s start coding.

Giscus Setup

Note: The repository where the comments would be stored needs to be public; giscus doesn’t currently have support for private repositories.

Next, head over to GitHub and create a new repository where your comments would be stored. You can create a dedicated repository for your application comments or use the same repository where your application code is. For sewb.dev, we created a separate repository for blog comments, but for the purpose of this tutorial, I’d be using the same repository that houses the tutorial code.

Next, head over to settings on the repository and turn on discussions.

Photo by sewb.dev

We’re almost there; just hang on

• Select the language of your blog
• Input your repository in the format <username/repository_name>, e.g. for this tutorial, the repsitory name is sewbdotdev/giscus-next-integration.
• Select your page → discussion mapping. I would select pathname; feel free to choose the best fit for you.
• Select the category of your discussion and specify if you want giscus to only search for discussions in that category. I selected announcements
• Next, decide if you want the following features to be enabled
  • reaction to the main post
  • emit discussion metadata to the page’s window
  • place the comment input box above the comments
  • if comments should be loaded lazily
• Then, select your desired theme.

Here’s my configuration, which may be entirely different from yours.

Photo by sewb.dev

Copy the script in the enable giscus section, We’d be requiring it for configuring our comments in nextjs. Here’s mine

1<script src="https://giscus.app/client.js"
2        data-repo="sewbdotdev/giscus-next-integration"
3        data-repo-id="R_kgDOHPv7gA"
4        data-category="Announcements"
5        data-category-id="DIC_kwDOHPv7gM4COz-s"
6        data-mapping="pathname"
7        data-reactions-enabled="1"
8        data-emit-metadata="1"
9        data-input-position="top"
10        data-theme="dark"
11        data-lang="en"
12        data-loading="lazy"
13        crossorigin="anonymous"
14        async>
15</script>

Giscus Nextjs Integration

Next, open the nextjs project and head over to the index.tsx file. I’d be cleaning it up as we don’t need the defaults.

1import type { NextPage } from "next";
2import Head from "next/head";
3import styles from "../styles/Home.module.css";
4
5const Home: NextPage = () => {
6  return (
7    <div className={styles.container}>
8      <Head>
9        <title>Create Next App</title>
10        <meta name="description" content="Generated by create next app" />
11        <link rel="icon" href="/favicon.ico" />
12      </Head>
13
14      <main className={styles.main}>
15        <h1 className={styles.title}>Welcome to Giscus Nextjs Integration</h1>
16
17        <p className={styles.description}>
18          Check out the full tutorial at{" "}
19          <a
20            href="https://www.sewb.dev"
21            style={{
22              color: "lightblue",
23            }}
24          >
25            sewb.dev
26          </a>
27        </p>
28      </main>
29    </div>
30  );
31};
32
33export default Home;

Next import the giscus react component and copy the props from the script element to the react component. Add the Giscus component just before the closing main tag.

1//rest of the previous code
2<Giscus
3 repo="sewbdotdev/giscus-next-integration"
4 repoId="R_kgDOHPv7gA"
5 category="Announcements"
6 categoryId="DIC_kwDOHPv7gM4COz-s"
7 mapping="pathname"
8 reactionsEnabled="1"
9 emitMetadata="1"
10 theme="light"
11 inputPosition="top"
12 loading="lazy"
13 lang={"en"}
14/>
15// closing main and div tags

So I imported the Giscus component and added the comment repository to the repo prop; I also added the repoId and the categoryId with mapping props of the pathname. Basically, all these props are similar to the output we got after configuring giscus on Giscus.app.

Finally, if you open the page in your browser, you should see something similar.

Photo by sewb.dev

Let’s test everything to ensure that we can react to posts and create comments. First, you’d need to log in to GitHub to enable commenting.

Photo by sewb.dev

Voila, we have comments, and post-reaction enabled on our blog 😎.

You can change the default comment ordering by configuring giscus.app using a giscus.json file.

Create a giscus.json file at the root of your project and include the following value.

1{
2  "defaultCommentOrder": "newest",
3}

Here I am telling giscus.app to order the comments from the newest to the oldest. You could also set other configurations, e.g. origins that are allowed to load the comments etc., and I’d leave that as a challenge for you to do.

Conclusion

In this tutorial, we discussed the advantages of having a great commenting system, and we explored how we could integrate a fantastic solution called giscus.app in our react project. We used nextjs for this tutorial, but the steps are similar for all JavaScript libraries and frameworks. I do hope I have contributed a bit to your pursuit of knowledge. If you find this tutorial helpful, please leave a comment and reaction below. It encourages us and helps us know where to focus our strengths on. Till we meet again, young padawan 🙇‍♂️.