Naomi Carrigan - freeCodeCamp.org

Learn React in your Browser – freeCodeCamp Full Stack Curriculum Mid-2025 Update

Naomi Carrigan — Mon, 16 Jun 2025 16:43:56 +0000

Hey campers! The freeCodeCamp community is still very hard at work on the rest of the coursework for our full stack curriculum.

It’s only been a few months, but already there are many campers going full-force through these new lessons and programming challenges.

I’m excited to share our next wave of updates with you all.

New Curriculum Coursework

We have just released three new sections of the curriculum: The React Hooks and State section, the Performance section, and the Testing section.

This new coursework includes:

50 lecture videos
a dozen workshops and labs
three new review blocks
and a bunch of coursework to keep you on track with your learning goals (while we work to finish the remainder of the Full Stack curriculum.)

Some of the projects you’ll build include:

a fully playable Tic Tac Toe game
a color picker
and a superhero application form

Exams

We know many of you are eagerly awaiting the release of the exams at the end of each module. These are nearly ready.

We’re also building our own custom exam environment that you can use to take these exams. This will strike a balance between respecting privacy and preserving academic integrity.

What’s Next?

The community is now focused on the CSS Libraries and TypeScript modules next. We’re also building Python modules.

We have a lot of stuff coming out in the next few months.

A super early sneak peek of some of the projects coming soon:

build your own RPG character
a trading card game
a medical data validator
and more 🏕️

Get Involved

Are you interested in helping bring our full stack curriculum to life? We have plenty of opportunities to contribute – you can see all of the open issues on our GitHub repository.

Start by reading our contributor onboarding guide. Then hop on over to our Discord community with any questions you may have.

We’re stoked to watch you plow through all this new coursework. Keep up the forward momentum with your skills. Happy Coding! 💜

How to Help Someone with Their Code Using the Socratic Method

Naomi Carrigan — Tue, 07 Jan 2025 19:33:01 +0000

As a programming community, freeCodeCamp helps many people who have questions about their code. It can be quite tempting to simply provide the learner with the answer and move on, but that’s actually detrimental to the learning process. Here’s why:

When you give someone the answer, you are depriving them of that “aha” moment. You are removing the opportunity for them to learn how to reach the conclusion through their own thinking, and instead allowing them to progress with minimal effort or thought.

So how can you best help someone with their code?

What is the Socratic Method?

The Greek philosopher Plato was a student of another philosopher, Socrates. In Plato’s works, he often writes about the debates that Socrates would have with his colleagues and students.

Socrates would begin these discussions by raising common beliefs and scrutinizing them to question their compatibility with other beliefs, and guide people to reach the truth.

But how does that translate to our modern day interactions in a digital age?

Let’s consider a real example from one of our communities:

You might be tempted to give them the direct answer, such as this code example:

const sum = nums.reduce((acc, el) => acc + el, 0);

But in doing so, you have performed the logical reasoning on behalf of the learner.

Instead, you should focus on asking pointed questions to guide them to the answer. For example, you might start by asking:

❓ How would you find the sum of a list of numbers on pen and paper, without code?

It may seem counter-intuitive to ask the learner a question that requires them to step away from the code, but you are actually pointing them to the underlying logic behind their question.

Let’s assume the learner responds with something like:

I would go through each number, one by one, and add it to the sum of the previous numbers.

As the learner begins answering your questions, the dialogue should progress in this call-and-response format. Your questions should become increasingly narrow and pointed with the learner’s progress toward the solution.

For example, a series of questions might look like:

Instructor: “Great, now what is an array of numbers?”
Student: “A list?”
Instructor: “Good! How would you iterate through that list?”
Student: “With a for loop.”
Instructor: “And what does your loop need to do on each iteration?”
Student: “Add the current number to the sum.”
Instructor: “Where can you find the sum?”
Student: “I could put it in a variable outside the loop.”
Instructor: “Great, now you’re ready to try writing the code.”
— original example written for this article

At this point, the learner will likely connect the dots and reach the final solution.

Socrates in Modern Culture

Learning the Socratic method is hard. In fact, many do not encounter it until they reach their university studies. But there are examples found in modern pop culture that can help you understand how the Socratic method works.

The TV show House, M.D. is rife with examples. Take this exchange from the episode titled “Three Stories”:

House: “Kidney stones would cause what?”
Student: “Blood in urine.”
House: “What colour is your pee?”
Student: “Yellow.”
House: “What colour is your blood?”
Student: “Red.”
House: “What colours did I use?”
Student: “Red, yellow, and brown.
House: “And brown. What causes brown?”
Student: “Waste”.
— (Frapier, 2008)¹

You’ll notice how this exchange took place. House’s goal here was not to give the learner the answer, but to ask deductive questions to guide the learner to reach the answer on their own.

Consider the popular movie The Matrix:

Morpheus: “Have you ever had a dream, Neo, that you were so sure was real?”
Neo: “This can't be…”
Morpheus: “Be what? Be real?”
Morpheus: “What if you were unable to wake from that dream, Neo? How would you know the difference between the dreamworld and the real world?”
— (Wachowski & Wachowski, 1999)²

In this scene, Morpheus is applying the Socratic method to lead Neo to question his perceptions of reality. This is a rather dramatic example, but the premise remains the same: rather than telling the learner how they should think, you guide them to reach the conclusion through their own volition.

Finally, let’s look at an example from Legally Blonde:

Elle: “Your father was shot while you were in the shower?”
…
Chutney: “Yes. I was washing my hair.”
Elle: “Miss Windham, can you tell us what you'd been doing earlier in the day?”
Chutney: “I got up, went to Starbucks, went to the gym, got a perm, and came home.”
Elle: “Where you got in the shower.”
Chutney: “Yes.”
…
Elle: “…Had you ever gotten a perm before, Miss Windham?”
Chutney: “Yes.”
Elle: “How many, would you say?”
Chutney: “Two a year since I was twelve. You do the math.”
…
Elle: “Chutney, why is it that Tracy Marcinko's curls were ruined when she got hosed down?”
Chutney: “Because they got wet.”
Elle: “That's right. Because isn't the first cardinal rule of perm maintenance that you are forbidden to wet your hair for at least twenty-four hours after getting a perm at the risk of de-activating the ammonium thiglycolate? And wouldn't someone who's had -- thirty perms ? -- throughout her lifetime, be well aware of this rule? And if you, in fact, were not washing your hair, as I suspect you were not, since your curls are still intact, wouldn't you have heard the gunshot?”
—(Luketic, 2001)³

The Socratic method can often be seen in law, and this serves as an excellent example. Through this exchange, Elle is not trying to guide Chutney to reach a conclusion, but rather the spectators (in this case, the jury). This is an important distinction for a community such as ours: where engaging in a Socratic discussion with one member can actually benefit current and future members who may observe or revisit your conversation.

Goal of the Socratic Method

It is important to recognize that the goal of the Socratic method is not to present a quick exchange of information. Instead, the aim is to first get the learner to realize that they know less than they believe they do, then guide them to the answer through questions that elicit certain thought processes.⁴

When applying this to learning programming, then, it’s important to remember the phrase “challenge your assumptions”. We often assume that we know what the code we have written is doing, so our first step when it is not working is to examine those assumptions.

As we guide learners through the process of debugging, we want to ask questions that do the same. A common question in your repertoire should be “What does this line of code do?”. When the learner answers with information that is inaccurate, respond with questions that drill down into smaller components of the code – break the problem into pieces, per se.

Consider this example:

Learner: “but maybe that wouldnt work because I need to find the book not the id in the book”
Instructor: “Correct. Now, the good news is that we have a function that would ostensibly do that. The bad news is that function doesn't do that. What does that function do instead?”
Learner: “returns bookId”
— sourced from our Discord community⁵

By asking the question “What does that function do instead?”, the instructor has provided the direction for the learner to reach the correct conclusion without having to provide any specific information. The learner already knew that the function did not perform as expected, and the instructor asked the question to challenge the learner’s assumption that the function did perform.

Here’s another example:

Instructor: “This is the example from the Chalenge (sic). Did you follow that example they gave?”
Learner: “yes but i didnt understand the for-in loop, i didnt understand "(const food in refigerator)", having to state the string property name with const or let was confusing (it isnt anymore)”
Instructor: “Ok, so lets start here instead of the full solution to the Challenge”
Instructor: “What does that code do when you run it?”
…
Learner: “each of the object's keys were set to the variable food which was made in the for-in loop, it then iterates through the object and logs the key and value assigned to the key?”
— sourced from our Discord community⁶

Again we can see how the instructor focuses on asking pointed questions that guide the user toward the solutions through their own reasoning.

❗ That is the ultimate goal of the Socratic method: to guide the learner to reach the logical conclusion solely through their own reasoning.

Long-Term Benefits of the Socratic Method

The Socratic method is not solely beneficial for resolving the immediate solution. The deductive reasoning process that is applied in this approach can also serve the learner well over the long-term.

The process of asking a learner questions to challenge their assumptions and knowledge, and guide them to the solution, is something that can be internalized as well. It’s a powerful tool to have in your repertoire for approaching debugging, isolating assumptions, and even learning to articulate an issue.

That is, by walking a learner through this call-and-response conversation, the learner can also walk away with the ability to ask themselves these questions. They can take the same process of asking increasingly narrowing questions as a logical pathway and run through it mentally when they encounter future issues with their code (or even in other aspects of life)!

Conclusion

Providing a solution directly to a learner inhibits their intellectual growth and deprives them of the rewarding experience that comes from reaching their own logical conclusion. By leveraging techniques like the Socratic method, we can foster a stronger and more effective educational environment that allows learners to grow and thrive.

💡 If you were sent this article in response to a forum post, Reddit comment, Discord message, or other communication where you gave a fellow learner a working solution, please consider the merits of this method instead.

This approach can seem tedious and lengthy, and at times it is. It is far quicker (and arguably easier) to hand someone the code that resolves their problem.

But that approach, more often than not, harms the learner in the end. And, if you’ll forgive this author for an anecdote, I have seen people get frustrated when they are the subject of a Socratic approach, or lose patience with the back and forth conversation. But I have never seen them upset with or disappointed by that end result – the “aha” moment where they deduce the solution to the problem through their own reasoning.

Sources:

¹ Frapier, M. (2008). Being Nice is Overrated: House and Socrates on the Necessity of Conflict. In House and Philosophy (pp. 100–101). John Wiley & Sons, Inc.
² Wachowski, L., & Wachowski, L. (Directors). (1999, March 24). The Matrix (Z. Staenberg, Ed.). Warner Bros.
³ Luketic, R. (Director). (2001, July 13). Legally Blonde (A. Brandt-Burgoyne, Ed.). MGM Distribution Co.
⁴ Frapier, M. (2008). Being Nice is Overrated: House and Socrates on the Necessity of Conflict. In House and Philosophy (p. 103). John Wiley & Sons, Inc.
⁵ lightskingeneral & plamoni (2024, January 4). [Discord conversation]. Discord. Retrieved 2025, January 6, from https://discord.com/channels/692816967895220344/718214639669870683/1192488621043888198
⁶ lightskingeneral & jeremylt (2023, November 13). [Discord conversation]. Discord. Retrieved 2025, January 6, from https://discord.com/channels/692816967895220344/718214639669870683/1173733715109761065

Special thanks to ArielLeslie and JeremyLT for their help with this article.

How to Claim Your Supporter Role on Discord

Naomi Carrigan — Fri, 12 Apr 2024 19:27:01 +0000

If you have donated to support freeCodeCamp's efforts, you can now claim a special Supporter role in our Discord community.

Claim Your Role

In any channel within our Discord server, type /supporter and you should see a command window pop up.

Click CamperChan's /supporter command, and enter the email address associated with your freecodecamp.org/learn account.

Then, hit enter to submit the command and you should see a success message! You'll now have the role with access to the supporter-only channels.

Error Messages

There are a few error messages you may encounter when claiming this role. For any of these messages, please ping Naomi directly in the server to assist you.

Already Have Role

This error message means you have already been assigned the Supporter role in the Discord server.

Record for Discord Server Exists

This error message means your Discord account has already been granted the Supporter role previously, but you have somehow lost it (for example by leaving the server and rejoining later).

Naomi will need to reset the database entry for you.

Record for Email Exists

This means your email address has already been used by another Discord account to claim the Supporter role. Naomi will give you instructions on how to verify ownership of the email address.

Not a Supporter

This means your curriculum account has not been flagged as having donated. Reach out to Naomi, and she will provide you instructions so she can fix that - make sure to have your latest donation receipt ready.

No freeCodeCamp account

This means the email address you entered does not have a curriculum account associated with it. Double check the spelling, and make sure you are using the email you use to sign in at freecodecamp.org

Thank You

Thanks again for supporting our charity's mission. Your donation will help us continue to provide free learning resources to millions of people around the world.

Hacktoberfest 2023 Contributors

Naomi Carrigan — Fri, 03 Nov 2023 00:03:39 +0000

The freeCodeCamp community just finished participating in this year's Hacktoberfest – a month-long celebration of open source.

Our core team is excited to recognize all of our wonderful open source contributors. A big thank you to all of these folks for the effort they put into helping improve our curriculum and learning resources.

Thank you for your contributions to open source. 🎉

Hacktoberfest Contributions for freeCodeCamp

Sboonny made 15 valid contributions
huyenltnguyen made 12 valid contributions
ojeytonwilliams made 11 valid contributions
raisedadead made 7 valid contributions
gikf made 7 valid contributions
Riya267 made 7 valid contributions
dzmdre made 7 valid contributions
anand-harsh made 6 valid contributions
raditotev made 5 valid contributions
shabeebk made 5 valid contributions
ShaunSHamilton made 4 valid contributions
jdwilkin4 made 4 valid contributions
bbsmooth made 4 valid contributions
Ann-Cherian made 4 valid contributions
rohitrai3 made 4 valid contributions
naomi-lgbt made 4 valid contributions
sitek94 made 4 valid contributions
Yash-Ambekar made 3 valid contributions
moT01 made 3 valid contributions
ieahleen made 2 valid contributions
weilirs made 2 valid contributions
AidanLDev made 2 valid contributions
andrianarivo made 2 valid contributions
aotulana made 2 valid contributions
Nirajn2311 made 2 valid contributions
IgorShcherba made 2 valid contributions
Aman1919 made 2 valid contributions
lasjorg made 2 valid contributions
EggSaled made 2 valid contributions
stweil made 2 valid contributions
Web-Dev-Codi made 1 valid contribution
tmsagarofficial made 1 valid contribution
onukwilip made 1 valid contribution
Angad-Godara made 1 valid contribution
hairyputtar made 1 valid contribution
a2937 made 1 valid contribution
mdrizwanfk made 1 valid contribution
0xLBlaze made 1 valid contribution
avncharlie made 1 valid contribution
joshalling made 1 valid contribution
shoaib-31 made 1 valid contribution
lalithasj made 1 valid contribution
lakshmi930 made 1 valid contribution
Insidiae made 1 valid contribution
RickDeb2004 made 1 valid contribution
gerhynes made 1 valid contribution
devuser200 made 1 valid contribution
justynakantyka made 1 valid contribution
ArjunSingh-Rawat made 1 valid contribution
IamAyaanSk made 1 valid contribution
MojoBoingo made 1 valid contribution
Vedaant-Rajoo made 1 valid contribution
kensiecodes made 1 valid contribution
Elya29 made 1 valid contribution
leonfeng made 1 valid contribution
BiaDd made 1 valid contribution
mribeirodantas made 1 valid contribution
dipushrestha made 1 valid contribution
Ukarus made 1 valid contribution
NeetigyaPod made 1 valid contribution
arujjval made 1 valid contribution
pushkar707 made 1 valid contribution
umangbp made 1 valid contribution
FarisKarim made 1 valid contribution
Tauseef-Hilal made 1 valid contribution
Om-Aditya-Jain made 1 valid contribution
shootermv made 1 valid contribution
KyleGrande made 1 valid contribution
amitabh-sahu made 1 valid contribution
MrBrain295 made 1 valid contribution
samiralibabic made 1 valid contribution
wahmd made 1 valid contribution
grbknr1996 made 1 valid contribution
pankildoshi made 1 valid contribution
Subhrajit-Dutta made 1 valid contribution

Hacktoberfest Contributions for DevDocs

simon04 made 4 valid contributions
thewheat made 2 valid contributions
icai made 1 valid contribution
JuanVqz made 1 valid contribution
ojeytonwilliams made 1 valid contribution

Thank you to all of these contributors! If you are interested in becoming a contributor as well, we recommend starting with our contributing guidelines. If you have any questions feel free to ask us in our Discord server.

Hacktoberfest 2022 Contributors

Naomi Carrigan — Fri, 11 Nov 2022 20:25:10 +0000

freeCodeCamp participated in Hacktoberfest (a month-long celebration of open source) again this year.

We wanted to take a moment to thank all of our wonderful contributors for the effort they put in to help us continue to improve our curriculum and learning resources.

Thank you for your contributions to open source. 🎉

Hacktoberfest Contributions for freeCodeCamp

raisedadead made 16 valid contributions
Sboonny made 11 valid contributions
nayabatir1 made 11 valid contributions
naomi-lgbt made 10 valid contributions
ojeytonwilliams made 10 valid contributions
DerrykBoyd made 5 valid contributions
sidemt made 4 valid contributions
Prince-Mendiratta made 4 valid contributions
KravMaguy made 3 valid contributions
ahmadabdolsaheb made 3 valid contributions
jeremylt made 3 valid contributions
scissorsneedfoodtoo made 3 valid contributions
ShaunSHamilton made 3 valid contributions
moT01 made 3 valid contributions
k-rajat19 made 3 valid contributions
WizardLemon made 2 valid contributions
JustARatherRidiculouslyLongUsername made 2 valid contributions
hbar1st made 2 valid contributions
AndrewDawes made 2 valid contributions
saw-jan made 2 valid contributions
zairahira made 2 valid contributions
nouredinateur made 1 valid contribution
Yash-Pratapwar made 1 valid contribution
miyaliu666 made 1 valid contribution
Rancho2002 made 1 valid contribution
DylanDevelops made 1 valid contribution
jctello made 1 valid contribution
disabledandfab made 1 valid contribution
mmatsumoto1026 made 1 valid contribution
RohitPatel1122 made 1 valid contribution
HatimZ made 1 valid contribution
footedroom575 made 1 valid contribution
dojutsu-user made 1 valid contribution
denquinlan made 1 valid contribution
Aman-zishan made 1 valid contribution
myankpraksh made 1 valid contribution
michpara made 1 valid contribution
Kroustille made 1 valid contribution
saiharvin made 1 valid contribution
KeshariPiyush24 made 1 valid contribution
Florenciasicre made 1 valid contribution
mehdibouaziz made 1 valid contribution
carrotfarmer made 1 valid contribution
PakkuDon made 1 valid contribution
aniketsinha2002 made 1 valid contribution
anubhav823 made 1 valid contribution
Ayush-singla27 made 1 valid contribution
paulaxisabel made 1 valid contribution
rffontenelle made 1 valid contribution
Anuran12 made 1 valid contribution
surajrane42 made 1 valid contribution
Nirajn2311 made 1 valid contribution
sadikkuzu made 1 valid contribution
void-hr made 1 valid contribution
alekzandriia made 1 valid contribution
webpro made 1 valid contribution
lmssr made 1 valid contribution
JoseDeFreitas made 1 valid contribution
Saul-BT made 1 valid contribution
Prathamesh010 made 1 valid contribution
krupalitrivedi made 1 valid contribution
aryandeelwal made 1 valid contribution
friendofdog made 1 valid contribution
NiharPhansalkar made 1 valid contribution
dannygr664 made 1 valid contribution
bbsmooth made 1 valid contribution
Weredime made 1 valid contribution
tanmaythakral made 1 valid contribution
prajwal-144 made 1 valid contribution
fzs1994 made 1 valid contribution
adripo made 1 valid contribution
panoreak made 1 valid contribution
erkanzileli made 1 valid contribution
Insidiae made 1 valid contribution

Hacktoberfest Contributions for DevDocs

simon04 made 7 valid contributions
thewheat made 3 valid contributions
fabianchoxD made 2 valid contributions
ClasherKasten made 1 valid contribution
JuanVqz made 1 valid contribution
gonglexin made 1 valid contribution
axelf4 made 1 valid contribution
TomerPacific made 1 valid contribution

Thank you to all of these contributors! If you are interested in becoming a contributor as well, we recommend starting with our contributing guidelines, and if you have any questions feel free to ask us in our Discord server.

How to Set Up Your Own Mastodon Instance

Naomi Carrigan — Fri, 11 Nov 2022 16:29:20 +0000

Mastodon is a decentralized, federated social media platform based on the ActivityPub protocol. It allows you to follow and interact with friends across multiple instances.

In this article, you will learn how freeCodeCamp set up our own Mastodon instance - and how you can too.

What is Mastodon?

Imagine if there were multiple different websites for Twitter. On each of those websites, you could create an account (create one on all of them, if you were feeling ambitious).

You could then use your account to follow any of your friends on any of the other websites. You could repost their content to your account, and see activity from all of your followed accounts on a single timeline.

While Mastodon is by far the most popular platform to use, there are also other options such as Misskey, Pleroma, and their various forks.

Some of these platforms will be able to federate with each other, with cross-platform capabilities, while others will not.

Getting Started with Mastadon

There are a couple of things you will need to get started with the process we followed for freeCodeCamp:

A DigitalOcean account
A DNS provider (we use Cloudflare).

Begin by logging in to DigitalOcean and creating a new droplet. In the image options, select the marketplace tab. Then, search for the Mastodon image - this will handle a good portion of the setup for you.

Configure the rest of the droplet settings to your own needs - for the size, we began with the $12 option with the plan to scale up as necessary.

Once the droplet has finished provisioning, copy the IP address. Set up an A record for your domain or subdomain to point to your droplet - do this BEFORE you SSH into the droplet.

Once your DNS is ready, SSH into the droplet as the root user.

How to Set Up Your Mastadon Instance

When you first SSH into the server, the automatic setup tool will run.

Follow the prompts:

For Domain name, enter the new domain/subdomain record you just set up.
The tool will ask if you want to store user-uploaded files on the cloud. If you do, you'll need to provide credentials for a storage provider such as Amazon S3.
Mastodon requires an SMTP server for email notifications and the registration flow. You can either spin up your own, or provide credentials for a service like SendGrid.
The SMTP flow will prompt you to send a test email. This is highly recommended, as this will confirm your SMTP settings are correct. If they are not, the setup wizard will prompt you to re-enter them.

You will next create a Mastodon account to serve as the administrator. This can be your personal account, or it can be a shared account among your team.

Finally, you'll be prompted to enter your email for LetsEncrypt certificate renewal notifications.

After a few minutes, your instance should be up and running.

How to Configure Your Mastadon Instance

Visiting your new domain/subdomain should display the Mastodon landing page.

Sign in using the admin credentials you generated earlier. Then, select Preferences on the right sidebar, followed by Administration -> Site Settings on the left.

Here you can configure the basic information related to your instance, and upload your branding assets.

These will be displayed on your instance's /about page, shown to users when they register/login (and available in the footer).

When you are ready to start accepting user sign-ups, change the Registration mode setting to either Anyone can sign up or Approval required for sign up.

How to Manage Users

Under the Moderation -> Accounts tab in the settings, you can see registered and pending users.

If you click on a username, you will be taken to the user management view.

From this screen, you can manage their permission level (that is, grant moderation or admin status), check IP information, and block email domains.

Your moderation team can also leave private notes (only visible to the team) on a user account, to help keep a history of any moderation concerns.

Conclusion

Now that your instance is up and running, feel free to poke around the settings and interaction options. For more information on the various options, check out the official documentation.

You can find the freeCodeCamp core team and volunteer moderators on our private instance, where you can follow us from the instance you just created.

Enjoy your new platform, and happy coding!

Cover image from Mastodon's branding update page.

How to Set Up a GitHub OAuth Application

Naomi Carrigan — Thu, 27 Oct 2022 21:31:36 +0000

GitHub is an incredibly useful OAuth provider, especially if you are building an application targeted toward developers.

In this article, we will give you a quick rundown of how to set up a GitHub OAuth application.

Create Your Application

Begin by navigating to your GitHub settings (make sure you are logged in!). Scroll down to the bottom of the sidebar and click "Developer Settings".

This will take you to the application page:

You may see some applications you've previously authorised.

Click the "New OAuth App" button to create a new application.

Fill in the form and click "Register application". This will create your application and take you to the settings page.

For OAuth applications, you will need the Client ID. You will also need to generate a client secret. Click the "Generate a new client secret" to do so.

Make sure to save this secret in a secure location as you will not be able to view it again.

Using Your New Application

Now that you have a client ID and secret, you can use your OAuth application in your project.

If you want to learn how to do so, freeCodeCamp's curriculum can teach you.

Happy coding!

How to Use RegEx to Match Emoji – Discord Emotes Regular Expression Tutorial

Naomi Carrigan — Wed, 13 Jul 2022 23:04:07 +0000

Emoji are special Unicode characters that render pictographs. But these characters can be very tricky to identify with regular expressions (RegEx).

I was recently working on a Discord bot that had to detect the number of emotes in a given message. Today I'll share my process with you, including the newer JavaScript RegEx feature that finally solved the issues I was having.

How Unicode Emoji Work

The Unicode Consortium defines specific character codes for each emoji. They even maintain a helpful emoji chart as a reference. As an example, U+1F600 corresponds to the 😀 emoji.

Some emoji consist of multiple Unicode characters. This is most common with the flag emoji, which consists of the "regional indicators" that make up the country's two-letter country code.

This means the United States flag, 🇺🇸, consists of the two Unicode characters U+1F1FA and U+1F1F8, which correspond to the regional indicators U and S.

As a fun fact, it is up to the operating system to determine how to render an emoji. If you are on Windows, for example, you won't see a flag above. You'll see US.

What are Discord Emotes?

One of Discord's many features is allowing communities to upload their own custom emotes. These emotes are identified by a name, and are used with the syntax :emote_name:.

However, the way they are identified by the client/API is different. Each emote has a unique ID, and they're sent in the message content as <:emote_name:1234567890>, or for animated emotes.

You can see this in Discord by putting a backslash \ before the emote and sending it. It will render something like this:

`" width="600" height="400" loading="lazy">

How to Match Emoji and Emotes with RegEx

My original approach had two different RegEx phrases.

I was using /()?/g to catch the Discord emotes. This RegEx was successfully picking up Discord emotes, which was great!

I paired it with /:[^:\s]*(?:::[^:\s]*)*:/g to match the Unicode emoji, which only partially worked. The problem here was that I was seeing some emotes being counted twice – because the Discord RegEx was matching them. And others were being missed entirely.

So, with RegEx being what it is, I tried to make it more complex. <:[^:\s]+:\d+>||(\u00a9|\u00ae|[\u2000-\u3300]|\ud83c[\ud000-\udfff]|\ud83d[\ud000-\udfff]|\ud83e[\ud000-\udfff]|\ufe0f)/g was a bit more successful in matching the built-in emoji, but still wasn't perfect. This RegEx was designed to match unicode characters specifically.

I played around with trimming whitespace, using the word boundary \b character, and a few other tweaks, before finally giving up and doing some research.

And then I discovered Unicode Property Escapes. This RegEx feature allows you to add the u flag to your RegEx, unlocking the Unicode Properties denoted with the \p character.

With some additional research, I was able to find the Emoji Character properties – specifically, the Extended_Pictograph property. This enabled me to update the RegEx to a final, functional value:

/<a?:.+?:\d{18}>|\p{Extended_Pictographic}/gu

The \p{Extended_Pictographic} property seems to match Unicode emotes as well as character modifiers (often used for skin tones in emoji).

Conclusion

This RegEx is currently running in my production code and hasn't shown any issues yet.

Hopefully this article has helped you. If you are interested in exploring Unicode Property Escapes further, the Unicode Consortium offers a full list of the available values.

Happy Coding!

Build a 100 Days of Code Discord Bot with TypeScript, MongoDB, and Discord.js 13

Naomi Carrigan — Mon, 31 Jan 2022 21:41:05 +0000

The 100 Days of Code challenge is very popular among new coders and developers looking to level up their skills. It's so popular that our Discord server has an entire channel dedicated to it.

By popular demand, we built a Discord bot that helps people track their progress in the challenge.

Today I am going to show you how to build your own 100 Days of Code bot.

Note that discord.js has released version 14, which includes breaking changes. For compatibility with this tutorial, you will want to ensure you are using discord.js 13 - you can install this with npm install discord.js@13. If you have any questions, feel free to join my discord server.

Contents

How to Add Sentry to Your Node.js Project with TypeScript

Naomi Carrigan — Tue, 28 Sep 2021 16:24:26 +0000

Sentry.io is an external monitoring and logging service which can help you identify and triage errors in your code.

These logs provide information such as a trace stack, breadcrumbs, and (assuming this is a web application) browser data. This can help you triage issues and resolve bugs faster, with less investigative overhead.

How to Prepare Your Sentry Account

Begin by navigating to Sentry and clicking "Get Started". You will be taken to the account creation screen:

You can either sign up with OAuth or create separate credentials for Sentry. If you choose to create separate credentials, you'll need to enter an organization name now (this can be changed later). I used my username as my organization name.

Once you create your account, Sentry will take you through a tutorial to set up your first project. Click "I'm Ready" to be taken to the first step.

For our purposes, the NODE.JS option is the platform you should select. Then click "Create Project".

This takes you to the instructions for preparing the SDK to integrate with your codebase. Leave that page open as you will need your dsn value.

How to Use Sentry in Your Code

Your next step is to install the necessary Sentry packages:

npm install @sentry/node @sentry/integrations

The @sentry/node package is the core SDK for your Node.js project, and the @sentry/integrations package contains a tool you will use for mapping the file path.

Your Sentry tooling should be loaded as early as possible in your code flow. Ideally, this means you should initialize it within the entry point for your application (that is, index.ts).

Start by importing the packages:

import * as Sentry from "@sentry/node";
import { RewriteFrames } from "@sentry/integrations";

The first import pulls in the Sentry-Node tooling, and the second gives you access to the RewriteFrames integration. This integration allows you to adjust the pathing of the stack trace, which is necessary for properly pointing to your compiled JavaScript files.

Now you need to instantiate the Sentry monitor and provide the configuration:

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  tracesSampleRate: 1.0,
  integrations: [
    new RewriteFrames({
      root: global.__dirname,
    }),
  ],
});

Here you have passed a configuration object to the Sentry.init() method (which is used to instantiate and initialise the Sentry process). To break these options down:

dsn is a unique URL used to connect your Sentry instance to your dashboard. We will explore this a bit later.
tracesSampleRate determines the percent of events the monitor should send to the dashboard. A value of 1.0 sends 100% of the captured events – but if you find this to be too noisy you can reduce this number.
integrations loads the integrations you want to use. In this case, you are loading the RewriteFrames option and setting the root path for your stack traces to global.__dirname (which resolves to the directory you run your application from).

Then, anywhere in your code base where you are logging errors (such as a try / catch block or a .catch() chain), add Sentry.captureException(error) (replacing error with the variable that represents your error object) to pass that error off to your Sentry monitor.

How to Connect Your Code to Your Dashboard

Back on that project setup page, you'll see a URL value for the dsn option in the configuration.

Your dsn should be treated as a secret and not shared with anyone. You can achieve this by adding it to your .env file (assign it to SENTRY_DSN to match with our configuration from the previous step).

The dsn tells Sentry where to send the captured errors, and the dashboard uses it to link those errors to your new project.

A note for front end projects:
Because you do not have access to a .env on the front end, you will need to expose your dsn publicly. We will cover how to handle this in the next step.

Once this is set up, you can click "View a sample event for this SDK" in the small print at the bottom of the Sentry page. This will generate a fake error event and take you to the dashboard.

How to Configure Your Sentry Dashboard

The Sentry website will offer you a quick tour of the dashboard, which you can follow if you would like, or you can skip it and continue with this article.

This view shows you the specific details for a captured error event. In this case, it is the sample event generated by Sentry from the previous step.

The top half offers information such as the browser data from the user that triggered the error, the error message, and the error type. The bottom half provides the stack trace and breadcrumbs (actions that took place to trigger this error) – both helpful for reproducing this error in triage.

At the very top you should see your project's name (which defaults to your organization name) and a gear. Click that gear to be taken to your project's settings.

Here you see some configurations for your project. The "Name" determines the name of your project. Changing the "Platform" affects how stack traces are rendered. You are welcome to experiment with the other settings as desired.

For front-end projects:
As mentioned earlier, you will need to expose your DSN publicly. You can set your webpage's URL in the "Allowed Domains" to prevent data being sent from any other source.

On the side bar are a few additional options. Selecting "Client Keys(DSN)" will take you to a page where you can copy your DSN again, if needed. You can also delete and regenerate it if you accidentally exposed it.

Selecting "Alerts" will allow you to configure how you receive notifications for error events. I have mine set to send to a Discord Webhook, but you can configure a number of integration options for receiving your alerts.

Finally you have the main side bar. Here you can configure your organization settings, including renaming your organization or creating additional organizations and projects.

Conclusion

You have now successfully integrated Sentry with your Node.js-Typescript project. You are now ready to start receiving error information, triaging issues, and improving your project's stability.

Feel free to experiment with Sentry's settings and features to personalize your experience to meet your needs. Happy Coding!

How to Use TypeScript and MongoDB to Build a 100 Days of Code Discord Bot

Naomi Carrigan — Tue, 22 Jun 2021 16:20:36 +0000

The 100 Days of Code challenge is very popular among new coders and developers looking to level up their skills. It's so popular that our Discord server has an entire channel dedicated to it.

By popular demand, we recently built a Discord bot that helps people track their progress in the challenge.

Today I am going to show you how to build your own 100 Days of Code bot.

How to Create a Discord Bot Application

Your first step is to set up a Discord bot application. Head over to the Discord Developer Portal, sign in if needed, and select "Applications" from the sidebar.

Screenshot of the Developer Portal. If this is your first bot, you will not have any applications here.

Click the "New Application" button. Give it a name, and set it as a "Personal" application. You will now be taken to the application's settings. Here you can change the name, or give it an avatar.

Select "Bot" from the side bar, then click the "Add Bot" button. This will create a Discord Bot account for your application.

Screenshot of the Bot settings page. If you did not set an avatar, you will see a default based on your bot's name.

This is the screen where you will get the bot token. It is very important to keep this token secret, as the token allows your code to connect to your bot. Keep it safe and do not share it with anyone.

Now you need to add the bot to a server to interact with it. Click the "OAuth2" option on the side bar. You should see a form under the "OAuth2 URL Generator" section. Leave the "Select Redirect URL" dropdown blank, and check the box for the "bot" scope.

An option to select permissions will appear. Check the boxes for the following permissions:

Send Messages
Manage Messages
Embed Links
Read Message History
View Channels

Above that section, you should see a URL generated. Click the "Copy" button to copy it, then paste it into your browser and go.

This will take you through Discord's process to add your new bot to a server. Note that you must have the Manage Server permission in the server you want to add the bot to. If you do not have this permission in any servers, you can create a server to test your bot in.

Screenshot of the OAuth screen with the correct settings marked.

Now you are ready to write some code!

How to Set Up Your Project

You need to set up the infrastructure and tooling for your project.

Prepare the `package.json`

Create a directory, or folder, for your project. Open your terminal pointing to that new folder. Run the command npm init to set up your package.json file. For this tutorial, the default values are sufficient, but feel free to edit them as you wish.

You should end up with a package.json similar to this:

{
  "name": "tutorial",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC"
}

Now you need to make a couple of changes to get ready for the TypeScript implementation.

First, replace the main value of index.js with ./prod/index.js – you will be setting your TypeScript to compile to a prod directory.

Then, remove the test script and add the following two scripts:

"build": "tsc",
"start": "node -r dotenv/config ./prod/index.js"

The build script will compile your TypeScript into JavaScript so node can run it, and the start script will run the index.js entrypoint file.

Adding the -r dotenv/config here will dynamically import and run the config method in the dotenv package, which loads your environment variables from the .env file.

Speaking of packages, your next step is to install dependencies. Using npm install, install these dependencies:

discord.js – this is the library that will handle connecting to the gateway and managing the Discord API calls.
dotenv – a package that loads .env values into the node process.
mongoose – A wrapper for the MongoDB connection which offers tools for structuring your data.

Finally, install the development dependencies with npm install --save-dev. Development dependencies are packages that are required for working on your project in a development environment, but not required for running the codebase in production.

typescript – This is the package for the TypeScript language, which includes everything needed to write code in TypeScript and compile it into JavaScript.
@types/node – TypeScript relies on type definitions to help understand the code you write. This package defines the types for the Node.js runtime environment, such as the process.env object.

With these packages installed, you should now have a package.json similar to this:

{
  "name": "tutorial",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "build": "tsc",
    "start": "node -r dotenv/config ./prod/index.js"
  },
  "author": "",
  "license": "ISC",
  "dependencies": {
    "discord.js": "^12.5.3",
    "dotenv": "^10.0.0",
    "mongoose": "^5.12.14"
  },
  "devDependencies": {
    "@types/node": "^15.12.2",
    "typescript": "^4.3.4"
  }
}

Prepare TypeScript

TypeScript's compiler offers a number of different settings to maximize your control over the resulting JavaScript.

You can typically modify compiler settings through a tsconfig.json file at the root of your project. You can generate the default boilerplate for this file with npx tsc --init, use an existing one if you set one up in another project, or even write one from scratch.

Because the compiler settings can significantly change the behaviour of TypeScript, it is best to use the same settings when following this tutorial. Here are settings you should use:

{
  "compilerOptions": {
    "target": "ES6",
    "module": "CommonJS",
    "rootDir": "./src",
    "outDir": "./prod",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true
  }
}

The most important settings here are the rootDir and outDir settings. These tell the compiler that all of your code will be in the src directory, and the resulting JavaScript should go in the prod directory.

If you would like to test your settings, create a src directory and place an index.ts file inside. Write some code (such as a console.log statement) and run npm run build in your terminal. You should see a prod directory get created, with an index.js containing your compiled code.

Additional Setup Notes

If you are using git as a version control, you want to avoid pushing secrets and unnecessary code to your repository. Create a .gitignore file in your root project directory, and add the following content:

/node_modules/
/prod/
.env

The .gitignore file tells git not to track files/folders that match the patterns you enter. Ignoring the node modules folder keeps your repository from becoming bloated.

Pushing the compiled JavaScript is also unnecessary, as your project is typically compiled in production before runtime. .env files typically contain your secret values, such as API keys and tokens, so they should not be committed to a repository.

If you are using a UNIX based environment (such as Linux, or Git Bash on Windows), you can also add a prebuild script to your package.json. The prebuild script will automatically run before the build script when you use npm run build. I set mine to clean up the existing prod directory with rm -r ./prod.

How to Create the Discord Bot

Your next step is to prepare the initial bot connection. If you did not do so earlier, create a src directory and an index.ts file within.

Start with an anonymous immediately-invoked function expression (IIFE) to allow for top-level await use:

(async () => {

})();

Within this function you are going to instantiate your Discord bot. At the top of the file, import the Client class with import { Client } from "discord.js;". The Client class represents your Discord bot's session.

Inside your function, construct a new Client instance and assign it to a BOT variable with const BOT = new Client();. Now the BOT variable will represent your bot.

To connect your bot to Discord's gateway and begin receiving events, you will need to use the .login() method on your bot instance. The .login() method takes a single argument, which is the token for the bot application you created earlier.

Many of the methods in discord.js are asynchronous, so you will need to use await here. Add the line await BOT.login(process.env.BOT_TOKEN); to your IIFE.

The process.env object will contain the environment variables for your Node.js runtime environment. With the dotenv package, this will also include any variables you set in your .env secrets file.

Create that .env file in the root of your project, and add BOT_TOKEN="" as the first line. Between the quotes, paste the bot token from the bot page on the Discord Developer Portal.

Your index.ts file should now look like this:

import { Client } from "discord.js";

(async () => {
  const BOT = new Client();

  await BOT.login(process.env.BOT_TOKEN);
})();

Assuming you added your new bot to a server, if you run npm run build and npm start you should see your bot come online in the server. However, the bot will not respond to anything yet, because we have not started listening to events.

Gateway Events in Discord

Gateway "events" are generated when an action happens on Discord, and are typically sent to clients (including your bot) as JSON payloads. You can listen to those events with the .on() method, allowing you to write logic for your bot to follow when specific events occur.

The first event to listen to is the "ready" event. This event fires when your bot has connected to the gateway and is ready to process events. Above your .login() call, add BOT.on("ready", () => console.log("Connected to Discord!"));.

For your changes to take effect, use npm run build again to compile the new code. Now if you try npm run start, you should see "Connected to Discord!" print in your terminal.

How to Connect to the Database

You'll be using the mongoose package to connect to a MongoDB instance. If you prefer, you can run MongoDB locally, or you can use the MongoDB Atlas free tier for a cloud-based solution.

If you do not have a MongoDB Atlas account, freeCodeCamp has a great tutorial on setting one up.

Grab your connection string for your database and add it to your .env file as MONGO_URI="", with the connection string going between the quotes. For the database name, use oneHundredDays.

Create a directory called database to hold the files that contain your database logic. Within that directory, create a file called connectDatabase.ts. You will be writing your logic to initiate the database connection here.

Start with an exported function declaration:

export const connectDatabase = async () => {

}

mongoose offers a connect method for connecting to the database. Import it with import { connect } from "mongoose"; at the top of your file.

Then use the method inside your function with await connect(process.env.MONGO_URI);. Add a console.log statement after that so you can identify that your bot has connected to the database.

Your connectDatabase.ts file should now look something like this:

import { connect } from "mongoose";

export const connectDatabase = async () => {
    await connect(process.env.MONGO_URI);
    console.log("Database Connected!")
}

Now, within your index.ts file, import this function with import { connectDatabase } from "./database/connectDatabase" and add await connectDatabase() to your IIFE, just before the .login() method. Go ahead and run npm run build again.

A compiler error, indicating that: Argument of type string or undefined is not assignable to parameter of type string.

Oh no – an error!

Environment Variable Validation

The problem with environment variables is that they can all be undefined. This often happens if you make a typo in your environment variable name, or mix the name up with another name (a mistake I made when writing this tutorial, using TOKEN instead of BOT_TOKEN in some places).

TypeScript is warning you that the connect method takes a string, and that an undefined value will break things. You can fix this, but first you will want to write a function to handle validating your environment variables.

Within your src directory, create a utils directory to contain your utility functions. Add a validateEnv.ts file there.

Create a function in the file called validateEnv. This function will be synchronous and does not need the async keyword. Within that function, add conditions to check for your two environment variables. If either one is missing, return false. Otherwise, return true.

Your code might look something like this:

export const validateEnv = () => {
  if (!process.env.BOT_TOKEN) {
    console.warn("Missing Discord bot token.");
    return false;
  }

  if (!process.env.MONGO_URI) {
    console.warn("Missing MongoDB connection.");
    return false;
  }
  return true;
};

Head back to your index.ts file and import this validation function with import { validateEnv } from "./utils/validateEnv". Then at the beginning of your IIFE, use an if statement to return early if the function returns false. Your index.ts should look like:

import { Client } from "discord.js";
import { connectDatabase } from "./database/connectDatabase";
import { validateEnv } from "./utils/validateEnv";

(async () => {
  if (!validateEnv()) return;

  const BOT = new Client();

  BOT.on("ready", () => console.log("Connected to Discord!"));

  await connectDatabase();

  await BOT.login(process.env.BOT_TOKEN);
})();

If you try npm run build again, you will see the same error message as before. This is because while we know the environment variable exists, TypeScript still cannot infer it. The validation function is set up to exit the process if the environment variable is missing, so we are going to tell TypeScript that it is definitely a string.

Back in your connectDatabase.ts file, within the connect function use process.env.MONGO_URI as string to coerce the type into string. The error should go away, and you can now run npm run build and npm start.

You should see the messages you wrote for both the Discord and MongoDB connections print in your terminal.

The "message" Event

While you are making great progress on your bot, it still does not do anything. In order for the bot to respond to messages, you will need another event handler.

The logic in this one will be a bit more complicated, so you should create a separate module for it. Create an events folder in the src directory.

Within your events folder, create an onMessage.ts file. At the top, import the Message class from discord.js with import { Message } from "discord.js";. This class will serve as your type definition.

Then create an exported function called onMessage. The function should be asynchronous and take a message parameter with the Message type. Your function will look like this:

import { Message } from "discord.js";

export const onMessage = async (message: Message) => {

};

Before diving in to the logic for this function, you should attach it to the event listener. Back in your index.ts file, import your new function with import { onMessage } from "./events/onMessage";.

Next to your existing .on("ready") listener, add a BOT.on("message") listener. For the "message" event, the callback takes a message argument which you can pass to your new onMessage function:

BOT.on("message", async (message) => await onMessage(message));

We should test that this works. Head back to your onMessage.ts file. Inside your onMessage function, add console.log(message.content). The .content property on the Message class contains the text content sent in the message.

Use npm run build and npm start to get your bot running again, and then send "Hello" in a Discord channel the bot can see. You should see "Hello" print to your terminal.

How to Prepare for Commands

I maintain a few Discord bots, and one thing I've discovered that helps keep code maintainable and readable is making the components modular.

Define an Interface

You will first need to define a common structure for your commands. Create an interfaces folder in src. Then inside interfaces create a file CommandInt.ts.

Now you are going to create an interface. In TypeScript, an interface is often used to define the structure of an object, and is one of many tools available for declaring a variable's type.

In your CommandInt.ts file, import the Message class from Discord, then declare an interface called CommandInt with this syntax:

import { Message } from "discord.js";

export interface CommandInt {

}

Inside this interface, you are going to add three properties:

name: string; – the name value will be your command's name. You will use this to trigger the command in the Discord server.
description: string; – the description value explains what the command does. You will used this in one of the commands.
run: (message: Message) => Promise – this is the property that will hold the command's logic.

The run type definition is a bit tricky, so let's break it down. You have typed it as a function which takes one argument, message. That argument should be the Message type. You then set the function's return type to Promise. This means your function will be asynchronous (this is important later) and does not return a value.

Create a Command List

Next you need a place to store all of your commands. Create a folder called commands in the src directory, and add a file called _CommandList.ts. The underscore here will keep this file at the top of the list.

The _CommandList.ts file will need two lines. First, import your CommandInt interface, then declare a CommandList array. The array will be empty for now, but give it a CommandInt[] type so TypeScript knows it will eventually hold your command objects. The file should look like:

import { CommandInt } from "../interfaces/CommandInt";

export const CommandList: CommandInt[] = [];

The purpose of this file is to create an array of your bot's commands which you will iterate over in the message event listener. There are ways to automate this, but they tend to be unnecessarily complex for smaller bots.

Check for Commands

Back in your onMessage.ts file, you should start working on the logic to check messages for commands.

The first step is to ensure that your bot ignores its own messages, as well as the messages of other bots. This helps prevent endless cycles where the bot is responding to itself.

The message object has an author property, which represents the Discord user that sent the message. The author property has a bot property, which is a Boolean that indicates the author is a bot account. Add a step to check if this property is true:

if (message.author.bot) {
  return;
}

You also want to prevent people from accidentally calling your bot's commands. For example, if you have a help command, you would not want the bot to respond when someone says "help me please".

This can be avoided by setting a prefix for the bot to detect. Most bots use !, but you are welcome to choose whichever prefix you would like.

Declare a variable prefix and assign it your chosen prefix, such as const prefix = "!";. Then add a condition to check if the message.content does not start with that prefix, and if so return.

const prefix = "!";

if (!message.content.startsWith(prefix)) {
  return;
}

Now that you have verified that the message came from a user and is intentionally triggering your bot, you can check to see if the command is valid.

Using the (currently empty) CommandList array will facilitate this process, so import it at the top of your file with import { CommandList } from "../commands/_CommandList";.

There are a few ways to iterate through an array – for the live bot, I used a for..of loop. Regardless of the loop approach, you will want to check each command in the array against the message content. Here is a loop example:

  for (const Command of CommandList) {
    if (message.content.startsWith(prefix + Command.name)) {
      await Command.run(message);
      break;
    }
  }

This loop iterates through the list of commands, and if the message content starts with the prefix and command name, the bot will call the command's run method.

Remember that you declared the run property to be an async function that took the message as an argument. Then, to save on compute time, the loop breaks when it finds a matching command.

Database Model

There's one more step before you are ready to start writing commands. This bot will track your community members' 100 Days of Code progress. And you need to store that progress in the database.

mongoose helps structure your MongoDB records to prevent you from passing malformed or incomplete data into your database.

Start by creating a models folder in your database directory. In that models folder, create a CamperModel.ts file. This will be your structure for the user objects.

You first need to import the necessary values from the mongoose library. Add import { Document, model, Schema } from "mongoose"; at the top of the file.

Because you are using TypeScript, you need to create a type definition for your database objects. Create another interface, like you did for your commands, named CamperInt.

export interface CamperInt {

}

Your database model will have four properties. Add these to your interface:

discordId: string; – Every user object in Discord has a unique identifier, called a Snowflake, which is used to distinguish them from other users. Unlike a username or discriminator (the four digit number after the username), the id value cannot be changed. This makes it the ideal value for linking your stored data to a Discord user.
round: number; – This will represent the "round" the user is on in the challenge. When someone completes 100 days of the challenge, they may choose to undertake the challenge again. When they do, they often refer to it as "round 2", for example.
day: number; – This represents the day the user is on in the challenge.
timestamp: number; – You will use this value to track when the user last submitted a 100 Days of Code post.

Great! Now you need to define the Schema for your database entries. mongoose uses a Schema object to define the shape of the documents that go in to your database collection. The Schema import has a constructor, which you will assign to a variable.

export const Camper = new Schema();

This constructor takes an object as its argument, and that object defines the database keys and types. Go ahead and pass in an object similar to what your interface looks like.

export const Camper = new Schema({
    discordId: String,
    round: Number,
    day: Number,
    timestamp: Number,
})

Next you need to create the model. In mongoose, the model object serves to create, read, and update your documents in the MongoDB database. Add export default model(); at the bottom of your file.

The model function takes a few parameters. The first is a string, and is the name to use for the documents in your database. For this collection, use "camper". The second argument is the schema to use for the data – use your Camper schema there.

By default, mongoose will use the plural version of your model name for the collection. In our case, that would be "campers". If you want to change that, you can pass in a third argument of { collection: "name" } to set the collection to name.

If you were using JavaScript, this would be enough to get your database model set up. However, because you are using TypeScript, you should take advantage of the type safety. model() by default returns a Document type of any.

To resolve this, you can pass a generic type into the model function. Generic types serve as variables for type definitions, in a sense. You need to set the generic type for your model to use your interface. Add the generic type by changing model to model.

Just one more step here. Your CamperInt interface only defines the properties you set in the MongoDB document, but doesn't include the standard properties.

Change your export interface CamperInt to export interface CamperInt extends Document. This tells TypeScript that your type definition is an extension of the existing Document type definition – you are essentially adding properties to that structure.

Your final file should look like this:

import { Document, model, Schema } from "mongoose";

export interface CamperInt {
  discordId: string;
  round: number;
  day: number;
  timestamp: number;
}

export const Camper = new Schema({
  discordId: String,
  round: Number,
  day: Number,
  timestamp: Number,
});

export default model("camper", Camper);

As a safety check, use npm run build again. You should not see any errors in the terminal.

How to Write Bot Commands

You are finally ready to start writing some commands! As this is a 100 Days of Code bot, you should start with the command for creating a 100 Days of Code update.

100 command

Within your commands folder, create a oneHundred.ts file. This will hold your 100 Days of Code command. Import your command interface with import { CommandInt } from "../interfaces/CommandInt";.

Now declare an exported variable oneHundred and give it the CommandInt type:

import { CommandInt } from "../interfaces/CommandInt";

export const oneHundred: CommandInt = {

}

Set the name property to "100", give it a description property similar to "Creates a 100 Days of Code update", and set up the run function as async (message) => {}.

Now for the logic within the function. Your logic will need a few properties from the message object to work, so go ahead and destructure those out: const{ author, channel, content } = message;.

When a user calls this command, it should look something like this:

!100 Here is my 100 Days of Code update.

You will want to extract that text without the !100 part. There are a few was to do this – we are going to slice it out with const text = content.split(" ").slice(1).join(" "). Using the previous example, text would now hold the string "Here is my 100 Days of Code update.".

Time for some database work. Import your CamperModel with import CamperModel from "../database/models/CamperModel". Note that you are importing the default export, instead of a module.

Now you need to see if the user has a record in your database. Use let targetCamperData = await CamperModel.findOne() to prepare for this.

The .findOne() method is used to query the collection for a single record, and takes an object to filter the query. These queries support MongoDB's syntax for advanced searching, but in this case you only need to find the record by the user's discordId. Add {discordId: author.id} as the parameter for the findOne().

What happens if the user's record does not exist yet? If this is their first time using the command, they will not have a document in the database. Add an if condition to check if targetCamperData does not exist:

if (!targetCamperData) {

}

In this block, you are going to reassign targetCamperData to a new document with targetCamperData = await CamperModel.create(). You use the .create() method to generate and save a new document. The method takes an object as the first argument – that object is the document to create. Pass the following object to the method:

targetCamperData = await CamperModel.create({
  discordId: author.id,
  round: 1,
  day: 0,
  timestamp: Date.now()
});

Whether the record exists already or has just been created, your next step is to update it. After your if block, add a line to increment the day value: targetCamperData.day++.

What happens if the user is on day 100? They should not be able to go to day 101, as the challenge is only a hundred days long. You will need to add logic for that. If the user is above day 100, you want to set their day to 1 and increase their round:

targetCamperData.day++;
if (targetCamperData > 100) {
  targetCamperData.day = 1;
  targetCamperData.round++;
}

Now update the timestamp with targetCamperData.timestamp = Date.now();. This may seem redundant, since you did this step in the create method, but this ensures that the timestamp is updated if the data already existed.

You need to save the changes you made to the document. Add await targetCamperData.save(); to do this – mongoose will then save your changes to the document in MongoDB.

Now you will construct the message the bot should send. To do this, you are going to use a message embed. Message embeds are special message formats that are available to Discord bots, which offer additional formatting options and styling.

Start by adding the MessageEmbed class to your imports with import { MessageEmbed } from "discord.js";. Then, after your database logic, create a new message embed with const oneHundredEmbed = new MessageEmbed();. Time to start setting the values of the embed.

The embed title appears as large text at the top of the embed. Set the title to "100 Days of Code" with oneHundredEmbed.setTitle("100 Days of Code");.

The embed description appears as standard text below the title. Set this to the user-provided text with oneHundredEmbed.setDescription(text);.

The embed author appears above the title, and is used to indicate who generated the embed. You will set this with oneHundredEmbed.setAuthor().

This method takes a few arguments, and you will use the first two. The first argument is the author's name. Set this to author.username + "#" + author.discriminator. This will display in the same way that you see a user in Discord: nhcarrigan#0001.

Set the second argument to author.displayAvatarUrl(). This is a method provided by discord.js to fetch the URL for the author's avatar image.

Embed fields are additional title-description pairs that can be nested within the embed, and optionally inlined. These can be created with the .addField() method, which takes up to three arguments. The first argument is the field title, the second argument is the field description, and the third argument is an optional Boolean to set the field as inline.

Add two fields to your embed. The first is oneHundredEmbed.addField("Round", targetCamperData.round, true);, and the second is oneHundredEmbed.addField("Day", targetCamperData.day, true);.

You can add a footer to an embed and appears at the bottom in small text. Set the footer to the data's timestamp with oneHundredEmbed.setFooter("Day completed: " + new Date(targetCamperData.timestamp).toLocaleDateString();. The toLocaleDateString() method will take a Date object and convert it to a locale-specific string based on the location of your bot's server.

Now you need to send that message embed. The channel property you extracted from the message value earlier represents the Discord channel in which the message was sent. This object has a .send() method, which you can use to have the bot send a message back to that channel. Use await channel.send(oneHundredEmbed) to send your new embed to that channel.

To keep the channel clean, add an await message.delete() to have the bot delete the message that triggered the command. Your final code should look like this:

import { CommandInt } from "../interfaces/CommandInt";
import CamperModel from "../database/models/CamperModel";
import { MessageEmbed } from "discord.js";

export const oneHundred: CommandInt = {
  name: "100",
  description: "Creates a 100 Days of Code update",
  run: async (message) => {
    const { author, channel, content } = message;
    const text = content.split(" ").slice(1).join(" ");

    let targetCamperData = await CamperModel.findOne({ discordId: author.id });

    if (!targetCamperData) {
      targetCamperData = await CamperModel.create({
        discordId: author.id,
        round: 1,
        day: 0,
        timestamp: Date.now(),
      });
    }

    targetCamperData.day++;
    if (targetCamperData.day > 100) {
      targetCamperData.day = 1;
      targetCamperData.round++;
    }
    targetCamperData.timestamp = Date.now();
    await targetCamperData.save();

    const oneHundredEmbed = new MessageEmbed();
    oneHundredEmbed.setTitle("100 Days of Code");
    oneHundredEmbed.setDescription(text);
    oneHundredEmbed.setAuthor(
      author.username + "#" + author.discriminator,
      author.displayAvatarURL()
    );
    oneHundredEmbed.addField("Round", targetCamperData.round, true);
    oneHundredEmbed.addField("Day", targetCamperData.day, true);
    oneHundredEmbed.setFooter(
      "Day completed: " +
        new Date(targetCamperData.timestamp).toLocaleDateString()
    );

    await channel.send(oneHundredEmbed);
    await message.delete();
  },
};

If you remember, you created a list to hold all of your commands. You need to add your new command to that list. Head back to your _CommandList.ts file. Import your new command with import { oneHundred } from "./oneHundred";, then add oneHundred to your empty CommandList array:

import { CommandInt } from "../interfaces/CommandInt";
import { oneHundred } from "./oneHundred";

export const CommandList: CommandInt[] = [oneHundred];

Now you can test it out! Use npm run build and npm start to get the bot started. Try sending !100 This is my first post! in the channel. The bot should respond with an embed and delete your message.

You can see the embed, with the author, title, description, fields, and footer.

View command

What happens if a user forgets if they submitted or not, or wants to see what day they are on? You should add a command to view current 100 Days of Code progress.

In your commands directory, create a view.ts file. Like before, import your command interface and CamperModel, and create a new command called view. Set the name to "view", the description to something like "View your current 100 Days of Code progress", and the run command to async (message) => {}.

You won't need the message content for this command, so extract the author and channel values from the message like you did before: const { author, channel } = message;.

Just like the 100 command, you need to fetch the user's data from the database. This time, however, if the data does not exist you will not be creating it – so you can use const here instead of let: const targetCamperData = await CamperModel.findOne({ discordId: author.id });

Now, if the user doesn't have a data record yet, they haven't started the challenge with the bot. You should send a message to let them know how to do this.

if (!targetCamperData) {
  await channel.send("You have not started the challenge yet.");
  return;
}

Construct an embed, similar to the one you built for the 100 command. Don't forget to import the MessageEmbed class!

    const camperEmbed = new MessageEmbed();
    camperEmbed.setTitle("My 100DoC Progress");
    camperEmbed.setDescription(
      `Here is my 100 Days of Code progress. I last reported an update on ${new Date(
        targetCamperData.timestamp
      ).toLocaleDateString()}.`
    );
    camperEmbed.addField("Round", targetCamperData.round, true);
    camperEmbed.addField("Day", targetCamperData.day, true);
    camperEmbed.setAuthor(
      author.username + "#" + author.discriminator,
      author.displayAvatarURL()
    );

A couple of key differences here. Instead of taking a text input from the user, you are using a fixed description value to indicate this is a view embed instead of a 100 embed. Since you use the timestamp in the description, you do not need to add a footer.

Just like before, send the embed to the message channel and delete the original message. Your final file should be:

import { CommandInt } from "../interfaces/CommandInt";
import CamperModel from "../database/models/CamperModel";
import { MessageEmbed } from "discord.js";

export const view: CommandInt = {
  name: "view",
  description: "Views your 100 Days of Code progress.",
  run: async (message) => {
    const { author, channel } = message;

    const targetCamperData = await CamperModel.findOne({
      discordId: author.id,
    });

    if (!targetCamperData) {
      await channel.send("You have not started the challenge yet.");
      return;
    }

    const camperEmbed = new MessageEmbed();
    camperEmbed.setTitle("My 100DoC Progress");
    camperEmbed.setDescription(
      `Here is my 100 Days of Code progress. I last reported an update on ${new Date(
        targetCamperData.timestamp
      ).toLocaleDateString()}.`
    );
    camperEmbed.addField("Round", targetCamperData.round, true);
    camperEmbed.addField("Day", targetCamperData.day, true);
    camperEmbed.setAuthor(
      author.username + "#" + author.discriminator,
      author.displayAvatarURL()
    );

    await channel.send(camperEmbed)
    await message.delete();
  },
};

Add your new view command to your _CommandList.ts file with an import, and put the command in the CommandList array. Then use npm run build and npm start to test your new changes. Send "!view" in your channel and you should see the bot respond:

Edit command

Unfortunately, if a user makes a typo in their 100 Days of Code post, they can't edit the message because the bot sent it. But you can add a command that will allow them to do this.

Create an edit.ts file in your commands directory. Import your command interface and declare a new command called edit. Set the name to "edit", the description to something like "Edits a previous 100 Days of Code post", and prepare the run function as you have before.

Within the function, extract the author, channel, and content properties from the message object.

The edit command will take a Discord message id, followed by the updated text to use. You can destructure those from the message content with const [, targetId, ...text] = content.split(" ");.

The first element in the array would be the !edit command call, which is not needed for this command so you do not need to assign it to a value. The targetId element would be the id of the message to edit. ...text that uses the spread operator to assign the remaining message content to the text variable, as an array.

Now you need to use the targetId to get the actual message from Discord. The channel value has a messages property which represents all of the messages sent in that channel. You can use the fetch method on that messages property to get a specific message (or multiple messages). Set this up as const targetMessage = await channel.messages.fetch().

The .fetch() method can take an object containing the options for the fetch request, or it can take a string as the id of the message to fetch. Because you have the id, and are only fetching one message, you can pass targetId to the .fetch() method as the only parameter.

It is possible that the targetMessage does not exist. For example, if the user provided an invalid id string (or no id string at all). You'll need to add logic to check if the targetMessage is not found:

    if (!targetMessage) {
        await channel.send("That does not appear to be a valid message ID.");
        return;
    }

Now that you have asserted that the message exists, you can start working with the properties. Because your bot sends the message as an embed, the content property you are used to working with will be empty. Instead, you can find the embed within the embeds property.

The embeds property is an array of MessageEmbed objects. Since you wrote the bot's code to only send one embed, you can access that embed with const targetEmbed = targetMessage.embeds[0];.

Now that you have the embed, you need to confirm that the embed is from one of that user's 100 Days of Code posts. Thankfully, you set the user as the author of the embed. You can check if the embed's author information does not match the message author's information:

    if (
      targetEmbed.author?.name !==
      author.username + "#" + author.discriminator
    ) {
      await channel.send(
        "This does not appear to be your 100 Days of Code post. You cannot edit it."
      );
      return;
    }

You have accounted for the message belonging to a different user (or not having the correct embed entirely), so now you can edit the embed.

Like you did before, set the description of the embed with the .setDescription() method. You'll need to use .join(" ") on the text variable this time, since it is currently an array. targetEmbed.setDescription(text.join(" "));

Rather than sending a new message, you need to edit the existing message. You have the existing message stored in targetMessage, so you can use the .edit() method to change that message directly.

await targetMessage.edit(targetEmbed); will change the message's embed to your modified version. Then delete the message that triggered this command with await message.delete();. Your command should look like this:

import { CommandInt } from "../interfaces/CommandInt";

export const edit: CommandInt = {
  name: "edit",
  description: "Edits a previous 100 Days of Code post.",
  run: async (message) => {
    const { author, channel, content } = message;
    const [, targetId, ...text] = content.split(" ");

    const targetMessage = await channel.messages.fetch(targetId);

    if (!targetMessage) {
      await channel.send("That does not appear to be a valid message ID.");
      return;
    }

    const targetEmbed = targetMessage.embeds[0];

    if (
      targetEmbed.author?.name !==
      author.username + "#" + author.discriminator
    ) {
      await channel.send(
        "This does not appear to be your 100 Days of Code post. You cannot edit it."
      );
      return;
    }

    targetEmbed.setDescription(text.join(" "));

    await targetMessage.edit(targetEmbed);
    await message.delete();
  },
};

Add the command to your _CommandList.ts file, importing it and adding the variable to the array. Then use npm run build and npm start to run the bot again.

To grab a message ID, you should have Developer Mode enabled in your Discord client. If you have not done so, visit your settings and select the "Advanced" section. Toggle "Developer Mode" on:

Then head back to your channel and right click on your original 100 Days of Code message. You should see an option in the context menu to copy the message ID:

Select that option and you will get an ID (mine was 855559921666621441). Then in the same channel, use !edit 855559921666621441 This is an edited post!, replacing my value with the one you got from the "Copy ID" option. The bot should edit the existing embed with your new content.

Help command

You are almost there! One more command to go. Many bots have a help command, which returns a list of available commands. You should add one to your bot as well.

One last time, create a help file in your commands directory. Import your CommandInt interface and set up your command as help. Set the name to "help", and the description to something like "Returns information on the bot's available commands.". Set up your run function.

This time you only need the message's channel property, so no need to destructure anything here. Instead, import the MessageEmbed class from discord.js, and go ahead and import your command list too: import { CommandList } from "./_CommandList";.

Construct a new MessageEmbed and assign it to a helpEmbed variable. Set the title to "Available Commands:" and the description to something similar to "These are the available commands for this bot.".

Now you need to add a field to the embed and dynamically generate the list of commands. Start by adding the field with helpEmbed.addField(). Use the first parameter to set the field name to "Commands:". For the description (the second parameter), you will use the CommandList array to generate a readable list of commands.

    helpEmbed.addField(
      "Commands:",
      CommandList.map((el) => `\`!${el.name}\`: ${el.description}`).join("\n")
    );

The process here is two-part. First, using the built-in array method .map, you are creating a new array from your array of CommandInt objects. This array contains strings formatted using Markdown so the command name and description are readable. The string for your help command would look like:

!help: Returns information on the bot's available commands.

You are then joining that array of strings with a new-line separator, which will create a vertical list of commands in a single string (embed fields require strings for the description).

Send the embed to the channel. Because you did not destructure the channel property out of the message object, you will need to use message.channel.send(helpEmbed); directly.

This time, do not delete the original message – you did not add an author to the help embed, so preserving the original message helps moderators see who used the command. Your help command should look like:

import { CommandInt } from "../interfaces/CommandInt";
import { MessageEmbed } from "discord.js";
import { CommandList } from "./_CommandList";

export const help: CommandInt = {
  name: "help",
  description: "Returns information on the bot's available commands.",
  run: async (message) => {
    const helpEmbed = new MessageEmbed();
    helpEmbed.setTitle("Available Commands!");
    helpEmbed.setDescription(
      "These are the available commands for this bot."
    );
    helpEmbed.addField(
      "Commands:",
      CommandList.map((el) => `\`!${el.name}\`: ${el.description}`).join("\n")
    );

    await message.channel.send(helpEmbed);
  },
};

Import your help command into your _CommandList.ts file and add the command to your array. With this final command, your _CommandList.ts file should be:

import { CommandInt } from "../interfaces/CommandInt";
import { oneHundred } from "./oneHundred";
import { view } from "./view";
import { edit } from "./edit";
import { help } from "./help";

export const CommandList: CommandInt[] = [oneHundred, view, edit, help];

Use npm run build and npm start one last time to test this feature. Send !help in your channel and the bot should respond:

Conclusion

Congratulations! You have successfully built a Discord bot for the 100 Days of Code challenge.

If you are interested in exploring further, you can view the source code for the live bot that inspired this tutorial, which includes custom error logging, external error reporting, and a documentation site.

What is SendGrid? SMTP Email Newsletter Tutorial

Naomi Carrigan — Fri, 14 May 2021 20:31:30 +0000

You may have heard of the term SMTP before, and wondered what it is. SMTP is a common method for handling email messages.

Today I am going to explain what SMTP is, and how to use an SMTP provider such as SendGrid to send emails from your address.

What Is SMTP?

SMTP, or Simple Mail Transfer Protocol, is the method through which internet servers send email messages. When you send an email through your Gmail account, for example, your mail client uses SMTP to send that message to the server. The server then also uses SMTP to send it to the receiving server.

Without diving too much into the technical details, the easiest way to think of it is that SMTP is an email server.

What is SendGrid?

SendGrid is an SMTP service provider – in fact, it's the provider freeCodeCamp uses to send out Quincy's weekly newsletter.

Like many SMTP providers, SendGrid offers the use of their mail servers to send your emails. This is an excellent option for sending large volumes of emails, where having to do so manually would take a significant amount of time and effort.

How to Create a SendGrid Account

The first step in using SendGrid's services is to create your account. Head on over to the SendGrid website to get signed up. They offer multiple pricing models, but the free level will be sufficient at least for this tutorial.

As you scale up your email list, however, you may need additional features from a higher subscription tier.

Once you are signed in, you should see a default dashboard view:

Image depicting the default SendGrid dashboard view.

How to Set up Your Domain or Email with SendGrid

From that dashboard view, select "Settings", then choose "Sender Authentication" from the dropdown menu. The Sender Authentication settings are where you tell SendGrid which email accounts to allow emails to be sent from.

There are two approaches here – if you have a custom domain for your emails, you can set up Domain Authentication. If you are using a personal email address, such as a Gmail address, then you will need to set up Single Sender Authentication.

Choose whichever option works best for you, and follow SendGrid's prompts to set it up. Your end result should look similar to this:

Image depicting Sender Authentication settings.

How to Send Emails Via SendGrid's API

The actual process of sending the emails is done through SendGrid's API. But before you can use the API, you'll need to set up an API key.

From your dashboard view, select "Settings", then select "API Keys". Choose "Create API Key" and select the permissions you want the key to have (I gave mine full permissions, just to avoid issues).

Once you have the key, save it somewhere safe as you will not be able to access it again.

Image depicting the API Keys settings page.

Now that you have the API key, you'll need to set up the code to use the /mail/send endpoint. You can write the code manually, or use one of the helper libraries such as SendGrid's Node.js package.

When using the Node.js package, you set the values for your email as follows:

to: The address to send the email to.
from: The address to send the email from. This should match your settings in the Sender Authentication.
subject: The subject of your email.
text: The content of your email, if you are sending a plain text email.
html: The content of your email, if you are sending an HTML email.

The properties in a raw API call are different, as are the properties in the other helper libraries. Be sure to refer to the documentation for your specific approach.

How to Use Dynamic Templates in SendGrid

As an alternative option, instead of sending the email content in your API call, you can use a Dynamic Template to generate the content.

A Dynamic Template lets you set the content for emails to send out, and offers Handlebars functionality to replace specific data fields.

To create a Dynamic Template, from your dashboard select "Email API" and then "Dynamic Templates". Then click "Create a Dynamic Template" – you should see your template appear below.

Click on it, then select "Add Version" to open the template selection. Choose the blank template, then select the type of editor you would like to use (I use the code editor).

Image depicting the editor.

You can write the content of your email, and use placeholders such as {{name}} for the dynamic data. These placeholders would be given values through your API calls when you send the emails.

If you want to see how it would render, you can use the "Test Data" tab to add sample data for the placeholders.

How to Get Blocks/Bounces/Spams via SendGrid's API

It's important to track undeliverable emails. SendGrid offers tooling to help track this for you, and that data is available through three different dashboard views (or API endpoints, if you want to parse the data programmatically).

Blocked emails are emails that were rejected by the receiving email provider's policies, such as university emails that don't accept external traffic, or emails that could not be resolved (the mail server was not found).
Bounced emails are emails that were received by the server but returned. This occurs in cases where the email server exists, but the specific user does not, or the email inbox is at capacity.
Spam emails are arguably the most important to monitor, as these are generated when a user receives your email and reports to their provider that your email is spam. These directly impact your reputation as a sender, so it is imperative that you do not send an email to someone who has marked your previous emails as spam.

Other Concerns

Speaking of your reputation as a sender, SendGrid offers a top-level metric called "Sender Reputation". This metric is an aggregation of your activity through their platform, and helps give a general idea of the way email providers are likely to handle your emails.

A lower reputation will result in your emails being marked as spam automatically, or even your IP addresses being blocked.

If you are on the free tier for SendGrid, you will be using shared IP addresses. This means that other customers will also be sending emails through that same IP, and their actions can negatively impact your reputation.

If you intend to send large volumes of emails, I recommend that you purchase dedicated IP addresses to ensure that your reputation is protected.

Conclusion

I hope this article has helped you become more familiar with SendGrid and the services they offer. You should now be ready to start sending your own emails.

If you are planning to start an email newsletter, I wrote an article about creating effective email newsletters that might help.

How to Create an Email Newsletter – Design, Layout, Send

Naomi Carrigan — Thu, 13 May 2021 21:19:40 +0000

If you manage a large community, chances are you need a way to communicate updates to your members quickly and efficiently. An email newsletter can be a very effective way to do so.

In this article, I am going to provide some tips and suggestions for maximizing the impact of your email newsletter: open rates, click-through rate, and not irritating your recipients.

I will also share some technical details and configurations you can use to maximize the deliverability of your email newsletter.

How to Write an Impactful Subject Line

Your subject line is the first thing your readers will see when the email appears in their inbox. It's important, then, that you use something eye catching that encourages them to read the message.

What to Include in the Subject Line

Your subject line should provide a brief summary of the email content or highlight the key information. Some examples would be:

Learn Data Structures and Algorithms [free 6-hour coding course]

This headline comes from one of Quincy's email newsletters, and calls out the first article out of a weekly curated list of five articles.

Our Community Reached 3,000 Members - Here's What's Next

Here the headline provides a clear summary of the email's content – an update on the community's success and future plans.

The Observatory #4: Gravity is the key to community growth

Pulled from an Orbit newsletter, this subject line has two benefits: Like the others, it summarizes the content of the email. It also helps readers recognize this email as a serial newsletter, and track the number to ensure they have not missed one.

What to Exclude from the Subject Line

You want to avoid headlines which are vague, uninformative, or may seem like spam.

Click Here! Important Information Within!

Avoid words and phrases such as click here, urgent, important, and priority. These types of subject lines are often used in spam emails, and can cause your readers to disengage.

April 2020 Community Update

While this subject is not going to seem like spam, it is also vague and uninformative. You want your subject to catch the reader's attention and be unique.

Top Picks Just For You

Another vague subject line, this one also gives off a "click-bait" vibe. This type of subject line doesn't hook your readers or entice them in to reading your full email.

How to Craft an Effective Email Body

The body of your email is where your core content will go. Having a well written and effective email body is essential.

HTML vs. Plain Text in Emails

Using HTML in your email can make it look nice, certainly. However, HTML emails are more likely to be flagged as spam by the receiving providers.

Plain text emails are generally safer, though they offer less functionality. Additionally, a plain text email will ensure maximum compatibility with all devices, and ensure that your email can be viewed even over slower internet connections.

HTML, on the other hand, offers a much higher level of customization in terms of layout, content, and functionality. You can even implement things like interaction tracking to see who is opening (open rate), reading, and clicking on links in your email (click-through rate). Whether these features are worth the potential impact to delivery is or not is up to you.

How to Handle Links in Emails

Speaking of links, there are some special considerations when it comes to handling links in your email. The key idea is to keep your links easily readable and verifiable.

One important aspect is the transparency of your links. You want to avoid using things like URL shorteners that hide the domain the link points to. Keeping your link's target clear ensures that your readers can trust the safety of the link.

Many sending providers offer click-tracking features, where they will provide metrics on how many of your readers click the links within your email.

While these metrics may seem useful, they do come at a cost – usually the links are obfuscated through a redirect via the provider's domain. This decreases the chance that your readers will click the link.

Unsubscribe Links

If your email is considered commercial material (marketing, advertisements, and so on.), having an unsubscribe link is required. If it is a transactional (receipt, account updates) or relationship (communicating with existing contacts) email, then an unsubscribe link is not necessarily required but is still strongly recommended.

Having an unsubscribe link allows your recipients to quickly and easily opt-out of receiving future communications. While it may not seem ideal to lose your reader base, it is much better than having your emails flagged as spam (which can impact your sender reputation and cause future emails to anyone with that email provider to be blocked).

Your unsubscribe link does not need to be prominent or featured – a simple link with the text "Unsubscribe" at the bottom of your email is often sufficient.

Content and Layout of Your Emails

The content and layout of your email body are also very important. If you are using plain text to send your email, then your biggest consideration will be the length of your paragraphs. In general, shorter paragraphs are easier to read than a "wall of text", and will help your readers stay engaged with the content.

If you are using HTML, then you have some additional obstacles to consider.

For example, including images may seem very tempting as they can make the email look more visually appealing. But each image increases the time it takes for the email to render on the reader's device, and images aren't as accessible for those who use screen readers as plain text is.

Remember that images should add to the content, not detract from the information.

Another aspect to consider when using HTML is the semantic structure. To avoid any rendering errors or accessibility concerns, you will want to keep your HTML semantically correct. I recommend using an HTML Validator before sending the email to ensure you don't have any errors.

Content length itself is also important. You don't want to overwhelm your readers with too much information in a single email. If you have a lot of content you want to share, consider making a blog post or news article – then, link that article in your email with a brief summary of the content.

How to Sign Off in an Email

The signature of your email is just as important as the main content. Signing off your email lets your readers know who sent it, and gives you the opportunity to close out the content.

You should include your name and your role within your organization, so that your readers see that the email came from a person. This creates the impression that it is a more personal communication and not an automatically generated email.

Finally, the signature and conclusion also give you the chance to thank your readers for their time. It is good to recognize that your readers took time out of their day to read your content. Time is valuable, and your readers have given you theirs.

Technical Aspects of Email Newsletters

Now that you've drafted your first newsletter, you need to address the technical concerns. Namely, you'll need to figure out how you'll send this newsletter.

Choose a Sending Provider

The first question to answer is what will you use to send this email? It is entirely possible to set up and run your own Secure Mail Transfer Protocol (SMTP) server, but that can be a significant investment of time and resources.

Instead, there are a number of providers that will handle sending the emails for you. Here at freeCodeCamp we use SendGrid. Most providers will offer an API to request that emails be sent, or a UI to prepare your emails. Then they will handle the actual send process for you.

While these providers can get expensive at higher volumes, often times the cost is worth the access to additional features such as email validation and bounce report tracking.

Set up Email Authentication

Another important technical aspect is email verification and authentication, especially if you are using a custom domain.

How does a provider such as Gmail confirm that the email has legitimately come from your organization and not someone pretending to be you?

There are a couple of security steps you can take to ensure that your emails are delivered while spoofed emails are not.

Sender Policy Framework (SPF): You can use an SPF setting to validate that the mail server is authorized to send emails from your email domain. SPF is enabled via a TXT record in your domain settings. The content of that record will depend on the system you are using to send those emails.
DomainKeys Identified Mail (DKIM): You can use DKIM to assert that the email message has not been modified in transit from the sending server to the receiving server. DKIM records are set up in your domain settings either as a TXT record or a CNAME record, depending on your provider. These records will indicate the public encryption/decryption keys.
Domain Message Authentication, Reporting, and Conformance (DMARC): The final step, after enabling SPF and DKIM, is to set up a DMARC record. The DMARC record tells email providers what to do if an email from your domain fails SPF or DKIM, where to send delivery reports, and how often to apply the DMARC policy. A DMARC record is added as a TXT record to your domain settings, as _dmarc.yourdomain.tld.

Congratulations. Now that you have read this article, you should have a basic understanding of how to create and send your first email newsletter. I hope you found this article helpful.

PowerShell Themes and Windows Terminal Color Schemes – How to Customize Your Command Line

Naomi Carrigan — Sat, 06 Mar 2021 01:39:57 +0000

I recently set up and configured Windows Terminal for my local development environment. In this article, I will walk you through the steps to configure your own Terminal.

If you have not done so already, you can download Windows Terminal from the Microsoft Store if you are on Windows 10. Windows Terminal is not available on earlier versions of Windows.

How to Configure your PowerShell Selections

Image demonstrating the multi-tab functionality offered by Windows Terminal

One of the greatest benefits of Windows Terminal is the ability to use multiple shells in the same screen, switching between tabs to access different shells.

Once you have installed the application, open the terminal and select the v symbol at the top (next to the open tab). You should see a list of available terminals, but we will ignore those for now.

From the dropdown, select the "Settings" option and the settings.json file should open in your default text editor.

There are quite a few properties in here. The first one you will need to look at is the profiles property. The profiles property contains all of your terminal selection options - the nested defaults property contains default settings for all profiles, and the list property contains your terminal profiles.

We are going to focus on the list property, which should currently contain values similar to this:

    [
        {
            "guid": "{61c54bbd-c2c6-5271-96e7-009a87ff44bf}",
            "name": "Windows PowerShell",
            "commandline": "powershell.exe",
            "hidden": false
        },
        {
            "guid": "{0caa0dad-35be-5f56-a8ff-afceeeaa6101}",
            "name": "cmd",
            "commandline": "cmd.exe",
            "hidden": false
        }
    ],

The list property is an array of objects and determines which terminal executables can be loaded via Windows Terminal. In this example, the options available are Windows PowerShell and the CMD prompt.

Here is a breakdown of the properties in these objects:

guid: This is a Globally Unique Identifier and is used exclusively for the defaultProfile setting (which we will cover later).
name: This is the name that displays in the dropdown when you open a new tab in the Windows Terminal.
commandline: This is the executable that loads when you open a tab with this profile.
hidden: This option is a Boolean and determines whether the profile appears in the new tab dropdown. If you are not using a terminal often, set this to true to keep it from displaying in the dropdown. This allows you to preserve the profile settings while keeping your dropdown list to just the terminals you need.

Image depicting the dropdown menu, showing two terminals enabled: Ubuntu-20.04 and Git Bash

Custom PowerShell Window Terminal Configuration Example

These default options may be all you need, depending on your development environment. I do most of my work in Windows Subsystems for Linux (WSL 2) and occasionally use Git Bash, so I have a couple of extra options.

      {
        "guid": "{07b52e3e-de2c-5db4-bd2d-ba144ed6c273}",
        "hidden": false,
        "name": "Ubuntu-20.04",
        "source": "Windows.Terminal.Wsl",
        "startingDirectory": "//wsl$/Ubuntu-20.04/home/nhcarrigan",
      },
      {
        "guid": "{00000000-0000-0000-ba54-000000000002}",
        "commandline": "%PROGRAMFILES%/git/usr/bin/bash.exe -i -l",
        "icon": "%PROGRAMFILES%/Git/mingw64/share/git/git-for-windows.ico",
        "name": "Git Bash",
        "startingDirectory": "%USERPROFILE%",
      },

You might see some new properties in here.

source: This property is generated automatically when Windows Terminal detects and generates a profile for a new terminal executable. You should not add this when you manually construct a profile.
icon: This property is used to select which .ico icon file is used next to the name in the new tab dropdown.
startingDirectory: This is the file path Windows Terminal will point to when you load a new tab with this profile.

How to Construct a Custom Profile in PowerShell

The profile settings for Git Bash were not automatically generated by Windows Terminal, and I had to construct them manually. If you need to do the same, here is how you can do this.

First, you will need to generate a guid value. These take the format of {00000000-0000-0000-0000-000000000000}. You can generate one in Windows PowerShell by running [guid]::NewGuid(), or in WSL by running uuidgen.

Next, define the path to the executable in the commandline property. The %PROGRAMFILES% value points to your "Program Files" directory and will account for the difference between the path for 32-bit and 64-bit applications.

If your installation is located in your user directory instead, you can use the %USERPROFILE% value. The -i -l flags are used to ensure Windows Terminal will load your .bashrc file correctly.

The icon property can be omitted, but if you want the icon to appear next to the terminal name you will need to add the file path to that icon file here.

The name property is required, and determines the display name in the dropdown selector. Here I use "Git Bash", so I know which terminal this option opens.

Finally, the startingDirectory should be set to the default filepath location you would like the terminal to target when it opens. I set mine to %USERPROFILE%, which points the terminal to my Windows user directory on load. This way I can quickly access my "documents" folder or other folders.

How to Set your Default Profile in PowerShell Windows Terminal

Now if you scroll back to the top of your settings.json file you should see a defaultProfile property. This option accepts a guid value, which should match one of the guid values in your list array. Windows Terminal will load a tab with this profile when you start it.

In my case, the bulk of my work is done in WSL so I've set my defaultProfile to that guid:

  "defaultProfile": "{07b52e3e-de2c-5db4-bd2d-ba144ed6c273}",

Now when I open my Windows Terminal application, a WSL instance is spawned.

Screenshot depicting a Windows Terminal instance, with a single tab titled "Ubuntu-20.04". "nhcarrigan @ DESKTOP-049HSUK ~" is displayed in the terminal screen.

How to Design your Color Scheme in PowerShell Windows Terminal

Now that you have set up your terminal applications, we can focus on styling the text to make it pretty.

Below your profiles property in the settings.json, you should see a schemes property. schemes contains an array of color scheme objects, which look something like this:

{
    "name" : "Campbell",

    "cursorColor": "#FFFFFF",
    "selectionBackground": "#FFFFFF",

    "background" : "#0C0C0C",
    "foreground" : "#CCCCCC",

    "black" : "#0C0C0C",
    "blue" : "#0037DA",
    "cyan" : "#3A96DD",
    "green" : "#13A10E",
    "purple" : "#881798",
    "red" : "#C50F1F",
    "white" : "#CCCCCC",
    "yellow" : "#C19C00",
    "brightBlack" : "#767676",
    "brightBlue" : "#3B78FF",
    "brightCyan" : "#61D6D6",
    "brightGreen" : "#16C60C",
    "brightPurple" : "#B4009E",
    "brightRed" : "#E74856",
    "brightWhite" : "#F2F2F2",
    "brightYellow" : "#F9F1A5"
},

If you have used tools like the chalk package on npm, you may recognize some of these color values (purple here is magenta in chalk.) The other keys do the following:

Image depicting the resulting colors from the default theme above.

name: This is used to link the color scheme to one of the profiles we created earlier.
cursorColor: This determines the color of your text cursor.
selectionBackground: This determines the background color of highlighted text.
background: This determines the background color for your terminal.
foreground: This determines the foreground color for your terminal. With my current configuration, I haven't seen any distinguishable difference when modifying this value.

The color properties determine how each color value sent by a terminal command (such as console.log) are displayed.

The settings I use for my color profile are:

    {
      "name": "Duotone Dark",
      "black": "#1f1d27",
      "red": "#d9393e",
      "green": "#2dcd73",
      "yellow": "#d9b76e",
      "blue": "#2488ff",
      "purple": "#de8d40",
      "cyan": "#6ad7d9",
      "white": "#b7a1ff",
      "brightBlack": "#353147",
      "brightRed": "#d9393e",
      "brightGreen": "#2dcd73",
      "brightYellow": "#d9b76e",
      "brightBlue": "#2488ff",
      "brightPurple": "#de8d40",
      "brightCyan": "#6ad7d9",
      "brightWhite": "#dfd1ed",
      "background": "#1f1d27",
      "foreground": "#b7a1ff"
    },

I encourage you to play with these values until you find a color set that fits your preferences.

Image depicting the resulting colors from my theme settings.

How to Link Your Color Scheme to a Profile

Now that you have defined your color settings, you need to link those settings to a terminal profile. You could apply the settings to the defaults object within the profiles property, which will apply them to all of your terminals. I prefer to configure different color settings for different terminals, so I can quickly identify when I am in the correct window.

Let's apply this to our WSL profile. Add a colorScheme key to your profile object, and give it a value that matches your scheme's name. You should now have something like this:

      {
        "guid": "{07b52e3e-de2c-5db4-bd2d-ba144ed6c273}",
        "hidden": false,
        "name": "Ubuntu-20.04",
        "source": "Windows.Terminal.Wsl",
        "startingDirectory": "//wsl$/Ubuntu-20.04/home/nhcarrigan",
        "colorScheme": "Duotone Dark",
      }

If you reload your Windows Terminal, you should see your new colors take effect.

How to Configure Additional Appearance Settings

My full WSL profile object has a few extra settings:

      {
        "guid": "{07b52e3e-de2c-5db4-bd2d-ba144ed6c273}",
        "hidden": false,
        "name": "Ubuntu-20.04",
        "source": "Windows.Terminal.Wsl",
        "startingDirectory": "//wsl$/Ubuntu-20.04/home/nhcarrigan",
        "colorScheme": "Duotone Dark",
        "useAcrylic": true,
        "acrylicOpacity": 0.5,
        "fontFace": "PxPlus IBM VGA8",
        "fontSize": 16,
        "experimental.retroTerminalEffect": true
      },

You can tweak these settings to your preference as well.

useAcrylic will enable the Windows 10 transparency effect on the terminal background
If the transparency effect is enabled, acrylicOpacity will determine how strong the transparency effect is. The lower the number, the higher the transparency.
fontFace will select which font is used for the terminal. Note that you need to have the font installed on your computer. I use the PxPlus IBM VGA8 font, and downloaded the .ttf file which Windows can install.
fontSize will determine the size of the font (in pt).
The experimental.retroTerminalEffect is my favorite setting. This simulates "scan lines" on your terminal, much like old CRT monitors.

Here's what my final setup looks like:

Image depicting the final result of the theme settings.

Any of these appearance settings can be passed in to the defaultSettings option instead to apply them to all of your profiles globally.

    "defaultSettings":
    {
        "useAcrylic": true,
        "acrylicOpacity": 0.1,
        "fontFace": "Cascadia Code",
        "fontSize": 10
    },

How to Configure Additional Settings in PowerShell Windows Terminal

There are a few additional settings that are worth your time to consider.

After the schemes property, you should see an actions property. This contains an array of keyboard shortcut settings.

By default, Windows Terminal assigns the copy and paste commands to Ctrl+Shift+C and Ctrl+Shift+V respectively. You can bind these to the default Ctrl+C and Ctrl+V with these settings:

    { "command": { "action": "copy", "singleLine": false }, "keys": "ctrl+c" },
    { "command": "paste", "keys": "ctrl+v" },

The singleLine option set to false preserves line breaks in the copied text.

Likely near the top of your settings.json file, there are two properties which also affect the behavior of copying text from your terminal:

copyOnSelect defaults to false. When set to true, highlighting text in the terminal with your mouse will copy it to your clipboard.
copyFormatting defaults to false. When set to true, text formatting will also be copied (otherwise, the content is copied as plain text).

Copying text from your terminal is generally safe, but pasting text into your terminal can be dangerous. Windows Terminal comes with a couple of protections to help avoid the risks:

largePasteWarning defaults to true and may not be present in your settings.json file. This setting triggers a dialogue box when you attempt to paste more than 5KB of content.
multiLinePasteWarning defaults to true and may not be present in your settings.json file. This setting triggers a dialogue box when you attempt to paste text content that contains line breaks (a common tactic for clipboard hijacking attacks is to force commands to run on paste with newline characters).

I strongly recommend leaving these protections in place.

Additional Resources

Congratulations! You have now set up and configured your own Windows Terminal setup.

For additional customization options that you did not read about in this article, visit the Windows Terminal Customization Documentation.

For a large selection of color schemes, available as downloadable JSON files, check out Windows Terminal Themes. This is where I got my settings from, which I tweaked a little to my personal taste.

The image which started it all - a demonstration screenshot of my email blast tool.

Happy coding.

How to Build a RocketChat Chatbot with TypeScript

Naomi Carrigan — Thu, 07 Jan 2021 23:30:51 +0000

Today I will show you how to build your own Rocket.Chat bot and test it locally.

This is the same process I used to build freeCodeCamp's moderation chat bot for our community's self-hosted chat server. This code is now running in production, and lots of people are using it.

How to Set up a Rocket.Chat Server

Your first step is to get an instance of Rocket.Chat running locally – you will need this to test the bot's functionality.

You can use freeCodeCamp's docker file, which will spin up both Rocket.Chat and MongoDB automatically for a development environment. This will save you a lot of time.

You can either clone this repository, or manually create your own docker file based on our configuration. This tutorial will assume that you are using our existing docker file.

Note: If you do not have docker installed, you will need to install it. The installation process is different for each operating system. I personally use Windows 10, so I installed the Docker desktop client and had to enable hardware virtualisation in my BIOS.

Within your Rocket.Chat directory, create a .env file and insert the following contents:

COMPOSE_FILE=docker-compose.dev.yml
PORT=3000
ROOT_URL=http://localhost:3000
ROCKETCHAT_VERSION=latest

Then open your terminal pointed at that same directory and run:

docker-compose up -d

You should see three success messages in your terminal:

Image showing the console output for the docker-compose up -d command. Three docker images were created, and each shows done.

Now if you open your browser and navigate to localhost:3000 you should see your local Rocket.Chat instance. The first screen you see will be the Setup Wizard, which will walk you through creating your Admin account.

Most developers use the Admin account for root-level access to configure their chat. Because this is a local instance, your credentials' security is less important than in a live instance.

Fill in your information to create the admin account:

Image showing the Admin Info modal, with inputs for Name set to Nicholas Carrigan, Username set to nhcarrigan, Organization Email set to nick@freecodecamp.org, and Password which is obfuscated. Below the input fields is a button labelled Continue.

The next screen is the Organization Info screen. This information is optional. For this tutorial, we will leave this information blank.

Clicking Continue will take you to the Server Info page. Here you set the name for your chat server (which will appear in the title metadata), your default language, the server type, and the 2FA setting.

Be sure to turn off the automatic 2FA setup for your local instance or you could be locked out of your own server.

Image showing Server Info modal, with inputs for Site Name set to fCC ChatBot tutorial, Language set to Default, Server Type with no selection made, and Auto opt in new users for Two Factor via Email set to No. Below the input fields are buttons labelled "Back" and "Continue".

The final step is to optionally register your server and gain access to Rocket.Chat's services such as push notifications. Note that these are paid services.

For the purpose of this tutorial, you can select the Keep standalone option. Then you can decide whether you want any paid services later.

After clicking Continue, you'll see a modal indicating that your workspace is ready to use. Then you should see your new chat room. The default channel created by the Setup Wizard is general.

Image showing Rocket.Chat after completing the setup wizard. Sidebar on the left shows a general channel, and primary windows shows a system message that "nhcarrigan has joined the channel".

If you see this, congratulations. You are half way there and now have a functional chat server.

How to Set up a Bot Account in Rocket.Chat

Now we need to create a bot user in our local chat server for our code to connect to.

Select the three dots at the top of the sidebar and choose Administration. Then select Users from the new sidebar that appears, and click the +New button in the top right. This opens a pane for creating a new user account.

Fill in the information and credentials for your bot account.

A few key things to note:

Leave Require password change and Set random password and send by email set to off.
Leave Send welcome email set to off.
Select bot from the Roles dropdown menu.

Image showing the Rocket.Chat settings screen. The left sidebar shows the list of settings - Users has been selected. The center screen shows a list of user accounts - nhcarrigan and Rocket.Cat. The right sidebar shows the Add User interface, with inputs for Name set to Tutorial Bot, Username set to tutorial-bot, Email set to nhcarrigan@gmail.com, Verified toggled off, Status Message with no value, Bio with no value, Nickname with no value, Password which is obfuscated, Require Password Change which is toggled off, Set random password and send by email which is toggled off, Roles with "bot" selected, Join default channels which is toggled on, and Send Welcome Email which is toggled off.

Rocket.cat is a built-in account used for system notifications (i.e. Rocket.Chat updates).

Save the changes, and your bot account should now be created! Keep a note of the username and password, as we will need these for the code.

How to Code your Rocket.Chat Chatbot

Now it's time to create the code. Start with a new, empty folder for your project.

Initial Rocket.Chat Chatbot Project Setup

We will begin with initializing a node.js project. You are welcome to use npm init to generate a package.json, or you may create one manually.

Either way, you will need to add some specific values to the scripts section:

  "scripts": {
    "prebuild": "rm -rf ./prod",
    "build": "tsc",
    "start": "node ./prod/bot.js"
  },

Next you will install your necessary dependencies. First, install the development dependencies:

npm install --save-dev typescript @types/node

Then, install your primary dependencies:

npm install @rocket.chat/sdk dotenv

Your next step is to set up the TypeScript configuration.

If you have installed TypeScript globally, you'll be able to call tsc --init and automatically generate a configuration file. Otherwise, you'll need to manually create a tsconfig.json file in your project's root directory.

Either way, these are the settings you will need for this project:

{
  "compilerOptions": {
    "target": "ES5",
    "module": "CommonJS",
    "rootDir": "./src",
    "outDir": "./prod",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "noImplicitAny": false,
  }
}

If you are using git for version control, you will need to create a .gitignore file. This file tells git which files/folders to ignore. In this case, you want to ignore:

the compiled JavaScript in prod
your Node modules
your .env secrets.

Add these to your .gitignore:

/node_modules/
/prod/
.env

Speaking of secrets, you should set those up now. Create a .env file, and add the following values:

ROCKETCHAT_URL="localhost:3000"
ROCKETCHAT_USER="tutorial-bot"
ROCKETCHAT_PASSWORD="********"
ROCKETCHAT_USE_SSL=""

View the code at this point.

How to Write the Primary Rocket.Chat ChatBot Code

Now it is time to write the initial bot code. Create a src folder within your project directory, and inside that src folder create a bot.ts file. Your file structure should now look like this:

_Image showing a file tree. From top to bottom: A node_modules folder, which is collapsed, a src folder which contains a bot.ts file, a .env file, a .gitignore file, a .package-lock.json file, a package.json file, and a tsconfig.json file. The files show they are being tracked by git, except the node_modules folder and .env file._

The package-lock.json file is created/updated by npm whenever you run install. This should be committed to your repository too, as it is required for the npm ci command.

Within your bot.ts file you will write the basic code that powers your bot. Start with your necessary imports:

import { api, driver } from "@rocket.chat/sdk";
import dotenv from "dotenv";

Because node doesn't load environment variables automatically, you need to call dotenv's config() method to bring your .env values into the node process:

dotenv.config();

Now you can extract those variables from the node environment. Use destructuring to grab the values:

const {
  ROCKETCHAT_URL,
  ROCKETCHAT_USER,
  ROCKETCHAT_PASSWORD,
  ROCKETCHAT_USE_SSL,
} = process.env;

Aside from ROCKETCHAT_USE_SSH, these environment values are required. Missing one will cause the code you write to error out, so you need to add a step to verify that all of these values are present.

if (!ROCKETCHAT_URL || !ROCKETCHAT_USER || ROCKETCHAT_PASSWORD) {
  console.error("Missing required environment variables.");
  process.exit(1);
}

Now you can use the Rocket.Chat SDK to connect your bot to the account you created.

Because the methods in the SDK are asynchronous, you will use an anonymous immediately-invoked function expression (IIFE) to enable async/await features.

(async () => {
  // Nothing here yet
})();

These next steps will be written inside this function.

First, determine if your bot should use SSL to connect to the chat server. If your chat server uses HTTPS://, this should be set to true. Because you are developing locally, this is set to false as localhost does not have an HTTPS protocol.

To ensure your code would work in a production environment as well, you can dynamically set this value based on your environment variables:

const ssl = !!ROCKETCHAT_USE_SSL;

Next, use the SDK driver to interface with your chat server. Connect the driver to your server:

await driver.connect({ host: ROCKETCHAT_URL, useSsl: ssl });

await driver.login({
    username: ROCKETCHAT_USER,
    password: ROCKETCHAT_PASSWORD,
  });
await api.login({ username: ROCKETCHAT_USER, password: ROCKETCHAT_PASSWORD });

Have the bot join your general room, to handle instances where the bot isn't already in the room. Also tell the bot to listen for messages with the subscribeToMessages() method.

  await driver.joinRooms(["general"]);
  await driver.subscribeToMessages();

Finally, have the bot send a message when it comes online (so you can confirm connection status).

  await driver.sendToRoom("I am alive!", "general");

Now, build and run the code. Call these necessary scripts in your terminal:

npm run build
npm run start

After some built-in logging from the SDK, you should see the bot send its online message in your chat server.

Image depicting a Rocket.Chat message. The message was sent by tutorial-bot, which has the bot role by its name. The message text reads I am alive!.

View the code at this point.

How to Write the Command Handler

Your bot will now connect to the chat server and listen for messages, but it does not have any functions.

Before you can add commands, you need to build the infrastructure to handle those commands.

First, tell the bot to handle messages. Just after your subscribeToMessages() call, add a line to handle responding to messages:

driver.reactToMessages();

You'll see an error in your Intellisense, because the reactToMessages() method expects a callback function.

You could write the callback function within this method directly, but instead you will modularise your code and create an exported handler. This keeps your code cleaner and more maintainable.

Create a folder called commands within your src folder, and add two files: CommandHandler.ts and CommandList.ts. Within the CommandList.ts file, we are going to add a single line for now:

export const CommandList = [];

As you build commands, you will add them to this array to be able to iterate through them in our handler.

Now you need to write your handler's logic in the CommandHandler.ts file.

Start with your required imports:

import { driver } from "@rocket.chat/sdk";
import { IMessage } from "@rocket.chat/sdk/dist/config/messageInterfaces";
import { CommandList } from "./CommandList";

Define the command handler function:

export const CommandHandler = async (
    err: unknown,
    messages: IMessage[]
): Promise<void> => {
    // Code will go here.
}

Add some error handling.

  if (err) {
    console.error(err);
    return;
  }
  const message = messages[0];
  if (!message.msg || !message.rid) {
    return;
  }

If you see an error in the err parameter, you need to return early.

The messages parameter takes an array of messages, but you want to react to the first message, so we extract it from that array as message.

Then, for TypeScript's assertion handling, you need to exit early if certain properties are missing or undefined. In this case, message.msg is the text content of the message, and message.rid is the ID of the room the message was received in.

For cleaner/more readable code, you can destructure some values out of the message object. Get the room's name from the rid value - the SDK includes a method for doing just this. Also get the prefix and the command that is called.

  const roomName = await driver.getRoomName(message.rid);
  const [prefix, commandName] = message.msg.split(" ");

Add the logic to iterate through our array of commands. TypeScript will identify some errors due to missing structures, but you can ignore those for now as you have not written the commands yet.

  if (prefix === "!fCC") {
    for (const Command of CommandList) {
      if (commandName === Command.name) {
        await Command.command(message, roomName);
        return;
      }
    }
    await driver.sendToRoom(
      `I am sorry, but \`${commandName}\` is not a valid command.`,
      roomName
    );
  }

This block of code might be a bit confusing as we have not established how commands work yet.

First, the bot determines if the message begins with the correct prefix. If it does not, the bot will ignore the message.

Then the bot iterates through the list of commands, and if it finds a command for which the name value matches the command name sent in the message, it will run that command.

If it does not find any matching commands, it will send a response in the room that the command was not valid.

Before you move on to a command, head back to the reactToMessages() call in the bot.ts file and pass your new handler as the callback:

  driver.reactToMessages(CommandHandler);

You may need to manually import it:

import { CommandHandler } from "./commands/CommandHandler";

View the code at this point.

How to Write a Command

TypeScript offers an interface feature which can be used to define an object structure.

In your src folder, create an interfaces folder, and create a CommandInt.ts file.

Inside that file, you will define your command type. First, import the message type again.

import { IMessage } from "@rocket.chat/sdk/dist/config/messageInterfaces";

Now build the exported interface for the command definitions.

export interface CommandInt {
    name: string;
    description: string;
    command: (message: IMessage, room: string) => Promise<void>
}

Congratulations! You are now ready to build the ping command.

Within your src/commands folder, create a ping.ts file. Start with your necessary imports: the Rocket.Chat driver and your new command interface.

import { driver } from "@rocket.chat/sdk";
import { CommandInt } from "../interfaces/CommandInt";

Define and export the command:

export const ping: CommandInt = {
    name: "ping",
    description: "Pings the bot.",
    command: async (message, room) => {
        // Code will go here.
    }
}

Let's have the bot respond with "Pong!" when this command is called. Inside the function, replace the comment with:

await driver.sendToRoom("Pong!", room);

Now, load this command in your list of commands. Open the CommandList.ts file, where you will import our new command and include it in the array.

import { ping } from "./ping";

export const CommandList = [ping];

With this, you should see the errors in the CommandHandler.ts file disappear as well, because TypeScript is inferring that the CommandList array contains CommandInt types.

For extra type safety, and to ensure you do not accidentally add values to your CommandList that aren't proper CommandInt objects, explicitly type this variable.

import { CommandInt } from "../interfaces/CommandInt";
import { ping } from "./ping";

export const CommandList: CommandInt[] = [ping];

Run your build and start scripts again to test this new feature.

Call your ping command in the chat room. You should see a successful response:

Image depicting a Rocket.Chat conversation. The first message was sent by nhcarrigan, who has the Admin role by his name. The first message content reads "!fCC ping". The second message was sent by tutorial-bot, which has the Bot role by its name. The second message content reads "Pong!".

Call a pong command. You should see that the bot identifies it is not a valid command:

Image depicting a Rocket.Chat conversation. The first message was sent by nhcarrigan, who has the Admin role by his name. The first message content reads "!fCC pong". The second message was sent by tutorial-bot, which has the Bot role by its name. The second message content reads "I am sorry, but pong is not a valid command".

View our final code.

Further Exploration

Congratulations! You have now successfully built a basic Rocket.Chat chatbot.

If you would like to explore further features and command implementations, feel free to browse our live bot's codebase.

Naomi Carrigan - freeCodeCamp.org

Learn React in your Browser – freeCodeCamp Full Stack Curriculum Mid-2025 Update

New Curriculum Coursework

Exams

What’s Next?

Get Involved

How to Help Someone with Their Code Using the Socratic Method

What is the Socratic Method?

Socrates in Modern Culture

Goal of the Socratic Method

Long-Term Benefits of the Socratic Method

Conclusion

Sources:

How to Claim Your Supporter Role on Discord

Claim Your Role

Error Messages

Already Have Role

Record for Discord Server Exists

Record for Email Exists

Not a Supporter

No freeCodeCamp account

Thank You

Hacktoberfest 2023 Contributors

Hacktoberfest Contributions for freeCodeCamp

Hacktoberfest Contributions for DevDocs

Hacktoberfest 2022 Contributors

Hacktoberfest Contributions for freeCodeCamp

Hacktoberfest Contributions for DevDocs

Hacktoberfest Contributions for Developer Quiz Site

How to Set Up Your Own Mastodon Instance

What is Mastodon?

Getting Started with Mastadon

How to Set Up Your Mastadon Instance

How to Configure Your Mastadon Instance

How to Manage Users

Conclusion

How to Set Up a GitHub OAuth Application

Create Your Application

Using Your New Application

How to Use RegEx to Match Emoji – Discord Emotes Regular Expression Tutorial

How Unicode Emoji Work

What are Discord Emotes?

How to Match Emoji and Emotes with RegEx

Conclusion

Build a 100 Days of Code Discord Bot with TypeScript, MongoDB, and Discord.js 13

How to Add Sentry to Your Node.js Project with TypeScript

How to Prepare Your Sentry Account

How to Use Sentry in Your Code

How to Connect Your Code to Your Dashboard

How to Configure Your Sentry Dashboard

Conclusion

How to Use TypeScript and MongoDB to Build a 100 Days of Code Discord Bot

How to Create a Discord Bot Application

How to Set Up Your Project

Prepare the package.json

Prepare TypeScript

Additional Setup Notes

How to Create the Discord Bot

Gateway Events in Discord

How to Connect to the Database

Environment Variable Validation

The "message" Event

How to Prepare for Commands

Define an Interface

Create a Command List

Check for Commands

Database Model

How to Write Bot Commands

100 command

View command

Edit command

Help command

Conclusion

What is SendGrid? SMTP Email Newsletter Tutorial

What Is SMTP?

What is SendGrid?

How to Create a SendGrid Account

How to Set up Your Domain or Email with SendGrid

How to Send Emails Via SendGrid's API

How to Use Dynamic Templates in SendGrid

Prepare the `package.json`