Forem: Abdulla T

Taking the OpenJS Node.js Services Developer Certification Exam

Abdulla T — Mon, 03 May 2021 16:33:22 +0000

My review on taking the JSNSD (OpenJS Node.js Services Developer) exam, its preparation course, and some useful tips that helped me pass the exam.

Earlier this week, I set up an isolated corner in my living room and took the 2-hour online exam for the OpenJS Node.js Services Developer (JSNSD) certification.

In this post, I would like to talk about the exam itself, my experience and preparation for it, and discuss if it's worth it for you too.

I won't be sharing information about the exam questions as this is against the exam's confidentiality agreement. However, I will talk more about the experience and the preparation course for this exam offered by the Linux Foundation.

Who offers this certificate?

This certification is offered by the OpenJS Foundation, a leading foundation that supports the growth and governance of many NodeJS open source projects such as Node.js, Electron, jQuery, and Webpack.

The exam is delivered through The Linux Foundation, which is also known for delivering other popular certificates such as the Certified Kubernetes Administrator (CKA) and the Linux Foundation Certified Engineer (LFCE) as well as other types of certificates. So, this is probably the most legitimate Node.js certification in the industry nowadays.

There are two types of Node.js certificates offered:

OpenJS Node.js Services Developer (JSNSD) (I took this one)
- Focuses on creating REST API services and security of your services against malicious user input.
OpenJS Node.js Application Developer (JSNAD)
- Focuses on the core modules of Node.js such as the file system, buffers, streams, child processes.

I'll be talking more in-depth about the JSNSD, but some of the tips would also apply if you take the JSNAD.

Exam Format and style

The exam is a performance-based exam (like a practical lab), which means you will take your test on a VM online to write some code and create Node.js applications.

Each task will require you to build a simple Node.js app that implements a specific requirement only (for example, an HTTP method that should return a particular HTTP response and status).

For the JSNSD, you can implement your solution in any way you like. You won't be assessed on how you implement the solution, but on how your application responds to their various HTTP requests.

The exam is 2 hours long, and you will solve it by connecting to a remote desktop Linux environment virtual machine. The VM for the JSNSD is currently using CentOS with a GUI. The VM comes already pre-installed with node, npm, Postman, Visual Studio Code, and even WebStorm IDE. So, you don't need to install anything on the virtual machine you will be testing on.

You are allowed to search on Google and browse any Node.js documentation through the chrome browser of the remote desktop. You can access any documentation, npm modules docs, and even GitHub. However, StackOverFlow and other Stack Exchange websites are blocked during the exam.

Motivation for the exam and its value

I've been using Node.js for over four years, both at work and on my side projects.

I first heard about this certification from Twitter early in 2020, and what greatly interested me was the style of the exam. I thought it would be an exciting challenge to try out, so I decided to take the JSNSD because it's more in line with what I work with more often.

I've read online about some people who have taken one or both certificates to improve their Node.js skills or because their employers asked them (for whatever reason). At the moment, I haven't found any information if this certificate brings a lot of value to the employer as there is no organizational benefit (partner benefits) to the company if their engineers held this certificate.

I usually think that coding skills are better validated by building a challenging project instead of doing a certification in some scenarios. However, I don't want to ignite the debate of whether coding languages certifications are worth it. I would compare these Node.js certifications to the Java associate certifications from Oracle. Some people have found great value by being Java certified in helping them at least get their foot in the door for an interview. The Node.js certifications are barely two years old, so they are not as well known in the industry as the Java certifications, but they might still be a good conversation starter in an interview.

Exam and companion study course cost ($$$)

So, the reason I talked about motivation and value above is because the cost of this certification is an eye-watering USD 300, which is quite expensive for someone who will pay for it from their pocket (like me). If you decide to buy the preparation companion course, you can buy the bundle which costs USD 499 in total at the moment of writing this blog post. This price is for one of the certificates (either the JSNSD or JSNAD).

Thankfully, I bought this exam (and course) at a massive discount during a sale season run by The Linux Foundation. The last discount they had in early April 2021 was offering the exam for $99. They also offered both the exam and preparation course bundle for $149. So, I strongly suggest subscribing to The Linux Foundation email updates and wait for their next sale season, or convince your boss to pay for it.

When you purchase the exam, you get a voucher that is valid for one year. You can schedule your exam anytime during this year. You also get a free retake if you fail your first attempt at the exam.

If you also purchase the course, you will get 1-year access to the course.

Before you buy the exam, make sure you read the list of faqs for Id and system requirements and whether you are not currently living in a sanctioned country.

Preparing for the exam

Initially, when I bought the exam, there was no companion preparation course, so I referred to their list of suggested references, which included:

Node Cookbook
https://nodeschool.io/
Node.js documentation
Any Node.js web framework documentation

However, while I read some chapters and sections from the above resources, I procrastinated on reading more. I didn't feel confident enough whether I knew everything they were going to test me, and information was scarce. A few months later, The Linux Foundation launched a couple of training courses for these exams, so I bought the Node.js Services Development (LFW212) course and studied it.

The course was sufficient for me as the only study material I needed for the exam. In total, it took me a couple of weekends to finish the whole course. The list of chapters is listed on the course page here. The course is targeted to intermediate-level Node.js developers, so if you are a total beginner to backend and Node.js, it might take you a bit longer.

Course review

The course is a written format course (so no video or recordings to watch). It was split into ten chapters with 1 or 2 labs for each chapter. Each lab is a written task (which is similar to the exam task), and you need to download a few JS files that contain some required code for each lab. One of the JS files is a unit testing suite that you can run at the end of your lab to validate if you've implemented the lab requirements correctly.

Here are the pros and cons of the course based on my own opinion:

Pros

I enjoyed the course and mainly because the course author focused on two web frameworks (Express and Fastify) and implemented most examples in each framework to compare the implementation to each other.
The author also did an excellent job explaining the memory leak issues that can arise when using the Express framework with async-await (without a try-catch), so he provided the express examples using callback-style functions.
You have access to the forum to ask questions if you are stuck.
The course is sufficient for the exam but is still well-rounded enough to cover some basics of REST API design in Node.js.

Cons

For an expensive course, I was hoping that the labs can be solved and validated online rather than downloading all files and setting up my local environment.
The topics covered in the Web Security chapters are disappointingly basic and limited. Here's what was covered in the course:
- Preventing HTTP Parameter Pollution
- Validating API requests and response body and structure
- Blocking a specific IP from your application on the code level.
I found the sidebar navigation menu quite annoying as a lot of the sublinks had the same title, so finding a specific part you've read earlier is tricky.

I wish the course had covered more advanced security topics, and the certificate is evolved (or have an advanced level) to test for a broader range of security threats that can affect any Node.js application.

Scheduling the exam

Scheduling the exam was straightforward through the Linux Foundation Portal. I just selected a date and time 2 days in advance. The date and time selection dropdown is super slow, but you can see different daily availabilities on different hours once you get it loaded. The test itself is proctored by PSI.

You will also be asked to download a specific chrome extension so that the proctor can monitor your screen.

Taking the exam

For the exam, I set up an isolated, comfortable free-of-clutter desk in my living room. I logged in 15 minutes before my exam starts and waited for the proctor to show up. The proctor asked me to show my primary ID using the webcam and do a 360 tour of the room with my webcam. After going through some extra screen-sharing checks, I was allowed to start the exam right away.

The remote desktop is accessed through my laptop's Chrome browser tab. The VM's desktop size is viewed full screen on my browser tab. Inside the VM, there is a Chrome browser (which belongs to the VM) that is already open with the list of tasks you have to do. I opened the WebStorm IDE, which immediately opened the list of folders for all of the tasks. I just jumped between each folder in the IDE terminal. I also opened some documentation references via the chrome browser of the VM (not my machine).

The exam went smoothly with no latency issues, and I managed to complete all the tasks in an hour and a half, and I spent the remaining half an hour testing my code again and make sure there were no hiccups.

The results were emailed to me after 24 hours, and I successfully passed the test with a score of 94%. Unfortunately, there is no feedback on the scoring, so I don't know which part I might have implemented wrong.

You also get a digital badge via Credly and a link to a certificate validation tool. The certificate is valid for three years.

Final thoughts

If you are a total beginner to the backend or Node.js, I think the course or exam will be challenging to tackle. If you've already worked with Node.js before, this is an easy exam.

The exam can be an interesting personal learning milestone and help you showcase something to get a first programming job in a Node.js company.

The companion training course is a time saver to help you study faster instead of referring to multiple references. Still, if you want to budget your money and already have some Node.js experience, you can take the exam first as you have a free retake. You can then decide if you want to purchase the course or not.

Nevertheless, I learned a lot from this course. I've worked with Express a lot before, so I primarily learned about Fastify through this course, and I liked it, so now I'll mainly be using Fastify in my future Node.js projects.

Tips summary

Don't forget to cover your Javascript and Node.js basics (e.g., async-await, promises, set timeout, callbacks, package.json, dependencies, npm)
Learn a framework (e.g., Express or Fastify). Implementing the exam tasks with a vanilla Node.js server will take you longer.
Make sure all of your tasks can start running with npm start command.
Don't memorize the code. It's an open book exam, so you can refer to references. However, you will need to study the concepts before. The exam time is not sufficient for you to learn how to implement a GET method if you've never implemented one before.
If you plan to take both certificates, I would recommend starting with the JSNAD if you want to cover most of the Node.js core modules in your learning.
Bonus tip: The Linux Foundation is currently offering a limited-time offer for you to preview the Node.js Certification Testing Environment. You can get a good feel of how the VM test looks like, and you can do a few sample questions. No proctor, and it's not assessed. You can apply for it here.

I also found a few extra tips in this post helpful.

Thank you so much for taking the time to read through my article.

If you enjoyed it or have a question, please let me know in a comment below or reach me on Twitter.

Using PartiQL to query AWS DynamoDb in Javascript

Abdulla T — Mon, 15 Feb 2021 11:12:22 +0000

AWS recently announced a new feature to give users the ability to use PartiQL, which is an SQL compatible query language to work with data in Amazon DynamoDB.

When this was launched, I was initially excited because it means I can write my queries in a more familiar way of SQL-like queries rather than using the Document Client API.

In this article, I would like to compare querying and inserting data into dynamoDb using PartiQL vs. using the Document Client. I will also be touching on the performance and features of using either approach. I will be using the AWS Javascript SDK throughout my Node.js code examples.

Quick introduction to the Document Client and PartiQL

PartiQL

Amazon DynamoDB supports PartiQL, an SQL-compatible query language to select, insert, update, and delete data in DynamoDB. PartiQL operations provide the same availability, latency, and performance as the other DynamoDB data operations. For the PartiQL specification and a tutorial on the core query language, see the PartiQL documentation.

Document Client

DynamoDb Document Client simplifies working with the DynamoDB methods by abstracting away the notion of attribute values. Basically, you can use Javascript objects directly and pass them to DynamoDB methods, and the Document Client will map the Javascript types to the DynamoDB tables.

For example, to get an item from a DynamoDb table, this example below will show the differences in constructing the param object between the Document Client and the DynamoDb direct method.

This example uses the DynamoDB documentClient get method.

const documentClient = new AWS.DynamoDB.DocumentClient();
const params = {
        TableName: "Movies",
        Key:{
            "year": 2020,
            "title" : "A movie"
        }
    };

documentClient.get(params, function(err, data) {
  if (err) console.log(err);
  else console.log(data);
});

And this example below is using the DynamoDB getItem method directly.


const dynamoDb = new AWS.DynamoDB();
const params = {
        TableName: "Movies",
        Key:{
            "year":{
                N: "2020"
            },
            "title" : {
                S: "A movie"
            }
        }
    };

dynamoDb.getItem(params, function(err, data) {
  if (err) console.log(err);
  else console.log(data);
});

Getting started

To follow along with this article and try the examples on your machine, you can clone this Node.js github repo and run the getting started command, which will set up a DynamoDb table and upload sample data to that table. The table and sample data is almost similar to the AWS docs example.

The getting-started command of my example repo will create a simple DynamoDb table called Movies that has a list of movies with the following attributes:

Partition key: year (number)
Sort key: title (string)

I created the table in the US-East-1 region, so if you are following along, you will need to update your region in the example code if you use a different region. At the moment of writing this post, PartiQL is supported in 23 regions as per the announcement post.

If you've setup everything, you should see the following data in your Movies table preview in the console UI.

Querying the data using PartiQL Editor in the console

Before writing any code, let's test the data using the PartiQL editor in the console UI. You will need to use the new console UI preview to see this view.

We can start by writing a simple Select Query as shown below to query all movies from the year 2010.

SELECT * FROM Movies WHERE "year" = 2010;

The above will query the movies table and filter it with the Partition Key "year". Since the partition key is a number, we can pass 2010 as a number without quotes.

Another example below is querying all the movies from 2010, where the movie title contains the word 'and'.

SELECT * FROM Movies WHERE "year" = 2010
  and contains("title", 'and');

Important tips to keep in mind when writing PartiQL statements

Use single quotes for strings.
Use double-quotes for field names, variables, and reserved words.
Don't forget to include a WHERE clause condition that specifies a partition key to avoid having your SELECT statement perform an expensive full table scan. For more information, you can refer to the Select Statement reference.

Side Tip

If you are worried about writing PartiQL queries that can run full table scans accidentally, you can set an IAM policy for your user that locks full table scans. Once your policy is set, your query will return an exception. Read more here.

Using the Javascript SDK to run operations on the table

Now that we have the sample data uploaded in the table and quickly tested the PartiQL editor on the console, let's see how we can use the Javascript SDK to run operations on the table using both the Document Client and the PartiQL statements.

As mentioned above, you can view all the examples below in full, including the necessary try/catch blocks in this Github repository. If you are following the setup to run the same examples on your machine, you can run them using the node command. Refer to the repo readme file.

Querying the table

Example query with the Document Client

Let's start with an example of how a query can be done using the Document Client.


//query-documentAPI.js

const documentClient = new AWS.DynamoDB.DocumentClient();

async function queryWithDocumentClient({year, title}) {
    const params = {
        TableName : "Movies",
        ProjectionExpression:"#yr, title, info",
        KeyConditionExpression: "#yr = :yyyy and title = :title",
        ExpressionAttributeNames:{
            "#yr": "year"
        },
        ExpressionAttributeValues: {
            ":yyyy": year,
            ":title": title
        }
    };

     const results = await documentClient.query(params).promise();
}

In the above example, we form the params object, which contains the following:

ProjectionExpression specifies the attributes you want in the result. In this example, I selected all attributes.
KeyConditionExpression specifies the condition we want our query to use. Notice that we've used an alias '#yr' for the key 'year' because 'year' is a reserved keyword in DynamoDb.
ExpressionAttributeNames lets us map the alias '#yr' to the actual word 'year'.
ExpressionAttributeValues allows us to put the values and map them to the alias keys we wrote in the KeyConditionExpression.

Example query with PartiQL

Let's now see how we can write the same query in PartiQL.


//query-partiQL.js

const dynamoDB = new AWS.DynamoDB();

async function queryWithPartiQL({year, title}) {
    const statement = `SELECT * FROM Movies WHERE "year" = ${year} and "title" = '${title}' `
    const results = await dynamoDB.executeStatement({Statement: statement}).promise();
}

In the above example, we form our SQL statement as a string and then use executeStatement method to run this statement. This will return us the item but with the dynamoDb attribute map, so if we want to convert the first item in the results back to a JS object, we can use AWS.DynamoDB.Converter.unmarshall(results.Items[0]).

Inserting an item to the table

Example insert item with the Document Client

Let's start with an example of how an insert can be done using the Document Client.


//insert-documentAPI.js

const documentClient = new AWS.DynamoDB.DocumentClient();

async function insertWithDocumentClient(movie) {
    const params = {
        TableName: "Movies",
        Item: movie
    };
     await documentClient.put(params).promise();
};

const movieDetails = {
    year: 2020,
    title: "The Big New Movie",
    info:{
        plot: "Nothing happens at all.",
        rating: 0
    }
}

insertWithDocumentClient(movieDetails);

In this approach, inserting a single item with the Document Client is straightforward. We can pass the movie object as a JS object and construct our params object, which we pass to the put method.

You can also add additional keys to the params object such as ConditionExpression if you want to have your PutItem operation run only if a specific condition is met, e.g., attribute_not_exists.

Example insert item with PartiQL

Moving on to the next example, where we insert the same item with PartiQL. I found this part quite interesting when I was coding this example. Initially, PartiQL was constantly throwing an error for a badly formed statement.

The main reason for this issue is that the PartiQL statement expects the data to have strings in single quotes, as we mentioned earlier above. However, when you construct a regular JS object and pass it to another method, the strings become contained in double-quotes instead.

To fix this issue, I parsed the object in a simple DIY custom implementation of a JSON stringifier function, and I modified it to use single quotes instead. I also modified it to escape any single quotes in the text by doubling them. For example, if the movie's title is A bug's life, it becomes A bug''s life, which is how single quotes are usually escaped in SQL.

The code for this stringifier is in the utils folder in my Github repo; however, this is a simple implementation and was made only to demonstrate PartiQL in this blog article, so it doesn't handle a few cases. You might prefer in production to use a good JS library that can safely handle this string parsing to be compatible with PartiQL statements.


//insert-partiQL.js

const { stringify } = require('../utils/stringify')
const dynamoDB = new AWS.DynamoDB();

async function insertWithPartiQL(movie) {
  // stringify object to what PartiQL will accept
  const item = stringify(movie);
  await dynamoDB.executeStatement(
    {
      Statement: `INSERT INTO Movies VALUE ${item}`
    }).promise();
};

const movieDetails = {
    year: 2020,
    title: "The Big New Movie",
    info:{
        plot: "Nothing happens at all.",
        rating: 0
    }
}

insertWithPartiQL(movieDetails);

Batch Insert into a table

In addition to inserting and querying data, let's quickly go over an example for batch insert operations.

Example batch insert with the Document Client

In the Document Client, batch insert can be done using the batchWrite method. This method delegates to the AWS.DynamoDB.batchWriteItem but the advantage of using this Document Client method is that we can use native Javascript types instead of having to specify the DynamoDb attributes types for each field.


//batch-documentAPI.js

const documentClient = new AWS.DynamoDB.DocumentClient();

async function uploadBatchMoviesData(listOfMovies) {
    const items = listOfMovies.map((movie)=> {
        return {
            PutRequest: {
                Item: {
                    year: movie['year'],
                    title: movie['title'],
                    info: movie['info']
                }
            }
        }
    });
    for (let i = 0; i < items.length; i += 25) {
            const upperLimit = Math.min(i + 25, items.length);
            const batch = items.slice(i, upperLimit);
            const params = {
                RequestItems: {
                    'Movies': batch
                }
            };
        await documentClient.batchWrite(params).promise();
     }
};

const listOfMovies = createFakeMovies(500);
uploadBatchMoviesData(listOfMovies);

From the above example, we first iterate over the array list of all the movies to construct the shape of the PutRequest body. We then iterate again over this big array of items and slice 25 items for each batch request. This is because a single call to BatchWriteItem can have as many as 25 put or delete requests, and each item can be as large as 400 KB. Therefore, we will batch 25 movies in each call until we upload the whole list.

The Document Client BatchWrite method delegates to the DynamoDb BatchWriteItem, so there are some caveats which you need to consider:

BatchWriteItem cannot update items (it will replace the whole existing items), so if you want to update each item individually, use the UpdateItem method.
The response you get back from this method will contain an array of unprocessed items if some items failed. However, you will not get an individual response per item. Also, the whole batch write operation might fail even if only one of your items contain a wrong primary key attribute.
You cannot specify conditions on each put request.

For more information on BatchWriteItem, you can refer to the docs.

Example batch insert with PartiQL

PartiQL has some advantages here in batch operations compared to the Document Client. The reason for that is that we can write individual statements for insert and updates and then use the batchExecuteStatement method to run each statement. The other advantage is that we will get an individual response to each statement. However, one limitation is that the entire batch must consist of either read statements or write statements; you cannot mix both in one batch.

We also have the same limitation of 25 items in each batch request.


//batch-partiQL.js

const dynamoDB = new AWS.DynamoDB(listOfMovies);

async function uploadBatchWithPartiQL(listOfMovies) {
    const statements = listOfMovies.map((movie) => {
        const item = stringify(movie);
        return {"Statement": `INSERT INTO Movies VALUE ${item}`}
    })

    for (let i = 0; i < statements.length; i += 25) {
        const upperLimit = Math.min(i + 25, statements.length);
        const batch = statements.slice(i, upperLimit);
        const response = await dynamoDB.batchExecuteStatement({
            Statements: batch
          }).promise();
    }
}

const listOfMovies = createFakeMovies(500);
uploadBatchWithPartiQL(listOfMovies)

Similar to inserting an item using PartiQL, we are stringifying the movie using our custom stringifier method to ensure single quotes are used for strings in the object. We are then simply constructing an SQL statement that we then batch into an array of 25 items each and pass it to the batchExecuteStatement method.

Keep in mind that in both PartiQL or Document Client, if the same batch (the 25 items batch) has a duplicate primary key and sort key, then that whole batch call will fail.

On the other hand, if the duplicate item was inserted in a separate batch, one of the differences between both is that an insert statement using PartiQL batchExecuteStatement will fail for that statement only if the item already exists in the table (same Partition key and sort key). This is not the case with the Document Client batchWrite, which will actually replace the whole item even if it exists.

Performance Comparision

In short, there is no noticeable performance difference between Document Client and PartiQL. Both perform fast and almost take the same duration for the same type of operations. If you run the examples on your machine, you can also see the difference between each operation. I've added a console.log time to most files.

PartiQL would perform as fast as using Document Client, and if you run the same operation multiple times, the differences are less than 100-300 ms between each operation, and in some cases, they would run at the same speed or faster.

One thing to note is the way I wrote my batch write statements examples above will run each batch statement sequentially since we are using a for-loop. However, suppose your table uses on-demand capacity, or you've provisioned your table with a higher write capacity. In that case, it will be very performant for you to write it in a concurrent approach using Promises.all as the example code shown below.

Previously, both Document Client and PartiQL would take 23 seconds to insert up to 500 items. However, using Promises.all, both methods would take less than 1.5 seconds (on my machine) to insert 500 items.


const dynamoDB = new AWS.DynamoDB(listOfMovies);

async function uploadBatchWithPartiQL(listOfMovies) {
    const statements = listOfMovies.map((movie) => {
        const item = stringify(movie);
        return {"Statement": `INSERT INTO Movies VALUE ${item}`}
    })

    let promises = []

    for (let i = 0; i < statements.length; i += 25) {
        const upperLimit = Math.min(i + 25, statements.length);
        const batch = statements.slice(i, upperLimit);
        promises.push(dynamoDB.batchExecuteStatement({
            Statements: batch
          }).promise());
    }

    await Promise.all(promises.map(async(batchCall) => {
         await batchCall
     }))
}

const listOfMovies = createFakeMovies(500);
uploadBatchWithPartiQL(listOfMovies)

Conclusion and should you use PartiQL?

It's up to your comfort level of what you would like to use to decide if you want to include PartiQL in your codebase. There is no performance penalty to use either option. AWS provided PartiQL because AWS naturally likes to provide more than a way to communicate with DynamoDb. They also wanted to provide a tool that provides familiar semantics to access the data.

PartiQL seems to have a slight advantage in batch operations compared to batchWrite from the Document Client, particularly the ability to do batch updates. So if you are extensively working with batch operations, it might be worth looking into if PartiQL will improve your work case.

One question you might have is whether using PartiQL is a good idea with Javascript. I went over the importance of differentiating between single quotes and double quotes, which in JS can be tricky to manage. To manage that for the examples above, I've shown that I had to implement a custom stringifier method to create correct partiQL statements. My answer would be "it depends" whether the appeal of writing your queries in SQL-like format is more than using the Document Client, which is also a great way to run operations on DynamoDb items.

When writing this, the AWS Dynamodb PartiQL documentation only list examples written in Java and AWS CLI. As this is a new feature released, I'm sure AWS will add more support, and maybe the open-source community will add a useful util tool to make Javascript types compatible with partiQL statements.

Further Resources

Do you like working with DynamoDb and want to learn more? Here are some resources I recommend.

DynamoDb DocumentClient cheat sheet by Nader Dabit.
The DynamoDb Book by Alex DeBrie.
Useful tools to make working with DynamoDb easier:
- NoSQL Workbench for DynamoDB: A free client-side GUI application.
- Dynobase: Professional GUI Client for DynamoDB (paid).

I hope you enjoyed this article and learned a thing or two about DynamoDb. Let me know in the comments below or on Twitter of any questions you might have.

Add comments to your blog using GitHub Issues

Abdulla T — Fri, 18 Sep 2020 17:02:34 +0000

Having comments on your personal blogs can help you interact with your readers, and make them feel heard too. They can make your blog posts feel alive, rather than just a one-way interaction.

Of course, having comments in your blog may have some downsides, such as spammy and offensive comments from some trolls. Therefore, it is not advisable to have a very open comment system without a user login feature to deter trolls and bots.

I've seen some people use Disqus, which has a few pros and cons (such as ads or price), and I've also seen some developers build their own firebase-based solutions. However, I wanted to have something simple and free that would also look nice.

I read about Utterances from a blog post by Tania Rascia, who has a brilliant blog that I highly recommend, and I was quite impressed with how easy it is to implement it in my newly built site quickly. It took me a total of 20 minutes to integrate it with my Gatsby blog, so I'll be explaining in this article the steps to follow so you can also add it to your blog easily.

What is Utterances?

It's a free open source app, that will work as a widget in your blog using GitHub issues as the blog comments storage.

It will create a new issue for new posts and put any comments on your posts as comments on that issue itself. You can edit your comment from that GitHub issue too. It's pretty neat.

Is Utterances right for my blog?

Since Utterances stores the comments in GitHub issues, this post assumes that your blog is targeting an audience of developers who would generally have a GitHub account.

Also, if your blog is super popular with high traffic, using this solution might not work for you because the widget might hit the GitHub API rate limit and your comment feature will not work all the time, so keep this in mind for the future.

How does it look like?

Just scroll down to the end of the post on my blog to try it out. You can view the comments and issues here.

Adding Utterances to your blog

Adding Utterances in a standard Html-Js website is a matter of merely adding a simple script. The utterances website documents the easy steps to do this.

// example of embedding this in a non-react app

<script src="https://utteranc.es/client.js"
        repo="[ENTER REPO HERE]"
        issue-term="pathname"
        label="comment"
        theme="github-light"
        crossorigin="anonymous"
        async>
</script>

However, this walkthrough will be about adding Utterances in a react based blog, such as Gatsby or Next.

Here is a summary of the steps to follow:

Setting up the public repository in GitHub.
Install the utterances GitHub app onto the repo.
Add a react component for the comment.
Add a useEffect in the posts component to render the widget.

Step 1: Setting up the public repository in GitHub

You have two options, use an existing repo, or create a new empty repo. Either way, it has to be a public repo. Creating a new repo is better to avoid polluting the issues of your code repo with the comments (though you can add labels to the comments).

In this comments repository, you can also commit a utterances.json file and add the domain of your website. This will prevent other unauthorized websites using your comments repo, which can happen if someone clones your website and forgets to change the utterances script (which we will add below in step 4).

//utterances.json

{
  "origins": [
    "https://yourDomain.tld"
  ]
}

Note: The above file gets committed in the same repository you are using for the comments, not in your blog repository.

Step 2: Install the utterances GitHub app onto the repo

After you have decided which repo you will use, we can go to the utterances GitHub app to install it on our repository.
Just give the app the necessary permissions to read and write to the selected repository only, and we can move on to step 3.

Step 3: Create a react component for the comments container

Now, that we have everything ready, let's create a new component in our blog that we can then use wherever we want to integrate our comments.

//components/Comment.js

import React from 'react'

const Comment = React.forwardRef((props, commentBox) => {
  return <div ref={commentBox} className="comments" />
});

export default Comment;

So, we are simply creating an empty div here but what matters is that we are forwarding the reference ref={commentBox} to this div. React forwarding refs allow us to obtain a ref to the div DOM element, which we will use in the step below.

Step 4: Use the Comments component in our posts template

In this last step, we will need to integrate the Comment component in the place where we want the comments to show. In this example, we will use it in the Post Footer Component. You can directly use it in the post-template file, or anywhere you want.

In a rush: Jump to the end for the final code of this step.

Let's create a ref first in our parent component PostFooter.js.


// PostFooter.js

import React from 'react'

const PostFooter = () => {

    const commentBox = React.createRef();

    return (
        // ...
    )
}

export default PostFooter;

After that, we will be adding a useEffect to create the script element on component mount. I've added some comments to explain the value for each attribute.


useEffect(() => {
  const commentScript = document.createElement('script')

  commentScript.async = true
  commentScript.src = 'https://utteranc.es/client.js'

  // define the name of the repository you created here as 'owner/repo'
  // or import it from your config file if you have one.
  commentScript.setAttribute('repo', siteConfig.commentsRepo)

  // define the blog post -> issue mapping (e.g. page pathname, page url).
  // here the issues will be created with the page pathname as the issue title.
  commentScript.setAttribute('issue-term', 'pathname')

  // define a custom label that you want added to your posts.
  commentScript.setAttribute('label', 'blog-comment')

  // define if you want to use dark or light theme.
  commentScript.setAttribute('theme', 'github-light')

  commentScript.setAttribute('crossorigin', 'anonymous')

  // we will append this script as a child to the ref element we have created above
  if (commentBox && commentBox.current) {
      commentBox.current.appendChild(commentScript)
    } else {
      console.log(`Error adding utterances comments on: ${commentBox}`)
   }

  }, [])

If you have a dark/light theme toggler in your blog, you can still modify this further to allow changing the theme based on your user preference. Let's bring in the theme context which should be implemented somewhere else in your site (I won't go in much detail now on how to implement the theme context, as it's not relevant to this post).


  const { theme } = useThemeContext();

  useEffect(() => {

    const commentsTheme = theme && theme === 'dark'
            ? 'github-dark'
            : 'github-light'

    commentScript.setAttribute('theme', commentsTheme)

   // ...

 }, [theme])

Notice that we added theme as the second argument to the useEffect function. This allows triggering the useEffect function every time the user toggles the theme.

However, there is a catch, as we still need to implement a cleanup on this useEffect(); otherwise, we will end up with multiple comment boxes every time the theme is toggled. To clean up, we need to return a function in the useEffect function, and in that function, we can simply remove the utterances elements from the dom.


  useEffect(() => {

  // ...

  const removeScript = () => {
       commentScript.remove();
       document.querySelectorAll(".utterances").forEach(el => el.remove());
   };

  // clean up on component unmount
   return () => {
     removeScript();
   };

 }, [theme])

Finally, the last step is to render the Comment component we created in step 3 and pass it the commentBox ref.

    ...

    return (
        <>
          <Comment ref={commentBox} />
        </>
      )

    ...

Now you can use the PostFooter component in your post-template or on your page directly.

Final code for step 4

Here is the final cleaned up code for the PostFooter.js file.


// PostFooter.js

import React from 'react'
import Comment from './components/Comment'
import {useThemeContext} from '../context/theme-context';
import {siteConfig} from '../utils/site-config';

const PostFooter = () => {

  const commentBox = React.createRef();

  const { theme } = useThemeContext();

  useEffect(() => {
    const commentScript = document.createElement('script')
    const commentsTheme = theme && theme === 'dark'
            ? 'github-dark'
            : 'github-light'
    commentScript.async = true
    commentScript.src = 'https://utteranc.es/client.js'
    commentScript.setAttribute('repo', siteConfig.commentsRepo)
    commentScript.setAttribute('issue-term', 'pathname')
    commentScript.setAttribute('id', 'utterances')
    commentScript.setAttribute('label', 'comment')
    commentScript.setAttribute('theme', commentsTheme)
    commentScript.setAttribute('crossorigin', 'anonymous')


    if (commentBox && commentBox.current) {
      commentBox.current.appendChild(commentScript)
    } else {
      console.log(`Error adding utterances comments on: ${commentBox}`)
    }

    const removeScript = () => {
      commentScript.remove();
      document.querySelectorAll(".utterances").forEach(el => el.remove());
    };

    return () => {
      removeScript();
    };

  }, [theme])

  return (
    <>
      <Comment ref={commentBox} />
    </>
  )
}

export default PostFooter;

With that implemented, you should now have a commenting feature integrated within your blog. This should be all.

Thank you for reading. I hope you found this post useful.

photo credit:
circle icons PNG Designed By flat**** from Pngtree.com

Like what you read? I just started my new blog (finally) at abba.dev. Head over there to join my newsletter or follow me on twitter to stay updated with new stuff that I write about as a full-stack software developer. You can expect a lot more posts in JS, nodeJs, AWS, system design and probably much more.