Orim Dominic Adah - freeCodeCamp.org

How to Create Dynamic Emails in Go with React Email

Orim Dominic Adah — Mon, 20 Apr 2026 20:16:44 +0000

Backend applications are required to send emails to users to deliver notifications and maintain communication outside the application interface. These emails usually contain information specific to each user, such as the user's name or address, making them dynamic.

This article walks you through building a dynamic email template with React Email, converting it to HTML, and injecting data into it using Go templates. It also contains an optional section that shows you how to send and test the email delivery with MailHog.

To follow along with this article, you need to have Go and Node.js installed on your computer. You should also have a basic understanding of React and some familiarity with Go templates, though these aren't strict requirements because you can pick them up as you practise along.

What is React Email?
Go Templates
- Go Template Delimiters
Create Dynamic Emails in Go with React Email
Conclusion

What is React Email?

React Email is a JavaScript library that helps you build dynamic email templates with React. If you already know basic React, React Email provides a better developer experience for building dynamic email templates. Here are some reasons why:

Familiar syntax with React: If you know React already, React Email eliminates the hassle in learning a separate templating language, using inefficient drag-and-drop UIs, or writing emaiil templates from scratch with HTML tables.
Reusable built-in components: React Email provides ready-to-use UI components like Buttons and Footers so you don't have to start from scratch, making email development seamless and fast.
Consistency across email clients: React Email generates email templates that have been tested and work well across popular email clients. This helps eliminate worries over emails rendering inconsistently across email clients.
Email development tooling: React Email has features for previewing and assessing emails built with it. Some of these features include:
- A local development server that lets you preview mobile and desktop views of your emails in your web browser as you develop the emails in real time
- An email delivery feature that sends your email to a real email address for preview
- A compatibility checker that shows you how well your email is supported across popular email clients
- A spam scorer that analyses your email to determine if it's likely to be marked as spam
Tailwind integration: Tailwind is a popular CSS framework that provides classes for styling HTML and making it responsive. React Email integrates with Tailwind easily for creating beautiful emails.

All these features are free to use.

In this article, you'll learn how to generate an HTML file from a React Email template, convert it to a Go template, and inject data into the template for previewing.

Go Templates

The Go html/template package allows you to define reusable HTML templates that can be populated with dynamic data. These templates contain placeholders (called actions) that are evaluated by Go's templating engine and replaced with actual values during execution.

First, you give the package HTML content that contains Go-specific annotations. It converts the HTML content to a Go HTML template and the Go-specific annotations to actions in the template. The template is then executed with data to produce HTML output that contains the data.

package main

import (
	"html/template"
	"os"
)

func main() {
	tmpl := template.New("hello")
	tmpl, _ = tmpl.Parse(`Hello {{.}}`)
	tmpl.Execute(os.Stdout, "Gopher")
}

// Output: Hello Gopher
// Playground: https://goplay.tools/snippet/KxbkWPIArz5

In the code snippet above:

template.New creates an empty template object with the name "hello"
tmpl.Parse(`
Hello {{.}}
`) parses the HTML string Hello {{.}} to create a Go HTML template and saves it in tmpl . The {{.}} part of the HTML string is an action which acts as a placeholder for data. {{ and }} are called delimiters and . is the data access identifier.
tmpl.Execute(os.Stdout, "Gopher") populates the action with data - the "Gopher", string, and writes the resulting HTML output to the console.

Go Template Delimiters

In the previous code snippet, you used double curly braces ({{ and }}) as the delimiters in the Go template. Delimiters are symbols that Go uses to determine what parts of the input string represent an action – that is, a statement to be evaluated.

You can change the delimiters by using the Delims method on a template. An example is shown in the snippet below:

package main

import (
	"html/template"
	"os"
)

func main() {
	tmpl := template.New("hello")
	tmpl, _ = tmpl.Delims("((", "))").Parse(`Hello ((.))`)
	tmpl.Execute(os.Stdout, "Gopher")
}

// Output: Hello Gopher
// Playground: https://goplay.tools/snippet/00RuDzvZYwN

In the snippet above, (( and )) are used as the delimiters for the hello template.

This is important because you'll set your delimiters to prevent conflicts between Go's default delimiters and React's curly braces in React Email templates.

Create Dynamic Emails in Go with React Email

The image below summarizes how the sample application you'll build in this article works:

You'll create a React Email template that contains Go template annotations. Next, you'll use Node.js to create HTML files from it. Go will parse the HTML file to create a Go template, execute it, and send it.

Optionally, you'll use go-mail to send the email and MailHog, a local SMTP server, to preview it in your browser.

Set Up the Project

First, make sure that you have Go and Node.js installed on your computer already. Clone this freeCodeCamp-go-react-email repository and checkout the 01-setup branch using git checkout 01-setup.

The project contains a main.go file in the cmd directory and a go.mod file. It also contains a .gitignore file to instruct Git to ignore all node_modules directories.

Run go run cmd/main.go in the terminal of the project. If you see "It works!" logged to the console, you have set it up properly and you can continue to the next section.

Set Up React Email

In the project root directory, create a mailer directory which will serve as the mailer package. It will hold all functionality related to creating and sending mails.

In the mailer directory, you'll create the emails Node.js project that will handle React Email functionality. To create the project:

Create a directory called _emails in the mailer directory. The name of the directory starts with an underscore because it should be ignored when the go build command is run. So it won't be included in the Go compiled executable file.
Run npm init -y in the root terminal of the _emails directory to initialise the Node.js project in it. This will create a package.json file in the directory.
Update the value of the name field in package.json to "emails" to make the package name more conventional. This step is not compulsory.

Next, install the required React Email libraries by running the following commands in the root terminal of the _emails directory:

npm install @react-email/ui @types/react -D -E
npm install react-email react react-dom -E

After the installation is complete, replace the scripts field of the package.json file with the code snippet below:

  "scripts": {
    "dev": "email dev --dir ./src",
    "export": "email export --pretty --dir ./src --outDir ../templates"
  },

The dev script starts and runs the server for previewing the React Email templates in the browser. You will write the template with React and store it in the src directory under _emails. The export script transpiles the template files in the src directory from JSX (or TSX) to HTML and stores them in a directory called templates, a direct child of the mailer directory – not a child of the _emails directory.

The templates directory is stored as a child directory of the mailer directory because the Go project needs only the HTML output stored in the templates directory and not the contents of _emails.

If you've completed all these steps, you have set up React Email in the emails Node.js project. To view the current status of the project at this point, visit freeCodeCamp-go-react-email/02-setup-react-email.

In the next section, you'll create a React Email template and preview it in the browser.

Create a React Email Template

In this section, you'll create a React Email template and preview it in the browser. You'll also build and export the template to HTML files.

Create a directory called src inside the _emails directory. Inside the src directory, create a file called welcome.tsx. Copy and paste the content of the snippet below into welcome.tsx.

import {
  Body,
  Button,
  Container,
  Head,
  Heading,
  Html,
  Img,
  Preview,
  Section,
  Tailwind,
  Text,
} from "react-email";

interface WelcomeEmailProps {
  username?: string;
  company?: string;
  gophers?: string[];
}

const WelcomeEmail = ({
  username = "Nicole",
  company = "GoWorld",
  gophers = ["Tinky Winky", "Dipsy", "Laa-Laa", "Po"],
}: WelcomeEmailProps) => {
  const previewText = `Welcome to \({company}, \){username}!`;

  return (
    
      
      {previewText}
      
        
          
            
              
            
            
              Welcome to {company}, {username}!
            
            Hello {username},
            
              We're excited to have you onboard at {company}.
              We hope you enjoy your journey with us. If you have any questions
              or need assistance, feel free to reach out to any of the following
              gophers:
            
            
              
                {gophers.map((gopher) => (
                  {gopher}
                ))}
              
            
            
              
            
            
              Cheers,
              

              The {company} Team
            
          
        
      
    
  );
};

export default WelcomeEmail;

The code snippet above is the React Email template that you'll use in this article. To preview it, navigate to the terminal of the _emails root directory and run npm run dev . Use your web browser to visit the preview URL displayed on the terminal. Click on the "welcome" link on the left sidebar and you should see a UI similar to the one in the screenshot below:

In the UI above, React Email renders the email with the default values supplied to the welcome email template.

Stop the server by clicking on the terminal that runs it by pressing CTRL + C. Build the HTML output of the src directory and export it by running npm run export in the terminal of the _emails root directory. This creates a templates directory within the mailer directory where the exported HTML files are stored. In the templates directory, you'll see a welcome.html file – the HTML output from welcome.tsx.

To see the current status of the project, visit freeCodeCamp-go-react-email/03-create-react-email-template.

Set Up Go Templates from HTML Files

You have created a React Email template, previewed it, built it, and exported it as an HTML file. In this section, you'll update the React Email template to use the delimiters you set and not React's curly braces. You'll also create a Go template from the HTML file.

To get started, replace the content of welcome.tsx with the code snippet below to to use (( and )) as delimiters and remove TypeScript types:

import {
  Body,
  Button,
  Container,
  Head,
  Heading,
  Html,
  Img,
  Preview,
  Section,
  Tailwind,
  Text,
} from "react-email";

const WelcomeEmail = () => {
  const previewText = `Welcome to ((.Company)), ((.Username))!`;

  return (
    
      
      {previewText}
      
        
          
            
              
            
            
              Welcome to ((.Company)), ((.Username))!
            
            Hello ((.Username)),
            
              We're excited to have you onboard at ((.Company))
              . We hope you enjoy your journey with us. If you have any
              questions or need assistance, feel free to reach out to any of the
              following Gophers:
            
            
              
                ((range .Gophers))
                ((.))
                ((end))
              
            
            
              
            

            
              Cheers,
              

              The ((.Company)), Team
            
          
        
      
    
  );
};

export default WelcomeEmail;

Run npm run export in the root terminal of the _emails directory to build and export this version of the React Email template to HTML. The HTML generated will contain Go template annotations that will become actions when parsed by Go to form a Go HTML template.

In the mailer directory, create a file named fs.go. The code in the file will be used to embed the files in the templates directory for use in the Go application. Copy and paste the content of the snippet below into fs.go:

package mailer

import (
	"embed"
	"io/fs"
)

//go:embed templates/*
var embedded embed.FS
var templateFS, _ = fs.Sub(embedded, "templates")

//go:embed templates/* tells the Go compiler to embed files from the current directory (mailer) into the compiled binary of the Go application. You need this to access the HTML template files from the Go application. templateFS will be used to access the files in the templates subdirectory.

Create another file in the mailer directory and name it mailer.go. mailer.go will contain code used to parse HTML files to make Go HTML templates and also send emails. Copy the content of the code snippet below into mailer.go:

package mailer

import (
	"html/template"
	"io"
)

const (
	welcomeMailKey = "welcome_mail"
)

func setUpTemplates() (map[string]*template.Template, error) {
	templates := make(map[string]*template.Template)

	tmpl := template.New("welcome.html").Delims("((", "))")
	welcomeEmailTmpl, err := tmpl.ParseFS(templateFS, "welcome.html")
	if err != nil {
		return nil, err
	}

	templates[welcomeMailKey] = welcomeEmailTmpl

	return templates, nil
}

type Mailer struct {
	templates map[string]*template.Template
}

// NewMailer creates a new mailer
func NewMailer() (*Mailer, error) {
	tpls, err := setUpTemplates()
	if err != nil {
		return nil, err
	}

	return &Mailer{
		templates: tpls,
	}, nil
}

type WelcomEmailData struct {
	Username string
	Company  string
	Gophers  []string
}

func (mailer *Mailer) WriteWelcomeMail(w io.Writer, data WelcomEmailData) error {
	tmpl := mailer.templates[welcomeMailKey]
	err := tmpl.Execute(w, data)

	return err
}

In the code snippet above:

setUpTemplates creates a template object, tmpl, and sets its delimiters. tmpl parses welcome.html to convert it to a Go template and stores the template with welcomeEmailTmpl as its identifier. After that, welcomeEmailTmpl is added to the templates map with welcomeMailKey as its key and templates is returned.
NewMailer creates and returns a Mailer object which holds the templates map and methods to work with the mail templates.
WriteWelcomeMail is a method on Mailer that's used to execute the welcome email template with real data.

To view the current status of the codebase at this point, visit freeCodeCamp-go-react-email/04-create-golang-template.

Render the Dynamic Email in the Browser

In this section, you'll create a simple web server to view the rendered email template containing the dynamic values passed to it.

Replace the content of main.go with the code snippet below:

package main

import (
	"fmt"
	"net/http"
	"os"

	pkgMailer "github.com/orimdominic/freeCodeCamp-go-react-email/mailer"
)

func main() {
	mailer, err := pkgMailer.NewMailer()
	if err != nil {
		fmt.Fprint(os.Stderr, err)
		os.Exit(1)
	}

	http.HandleFunc("/mail", func(w http.ResponseWriter, r *http.Request) {
		username := r.URL.Query().Get("username")
		company := r.URL.Query().Get("company")
		gophers := []string{"Tinky Winky", "Dipsy", "Laa-Laa", "Po"}

		err := mailer.WriteWelcomeMail(w, pkgMailer.WelcomEmailData{
			Username: username,
			Company:  company,
			Gophers:  gophers,
		})
		if err != nil {
			http.Error(w, err.Error(), http.StatusInternalServerError)
			return
		}
	})

	port := ":8888"
	err = http.ListenAndServe(port, nil)
	if err != nil {
		fmt.Fprint(os.Stderr, err)
		os.Exit(1)
	}
}

The code snippet above first creates a mailer object using the NewMailer function from mailer.go. After the error handling, it creates a simple web server running on port 8888 with a GET /mail route.

The GET /mail route accepts two query parameters: username and company, which will be used as the dynamic data for the email. The result of executing the template with WriteWelcomeMail is written as an HTML response on the browser. You'll use this route to test the functionality of the mailer package.

Before you start the server, you should build and export the React Email templates so that your HTML files always have the most recent changes from React Email templates. Instead of navigating between different directories to build, export and run the server, you can use a Makefile.

Navigate to the terminal of the root directory of the project and create a file called Makefile. Copy and paste the content of the code snippet below into it:

run: email-build
	go run cmd/main.go

email-build: mailer/_emails
	npm --prefix mailer/_emails run export

The run script of the Makefile above builds and exports the React Email templates as HTML to the mailer/templates directory and then starts the Go application. Ensure that Makefile uses hard tabs, not spaces for indentation.

Run make run in the terminal of the root directory of the project and visit http://localhost:8888/mail?username=Nicole&company=GoWorld in the browser. You'll see the email rendered on the browser UI.

Replace the values of username and company in the URL to test the email with different values.

With this setup, you can integrate the result of executing the template with your mail client and the email recipient will see the email as it's displayed in the browser.

To view the current status of the codebase at this point, visit freeCodeCamp-go-react-email/05-render-dynamic-email.

Send and Test Email with go-mail and MailHog

In the previous section, you supplied data to execute your template, but it was rendered in the browser, not an email client. In this section, you'll use go-mail to send the email and MailHog to intercept and view it.

This section is optional. If you don't have MailHog installed locally, you'll need Docker Compose to set it up for this project. Make sure Docker Compose is installed on your computer before proceeding.

In your terminal, navigate to the root directory of the project and run go get github.com/wneessen/go-mail to install go-mail. Create a compose.yml file in the root directory of the project and paste the contents of the code snippet below into it:

services:
  mailhog:
    image: mailhog/mailhog
    restart: no
    logging:
      driver: "none" # disable saving logs
    ports:
      - 1025:1025 # smtp server
      - 8025:8025 # web ui

In your terminal, navigate to the project's root directory and run docker compose up to pull and start the MailHog SMTP server. MailHog listens for emails on port 1025 and exposes a web UI at http://localhost:8025 where you can view intercepted emails. Depending on your internet connection, the initial image pull may take a few minutes.

Replace mailer.go with the content of the code snippet below:

package mailer

import (
	"html/template"
	"io"

	"github.com/wneessen/go-mail"
)

const (
	welcomeMailKey = "welcome_mail"
    sender = "noreply@localhost.com"
)

func setUpTemplates() (map[string]*template.Template, error) {
	templates := make(map[string]*template.Template)

	tmpl := template.New("welcome.html").Delims("((", "))")
	welcomeEmailTmpl, err := tmpl.ParseFS(templateFS, "welcome.html")
	if err != nil {
		return nil, err
	}

	templates[welcomeMailKey] = welcomeEmailTmpl

	return templates, nil
}

type Mailer struct {
	client    *mail.Client
	templates map[string]*template.Template
}

// NewMailer creates a new mailer
func NewMailer() (*Mailer, error) {
	tpls, err := setUpTemplates()
	if err != nil {
		return nil, err
	}

	c, err := mail.NewClient(
		"localhost",
		mail.WithPort(1025),
		mail.WithTLSPolicy(mail.NoTLS),
	)

	if err != nil {
		return nil, err
	}

	return &Mailer{
		client:    c,
		templates: tpls,
	}, nil
}

type WelcomEmailData struct {
	Username string
	Company  string
	Gophers  []string
}

func (mailer *Mailer) WriteWelcomeMail(w io.Writer, data WelcomEmailData) error {
	tmpl := mailer.templates[welcomeMailKey]
	err := tmpl.Execute(w, data)

	return err
}

func (mailer *Mailer) SendWelcomeMail(to string, data WelcomEmailData) error {
	m := mail.NewMsg()
	m.From(sender)
	m.To(to)
	m.Subject("Welcome to " + data.Company)
	m.SetBodyHTMLTemplate(mailer.templates[welcomeMailKey], data)

	err := mailer.client.DialAndSend(m)
	return err
}

The new changes to mailer.go include:

An import of the go-mail
The creation of a sender constant which represents the email of the sender
The creation of a mail client with go-mail
The creation of a SendWelcomeMail method on the mailer struct which creates an email with welcomeEmailTmpl, executes it, and sends it to a receiver.

In main.go, update the GET /mail route to use SendWelcomeMail instead of WriteWelcomeMail. You can use any email address you want. The snippet below uses fcc@go.dev:

		err := mailer.SendWelcomeMail("fcc@go.dev", pkgMailer.WelcomEmailData{
			Username: username,
			Company:  company,
			Gophers:  gophers,
		})
		if err != nil {
			http.Error(w, err.Error(), http.StatusInternalServerError)
			return
		}

		fmt.Fprint(w, "Email sent")

Ensure that the mail server is running by visiting http://localhost:8025 in your web browser. In another terminal, from the root directory of the project, run make run to start the server. Test the functionality of the route by visiting http://localhost:8888/mail?username=Nicole&company=GoWorld once again. Next, check the email server by visiting http://localhost:8025. You should see a UI similar to the one in the screenshot below:

Click on "Welcome to Helix" to view the email.

To view the current status of the codebase at this point, visit freeCodeCamp-go-react-email/06-send-email.

Conclusion

By following along with this tutorial, you have:

Learned how to create Go email templates from React Email templates
Learned how to use Makefiles to run custom scripts
Previewed your email in the browser and tested it using MailHog

You can now skip the hassle of writing raw HTML email tables or learning a new templating language. With React Email and Go templates, you have a cleaner, more developer-friendly way to build and send beautiful emails.

How to Build a Voice-Powered AI Application with the Web Speech API

Orim Dominic Adah — Thu, 26 Mar 2026 21:18:39 +0000

The Web Speech API is a web browser API that enables web applications to use sound as data in their operations. With the API, web apps can transcribe the speech in sound input and also synthesise speech from text.

This guide shows you how to build a full-stack web application that:

Accepts audio input and transcribes the speech in it
Prompts an AI agent with the transcription
Displays the AI response on the UI

The application you'll build will be a simplified version of the Use Voice feature on AI chat applications highlighted in the image below:

By practising along with this article, you'll learn how to:

Build a frontend application that uses the SpeechRecognition API to accept voice input and transcribe it
Build a backend app that prompts an AI assistant of your choice and sends a response back to clients
Connect both applications together to send the transcription to the backend as a prompt and display the AI response on the frontend

Optionally, you'll also learn how to host the frontend with Firebase and the backend with Google Cloud Run.

Prerequisites
The Web Speech API
- How to Use the Web Speech API in JavaScript for SEO
How the Application Works
How to Build the Application
Test the Application Locally
Deploy the Backend Application with Google Cloud Run
Deploy the Frontend Application with Firebase
Connect the Deployed Applications
Conclusion

Prerequisites

This guide assumes that you have a working knowledge of HTML, CSS, and JavaScript in the browser. Basic familiarity with Node.js is beneficial but not essential.

In addition, you should have:

Google Chrome (at least version 33 ) and a functional audio input device
Node.js and npm installed on your computer
An API key from any AI assistant of your choice
A Google Cloud account and a Firebase account if you intend to deploy the applications

The Web Speech API

The Web Speech API enables applications to transcribe the speech in audio input and also synthesise audio from text. The API is made up of two components:

The SpeechRecognition component which receives audio input, recognises speech in the input and transcribes it
The SpeechSynthesis component which synthesises speech from text

You'll use the SpeechRecognition component in this guide.

How to Use the Web Speech API in JavaScript for SEO

The SpeechRecognition component works through a JavaScript object instantiated in code.

const recognition = new SpeechRecognition();

The recognition instance exposes several event listeners that respond to audio input. For example, the audiostart event fires when sound is first detected, logging "audio detected" to the console as shown in the snippet below.

recognition.addEventListener("audiostart", function(event){
  console.log("audio detected")
}

The first time it recognises speech in a sound bite, the speechstart event is fired.

A SpeechRecognition instance also has the ability to configure how speech recognition should work. For example, it has a property called lang which sets the language that it should recognise. The default value of the lang property is the HTML lang attribute value, or the browser's language setting. It also has a boolean property called interimResults, which when set to true, enables the instance to return transcriptions incrementally rather than waiting for the audio input to end.

Audio captured by the microphone is processed by a recognition engine which could be in a remote server (for Google Chrome) or embedded in the browser (for Firefox).

After processing, the recognition engine returns a result, which is a list of words or phrases that have been recognised in the speech.

Each transcription in the list has two properties: confidence, a numerical estimate of its accuracy ranging from 0 (low) to 1 (high), and transcript, the recognised text for all or part of the speech.

How the Application Works

In order for a SpeechRecognition instance to capture audio, it needs access to the microphone. The browser requests permission to use the microphone and, if granted, the application uses it to capture audio for the instance.

Speech captured by the instance goes through the recognition engine and produces results or transcriptions. Results with high confidence are combined and sent to the backend via an API request.

The backend uses the transcript it receives to prompt an AI assistant. The response from the AI assistant is sent back to the frontend and displayed on the UI as shown in the screenshot below:

How to Build the Application

First, you'll build a Node.js backend application that:

Receives a text prompt from the frontend
Sends the prompt to an AI assistant and receives a response
Returns the response of the AI assistant to the frontend

Next, you'll build the frontend to:

Accept your speech prompt, transcribe it, and display the transcription
Send the transcription result to the backend
Receive, format and display the response from the backend

Optionally, you'll deploy the frontend to Firebase and the backend to Google Cloud Run, connecting them so the application is publicly accessible.

Create the Backend Application with Node.js

The backend application you'll build in this section will receive text prompt from clients and use it to prompt an AI assistant. After receiving a response from the AI assistant, it will send the response back to the client.

We'll use Gemini in this guide, but you can use any AI assistant of your choice.

Create a folder for the backend app and give it a name, for example, "server".
In terminal, navigate to the project folder, run the npm init command, and answer the follow-up questions to generate a package.json file
In the root of the project, create a file named index.js.

Your project folder should have a structure like this:

├── index.js
├── package.json

The package.json file should have the following values for main , type and scripts.start:

 { 
    "main": "index.js", 
    "type": "module", 
    "scripts": { 
       "start": "node index.js" 
    }, 
}

Copy and paste the code below into the index.js file to set up the server:

import http from "node:http";

async function parseRequestBody(req) { 
    return new Promise((resolve, reject) => { 
        let data = ""; 
        req.on("data", (chunk) => (data += chunk)); 
        req.on("end", () => resolve(JSON.parse(data))); 
        req.on("error", reject); 
    }); 
}

const server = http.createServer(async function (req, res) { 
    switch (req.method) { 
        case "POST":
          return res.end("POST request received");
        default:
          return res.end("non-POST request received");
    }
})

const port = Number(process.env.PORT) || 8000; 
server.listen(port, function () { 
    console.log("server running on port", port); 
});

In the code snippet above, the http module is imported from Node.js. The parseRequestBody function converts the request body stream of a HTTP request to a JavaScript object.

It responds with POST request received for POST requests and non-POST request received for all others. By default, it listens on port 8000 unless a PORT environment variable is defined.

Run npm run start to start the server. To confirm it is running, execute the following command in the terminal:

# For Linux/Mac, use:
curl -X POST -H "Content-Type: application/json" -d '{"prompt":"hello"}' http://localhost:8000

# For Windows, use:
curl.exe -X POST -H "Content-Type: application/json" -d '{"prompt":"hello"}' http://localhost:8000

You'll get the POST request received response from the server.

Integrate an AI Assistant into the Node.js Application

In this section, you'll integrate the AI assistant into the backend application, prompt it with data sent from the frontend, and return its response to the client. Again, we'll use Gemini for this here.

Visit the npm page for your chosen AI assistant to learn how to install and set it up. Here are the npm pages for the most popular AI assistants:

Update the index.js file to include the setup for the AI assistant using the snippet below:

import http from "node:http";
import { GoogleGenAI } from "@google/genai"; 

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

async function parseRequestBody(req) { /* minimised code */ }

const server = http.createServer(async function (req, res) {
    res.setHeader("Access-Control-Allow-Origin", "*");

    switch (req.method) { 
        case "POST":
          const body = await parseRequestBody(req);
          const response = await ai.models.generateContent({
            model: "gemini-2.5-flash", // or whatever model you have
            contents: body.prompt,
         });

         return res.end(response.text);

        default:
          return res.end("non-POST request received");
    }
}
/* previous code minimised*/

The GEMINI_API_KEY is retrieved from the environment variables and passed as the apiKey to GoogleGenAI, which initialises the AI assistant.

The POST request body is parsed into a JavaScript object, and body.prompt is passed to ai.models.generateContent to prompt the AI assistant. The text property of the response which is in Markdown format, is then returned to the client.

Restart the server and test the current setup by making an API request to it with curl using the snippet below:

# For Linux/Mac:

curl -X POST -H "Content-Type: application/json" -d '{"prompt":"hello"}' http://localhost:8000

# For Windows:

curl.exe -X POST -H "Content-Type: application/json" -d '{"prompt":"hello"}' http://localhost:8000

You'll get an AI text response in the form of Markdown.

Create the Frontend Application with Vite

Vite is a build tool that provides a faster and more seamless development experience for developing applications. You'll use Vite to create the frontend application and connect it with the backend application from the previous section.

In another folder, create a project with Vite by running the npm create vite@latest command and answer the prompts:

npm create vite@latest

Need to install the following packages:
create-vite@8.1.0
Ok to proceed? (y) y

> npx create-vite

◇  Project name:
│  [name-of-your-frontend-app] e.g prompt-ai-with-speech-frontend
│
◇  Select a framework:
│  Vanilla
│
◇  Select a variant:
│  JavaScript
│
◇  Use rolldown-vite (Experimental)?:
│  No
│
◇  Install with npm and start now?
│  Yes

Open the project created in your code editor and make the following updates:

First, replace the content of index.html with the code snippet below:



  
    
    
    Prompt AI with the Web Speech Recognition API
  
  
    
      
        Prompt AI with the Web Speech Recognition API

Then replace the content of src/style.css with the code snippet below:

:root {
  font-family: system-ui, Avenir, Helvetica, Arial, sans-serif;
  line-height: 1.5;
  font-weight: 400;

  color-scheme: light dark;
  color: rgba(255, 255, 255, 0.87);
  background-color: #242424;

  font-synthesis: none;
  text-rendering: optimizeLegibility;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

button {
  border-radius: 8px;
  border: 1px solid transparent;
  padding: 0.6em 1.2em;
  font-size: 1em;
  font-weight: 500;
  font-family: inherit;
  background-color: #1a1a1a;
  cursor: pointer;
  transition: border-color 0.25s;
}
button:hover {
  border-color: #646cff;
}
button:focus,
button:focus-visible {
  outline: 4px auto -webkit-focus-ring-color;
}
.btn_container {
  padding: 16px 0px;
  display: flex;
  justify-content: center;
}

#ulist_chat {
  display: flex;
  flex-direction: column;
  width: 80%;
  margin: auto;
  padding: 0;
}

#ulist_chat .transcript {
  border: 1px solid tomato;
  background: #fce5e5af;
  border-radius: 4px;
  align-self: flex-end;
  list-style-type: none;
  margin: 8px;
  padding: 8px;
  max-width: 80%;
}

#ulist_chat .ai_response p { 
  margin: 2px; 
}

#ulist_chat .ai_response {
  border: 1px solid green;
  background: #e5fce8af;
  border-radius: 4px;
  align-self: flex-start;
  list-style-type: none;
  margin: 8px;
  padding: 8px;
  max-width: 80%;
}

@media (prefers-color-scheme: light) {
  :root {
    color: #000;
    background-color: #ffffff;
  }
  a:hover {
    color: #747bff;
  }
  button {
    background-color: #f9f9f9;
  }
}

Now replace the content of src/main.js with the code snippet below:

import "./style.css";
import { marked } from "marked";

const apiUrl = "http://localhost:8000";
const btnRecord = document.getElementById("btn_record");
const uListChat = document.getElementById("ulist_chat");

function ensureBrowserHasSpeechAPI() {
  if (
    !("webkitSpeechRecognition" in window) &&
    !("SpeechRecognition" in window)
  ) {
    btnRecord.style.display = "none";

    return alert(
      "This browser does not have the features required for this demo. Use Google Chrome >= v33"
    );
  }

  start();
}

function toggleRecording(config, listener) {
  if (config.isListening) {
    config.isListening = false;
    btnRecord.innerText = "Start recording";
    return listener.stop();
  }

  config.isListening = true;
  btnRecord.innerText = "Stop recording";

  return listener.start();
}

/** @param {string} transcript  */
function appendTranscriptToChatList(transcript) {
  const li = document.createElement("li");
  li.innerText = transcript;
  li.classList.add("transcript");
  uListChat.appendChild(li);
}

/** @param {string} aiResponse  */
function appendAIResponseToChatList(aiResponse) {
  const li = document.createElement("li");
  li.innerHTML = marked.parse(aiResponse);
  li.classList.add("ai_response");
  uListChat.appendChild(li);
}

/** @param {string} prompt  */
async function promptAI(prompt) {
  try {
    const response = await fetch(apiUrl, {
      body: JSON.stringify({ prompt }),
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
    });

    if (!response.ok) {
      const err = await response.text();
      console.error(err);
      alert("An error occurred. Try again");
      return;
    }

    const text = await response.text();
    return text;
  } catch (error) {
    logError(error);
    alert("An error occurred. Try again");
    return ""
  }
}

function setUpSpeechRecognition() {
  const SpeechRecognition =
    window.SpeechRecognition || window.webkitSpeechRecognition;

  const listener = new SpeechRecognition();
  listener.continuous = true; // listen for long speech
  listener.maxAlternatives = 2; // only two transcription suggestions required
  let transcript = "";

  // automatic: onstart -> onaudiostart -> onsoundstart -> onspeechstart
  // automatic: onspeechend -> onsoundend -> onaudioend -> onresult -> onend
  // click button: onaudioend -> onresult -> onend

  listener.onend = async function () {
    if (!transcript || !transcript.trim()) return;

    btnRecord.innerText = "Thinking...";
    btnRecord.disabled = true;
    appendTranscriptToChatList(transcript);
    promptAI(transcript)
      .then(function (res) {
        appendAIResponseToChatList(res);
      })
      .finally(function () {
        btnRecord.innerText = "Record prompt";
        btnRecord.disabled = false;
        transcript = "";
      });
  };

  listener.onerror = function (err) {
    logError(err);
    alert("Error occurred while capturing speech");
  };

  listener.onresult = function (event) {
    for (const alternatives of event.results) {
      const [bestAlternative] = Array.from(alternatives).toSorted(
        (altA, altB) => altB.confidence - altA.confidence
      );

      transcript += bestAlternative.transcript;
    }
  };

  return listener;
}

async function start() {
  const config = {
    isListening: false,
  };

  const listener = setUpSpeechRecognition();

  btnRecord.addEventListener("click", function () {
    toggleRecording(config, listener);
  });
}

ensureBrowserHasSpeechAPI();

function logError(...str) {
  for (const s of str) {
    console.error("error:", s);
  }
}

marked is an npm package that helps convert Markdown text to HTML and it's a required dependency in the project. Install marked in the project by running the following command in the project's terminal:

npm install marked

The ensureBrowserHasSpeechAPI function in src/main.js checks to see if the browser in use has the WebSpeechAPI feature. If it doesn't, it prevents the application from displaying the controls for the UI. That's why you'll need a Google Chrome browser with a version greater than or equal to 33 for this guide. Those versions have the WebSpeechAPI feature.

The toggleRecording function executes when the Record prompt button is clicked. On the first click, it requests microphone permission. It also enables/disables the activity of the SpeechRecognition instance.

The setUpSpeechRecognition function sets up the SpeechRecognition instance: listener, and its configuration. It also attaches functions to be run when the end, error and result events are triggered.

error is triggered when there is an error in capturing or processing audio
result is triggered when the recognition engine returns transcription results
end is triggered when the speech recognition service has disconnected from the application.

The transcript is displayed on the UI after passing it as an argument to the appendTranscriptToChatList function.

The promptAI function executes when the end event fires, accepting the speech transcript as an argument and sending it to the backend via a POST request using fetch. On success, the AI response is returned as Markdown and passed to appendAIResponseToChatList, which converts it to HTML and displays it on the UI.

Test the Application Locally

Start the backend application by running npm run start in the backend project's terminal and start the frontend application by running npm run dev in the frontend project's terminal. Visit http://localhost:5173 to view the UI of application. You should see a UI similar to the one in the image below:

Click the Record prompt button. A prompt will appear requesting microphone permission. Select "Allow while visiting the site" or "Allow this time" to grant access and begin recording. Click on the Stop recording button when you're done.

The UI will display the transcript of your speech and the application will send it to the backend as a prompt. After waiting for a short while, you'll see the response from the AI assistant displayed on the UI.

You have been able to use speech input to prompt an AI assistant, receive a response and display it. How do you make this application accessible to everyone? The next section guides you through deploying both applications.

Deploy the Backend Application with Google Cloud Run

In this section, you'll deploy the backend application with Google Cloud Run and get a URL which will be used as the apiUrl in the frontend application.

In order to host the backend application with Google Cloud Run, you need to have a:

Google Cloud developer account
Google Cloud project

Visit Google Cloud to create an account and create a project. You can name the project whatever you want but it's a good idea to give a descriptive name. Take note of the project's ID because you'll use it in the deployment process.

There are three ways to deploy applications on Google Cloud Run:

Deploy a revision from an existing container image
Deploy from a repository such as GitHub or GitLab
Create a function using the inline editor

You can see all three options if you visit the create Cloud Run service page.

In this guide, you'll use the option to deploy from an existing container image. Follow the steps below to deploy the backend server from a container image or follow the Cloud Run documentation at build and deploy Node.js service on Cloud Run:

Install the Google Cloud (gcloud) CLI on your computer by visiting the Install Google Cloud CLI page and following the instructions on the page for your operating system
Initialise the gcloud CLI to connect it to your developer account by visiting the Initializing the gcloud CLI page and following the instructions on the page
Set the project you want to deploy the backend server under by running the command below in your terminal:

# replace PROJECT_ID with your project ID

gcloud config set project PROJECT_ID

Visit your project's IAM Admin page to enable the following roles on the service account created for this project:
- roles/run.sourceDeveloper
- roles/iam.serviceAccountUser
- roles/logging.viewer

These roles are required to enable the Cloud Run Admin API and Cloud Build APIs. Take note of the service account email address.

Enable the Cloud Run Admin API and Cloud Build APIs by running the code snippet below in your terminal:

gcloud services enable run.googleapis.com cloudbuild.googleapis.com

Grant the Cloud Build service account access to your project by running the code snippet below in your terminal:

# replace PROJECT_ID with your project ID and 
# SERVICE_ACCOUNT_EMAIL_ADDRESS with the service account's email address

gcloud projects add-iam-policy-binding PROJECT_ID \
--member=serviceAccount:SERVICE_ACCOUNT_EMAIL_ADDRESS \
--role=roles/run.builder

Update index.js in the backend project to restrict API requests to clients specified in the ALLOWED_ORIGINS environment variable, and update the AI assistant configuration to use the API key loaded from environment variables.

// Use the API key from the environment variable
const GEMINI_API_KEY = process.env.GEMINI_API_KEY; 
const ai = new GoogleGenAI({ apiKey: GEMINI_API_KEY });

// Replace res.setHeader("Access-Control-Allow-Origin", "*"); with
res.setHeader("Access-Control-Allow-Origin", process.env.ALLOWED_ORIGINS);
res.setHeader("Access-Control-Allow-Methods", "POST,OPTIONS");
res.setHeader("Access-Control-Allow-Headers", "Content-Type");

This ensures that the application will receive POST requests from only frontend URLs specified in the ALLOWED_ORIGINS environment variable. This setup prevents the backend from being loaded with requests from frontend clients that you don't know, and also prevents the excess use of your tokens. It also keeps you from deploying the application with the AI API key hardcoded in it.

To test that the new changes work, run the backend application with the command below:

# replace YOUR_API_KEY with your Gemini API key

GEMINI_API_KEY=YOUR_API_KEY ALLOWED_ORIGINS="http://localhost:5173" npm run start

With the command in the code snippet above, the backend application will not respond to requests from frontend applications not hosted on http://localhost:5173. Try to send a prompt from the frontend application to test that it works.

To deploy the backend application to Cloud Run, run the command in the snippet below in the terminal of the backend project folder. The command sets the environment variables required for the application to run and also deploys it to Google Cloud Run.

# replace  with your Gemini API key

gcloud run deploy --source . \
--set-env-vars "ALLOWED_ORIGINS=http://localhost:5173" \
--set-env-vars "GEMINI_API_KEY="

Once deployment is complete, you'll receive the URL of your hosted backend. Copy it and replace the value of apiUrl in your frontend application with it. Run the frontend, record a prompt, and confirm that everything works as expected.

Deploy the Frontend Application with Firebase

In this section, you'll host the frontend application with Firebase. You need to have a Firebase account. Follow the steps below to host the frontend with Firebase:

Create and set up a Firebase project
Install the Firebase CLI by visiting the install Firebase CLI page and follow the instructions for your operating system
In the terminal of the frontend project, run firebase init hosting to initialise the hosting configuration for the project. Follow the prompts and use dist as the public directory when prompted
Run firebase deploy --only hosting to host the application with Firebase

Once deployment is complete, you will receive the URL of your hosted frontend application.

Connect the Deployed Applications

Remember that the first time you deployed your backend application, you set ALLOWED_ORIGINS to http://localhost:5173. The deployed backend application doesn't know about the URL of the deployed frontend application so it won't accept requests from it.

In the terminal of the backend application, deploy the backend application again using the command in the snippet below:

# replace  with your Firebase frontend URL and  
# with your Gemini API key

gcloud run deploy --source . \
--set-env-vars "ALLOWED_ORIGINS=" --set-env-vars "GEMINI_API_KEY="

Visit the deployed frontend application and test it. It should work without errors.

Conclusion

In this guide, you built a frontend application that captures and transcribes speech, a Node.js backend application that prompts AI, and you connected both applications together to build a simplified version of the Use Voice feature in AI chat applications.

Can you add a feature to the application that will make it read out the response from the backend when it receives it? You can use the SpeechSynthesis API to build it.

Feel free to connect with me on LinkedIn if you have any questions. Thank you for reading this far and don’t hesitate to share this article if you found it insightful. Cheers!

How to Create REST API Documentation in Node.js Using Scalar

Orim Dominic Adah — Wed, 25 Feb 2026 16:03:26 +0000

A REST API documentation is a guide that explains how clients can make use of the REST APIs in an application. It details the available endpoints, how to send requests and what responses to expect. It may also contain explanations of concepts that are specific to the scope of the application.

Without API documentation, application development is considered incomplete because developers cannot build software to interact with it, rendering the application effectively useless.

In this article, you will learn how to create beautiful REST API documentation that also allows you to test the APIs for free using an OpenAPI specification and Scalar in Node.js projects. You will use asteasolutions/zod-to-openapi to generate OpenAPI specification and use Scalar to create a web page from the specification.

To get the most out of this article, you should have experience developing REST APIs with Express or NestJS. You should also have experience with documenting REST APIs and using zod.

REST API Documentation Tools for Node.js
- Swagger
- Postman
- ReDoc
zod-to-openapi and Scalar for REST API Documentation
- How zod-to-openapi Works with Scalar
Benefits of Using zod-to-openapi and Scalar to Create REST API Documentation
How to Create the API Documentation
How to Use Scalar with NestJS
How to Resolve Content Security Policy (CSP) Errors When Used with Helmet
Absence of AsyncAPI Documentation Feature
Conclusion

REST API Documentation Tools for Node.js

A variety of tools already exist for documenting REST APIs and they have different strengths and weaknesses depending on their use case. While some of them are completely free to use, others operate a freemium model, and while some have an interface for testing APIs, others have a presentation-only user interface (UI).

Some of the most popular tools for documenting REST APIs in Node.js projects are listed below:

Swagger
Postman
Redoc

Swagger

In order to document REST APIs in Express with Swagger, you need swagger-jsdoc and swagger-express-ui. swagger-jsdoc collates and parses JSDoc-annotated documentation comments in the codebase and generates an OpenAPI specification document. swagger-ui-express uses the generated document to created a web page that renders the API documentation and test the APIs.

One of Swagger’s strengths lies in its support for the OpenAPI specification which is an industry standard. Swagger is free to use, has a vibrant open source community and strong support for many programming languages and frameworks. It supports only REST APIs.

Its major drawback is the poor developer experience in manually writing JSDoc comments or YAML for the documentation. The process can be clumsy and developers can forget to include some annotations. Another drawback is that the JSDoc comments can interfere with reading functional code. Lastly, some developers have complained about its boring UI.

Postman

Postman is a cloud-based desktop API client application that allows developers and technical writers to write, test, collaborate on and publish API documentation. Unlike Swagger, it does not require deep programming experience to use most of its features. It is also not limited to REST API documentation — it can document APIs for GraphQL, websockets and gRPC.

Postman provides a UI to fill in details of an API documentation. The documentation process is manual and sometimes, its content can get out of sync with that of deployed applications. It is not free to use for teams and collaboration and hides the real behaviour of browser interaction with the APIs like CORS and streaming.

ReDoc

ReDoc is an open-source tool used to generate API documentation from an OpenAPI (Swagger) specification. It supports GraphQL, AsyncAPI and the OpenAPI specification and it renders a more beautiful documentation than Swagger. redoc-express is used to document Express REST APIs with Redoc.

Redoc’s major drawback is that its free community edition is presentation-only. It does not support testing the APIs. Similar to Swagger, a drawback it has is manually updating the application's OpenAPI document via a YAML specification file or JSDoc comments.

zod-to-openapi and Scalar for REST API Documentation

asteasolutions/zod-to-openapi is a TypeScript library that generates OpenAPI specification from zod schemas. It provides typed methods which serve as guardrails for documenting API components instead of using code comments so that:

The library methods serve as guardrails for what to document and how to document it
The documentation is consistent across the codebase
The documentation doesn't negatively affect code readability

A sample snippet used to document a POST request for creating a user with zod-to-openapi is shown below:

// CreateUser and User are zod schema

registry.registerPath({
  method: "post",
  path: "/api/users",
  summary: "Create user",
  tags: ["users"],
  request: {
    body: {
      content: {
        "application/json": {
          schema: schema.CreateUser, 
        },
      },
      description: "Create user payload",
      required: true,
    },
  },
  responses: {
    201: {
      description: "User created",
      content: {
        "application/json": {
          schema: z.object({
            message: z.string(),
            data: schema.User,
          }),
        },
      },
    },
  },
});

Scalar is a tool that generates beautiful, organized and searchable API documentation from OpenAPI documents. The documentation generated also supports testing the APIs and this makes Scalar effectively function as an API documentation generator and a lightweight API client. The image below shows a sample documentation generated by Scalar:

How zod-to-openapi Works with Scalar

zod-to-openapi provides the functionality to generate an OpenAPI specification from code. Scalar uses the document generated to create a documentation web page that presents the information in the document in an organized and beautiful way that also allows for testing the APIs.

Benefits of Using zod-to-openapi and Scalar to Create REST API Documentation

When you combine zod-to-openapi and Scalar to create REST API documentation for your Express applications, you get a myriad of benefits. Some of the benefits are explained below:

OpenAPI Specification Support

The OpenAPI specification is a format for describing REST APIs. It takes takes into consideration the important components of an API necessary for clients to use it effectively. These components include:

Request paths, methods, headers, path parameters and query parameters,
Schemas of request and response payloads,
Authentication requirements,
Descriptions for information not accommodated by other components

zod-to-openapi provides methods for all of these to be included in the documentation and it generates an OpenAPI specification-compliant document that Scalar uses to generate the documentation web page.

Open Source and Free to Use

zod-to-openapi is open source and free to use. It has no plans to be unsupported or sunsetted soon because like Ruby on Rails and Laravel, the creators of the project use it in their day-to-day work.

Scalar is open source too. It has paid plans but the features in the paid plans are only really useful for enterprise applications. The free version supports the necessary features needed to create useful REST API documentation.

Better Documentation Experience

In terms of user experience, the union of zod-to-openapi and Scalar provides the following benefits when writing documentation with both tools:

Guardrails with zod-to-openapi Methods

The methods provided by zod-to-openapi serve as guardrails to ensure that developers don't omit or forget the documentation of important components of APIs. The methods also ensure that these components are documented in an OpenAPI specification-compliant manner through the typed nature of the methods' parameters.

Avoid the Clumsiness of Comments and YAML Files

With zod-to-openapi, you don't document the APIs using comments or a YAML file. You document APIs using methods from zod-to-openapi. This removes the cluttering of code with comments and the clumsiness around manually updating large YAML files of OpenAPI specification.

Accuracy and Auto-generation of Documentation

When you use zod-to-openapi and Scalar, your API documentation is generated automatically when the application runs. zod-to-openapi does the collation and compilation of the documented APIs, and Scalar creates a web page for it that can be hosted on an API route of the same application. You don't need to manually run CLI commands to generate the documentation.

Another benefit of accuracy and auto-generation is that the job of API documentation is not split between technical writer and backend developer. The documentation is in the code and this makes development faster and more seamless in terms of API documentation.

Developer-friendly UI

While Swagger’s UI is functional, some developers consider its presentation somewhat minimal, particularly when displaying detailed endpoint descriptions. ReDoc improves on visual design but does not offer API testing features. Scalar, on the other hand, delivers a more refined and intuitive interface with greater customization options than ReDoc.

Beyond its design advantages, Scalar provides auto-generated code samples in multiple programming languages. This enables developers to integrate APIs more efficiently using examples tailored to their specific tech stack.

Scalar's UI provides a search feature that allows developers to quickly locate specific sections of the API documentation. It also includes an AI chat interface that enables users to understand how different API endpoints can help address their specific use cases. This approach is more efficient than manually reviewing the entire documentation.

Lastly, you can test the API endpoints from the UI. When you make authenticated API requests, the UI caches authentication tokens so that you don't have to type or paste them for subsequent requests.

Markdown Support

zod-to-openapi and Scalar have Markdown support. With Markdown, you can include conceptual documentation and more information about API endpoints that are not supported by the default documentation components like headers and the request body.

You can embed images, include tables and format text in the documentation. You can use Markdown to include notes that explain concepts related to the API.

How to Create the API Documentation

In this section, you will create an Express CRUD API project that uses zod-to-openapi and Scalar to document its APIs. To practice along, clone the Express starter project from GitHub at orimdominic/freeCodeCamp-zod-to-openapi-scalar.

Set up the Project

After cloning the project:

install its dependencies using your preferred Node.js package manager
start the server using the serve script

# Install dependencies
npm install

# Start the application
npm run serve

You should see the following output on the terminal if the application runs successfully:

> freecodecamp-zod-to-openapi-scalar@1.0.0 serve
> node --experimental-strip-types --watch src/index.ts

Listening on :3000

The project has two modules - Users and Pets.

The router configuration for each module is defined in the router.ts file, while the route controllers are located in the controllers.ts file within each module's folder under src/modules. The controllers do not contain business logic, they simply respond with JSON values generated by the Faker library.

How to Set Up zod-to-openapi

Install asteasolutions/zod-to-openapi using your preferred Node.js package manager. If you use npm, run the code snippet below in your terminal:

npm install @asteasolutions/zod-to-openapi

After the installation, create a folder called lib (library) in the src folder. In the lib folder, create a file called openapi.ts. The file will house the code that sets up zod-to-openapi for collating the API documentation and generating the OpenAPI specification.

Copy and paste the code snippet below into src/lib/openapi.ts:

import z from "zod";
import {
  extendZodWithOpenApi,
  OpenApiGeneratorV31,
  OpenAPIRegistry,
} from "@asteasolutions/zod-to-openapi";

extendZodWithOpenApi(z);

export const registry = new OpenAPIRegistry();

export const bearerAuth = registry.registerComponent("securitySchemes", "bearerAuth", {
  type: "http",
  scheme: "bearer",
  bearerFormat: "JWT",
});

export function generateOpenAPIDocument() {
  const generator = new OpenApiGeneratorV3(registry.definitions);

  return generator.generateDocument({
    openapi: "3.1.0",
    info: {
      title: "Users API",
      version: "1.0.0",
      description: `Backend API documentation for users application.`,
    },
    tags: [
      {
        name: "users",
        description: "For operations carried out by admin users",
      },
    ],
    servers: [
      {
        url: "http://localhost:3000",
        description: "Local server",
      },
    ],
  });
}

zod-to-openapi v8 requires zod v4. If you use zod v3, you should use v7.3.4 of zod-to-openapi.

extendZodWithOpenApi is a method provided by zod-to-openapi that enhances Zod schemas by adding an openapi method. The openapi method allows you to attach additional documentation to request payloads, responses, parameters, and their properties, which are then displayed in the API documentation rendered by Scalar.

It is important to call extendZodWithOpenApi before loading any files that use the openapi method, otherwise accessing openapi on Zod objects will result in errors.

An alternative is to use the meta method on zod v4 schemas for the additional documentation. For example, schemaOne and schemaTwo in the code snippet below are the same:

const schemaOne = z
  .string()
  .openapi({ description: 'Name of the user', example: 'Test' });

const schemaTwo = z
  .string()
  .meta({description: 'Name of the user', example: 'Test' });

The meta method supports all metadata information that you'd normally pass to openapi and will produce exactly the same results.

The OpenAPIRegistry is a utility that is used to collate API documentation which would later be passed to an OpenAPI specification generator. registry is created from OpenAPIRegistry, exported, and used to document API endpoints and components in modules where it is imported.

export const registry = new OpenAPIRegistry();

bearerAuth is a component created by the registry to represent JWT authentication. When bearerAuth is included in the documentation of an endpoint, the UI renders an input for submitting an authentication token for authenticated requests as shown in the image below.

In the registerComponent method, "securitySchemes" registers a security scheme component. "bearerAuth" , the first argument of registerComponent, is the name given to the component and it can be changed to a name that you prefer. It appears in the top right of the authentication token input, shown in the image above. The third input to registerComponent is an object that defines the component.

When generateOpenAPIDocument function is executed, it collates all the registry API definitions in the project, generates the OpenAPI specification through generator.generateDocument, and returns the specification as JSON.

The tags property in generator.generateDocument organizes API endpoints into sections on the documentation UI. For example, all API endpoints with the Users tag in their registry definition will be placed under the Users section of the UI. description can be written in Markdown within template literals.

The servers property is a collection of the servers connected to the application. If you have multiple servers, you have the option of selecting what server to use for the base URL in the documentation UI for making API requests from it.

With this setup in place, when endpoints are documented with the registry, generateOpenAPIDocument will have an OpenAPI specification to return.

How to Generate the Documentation UI with Scalar

In this section, you will set up Scalar and connect it to the return value of generateOpenAPIDocument. You will also connect Scalar with an Express route, allowing the application to serve the documentation UI at that route.

Scalar has an Express API reference library that makes it easier for you to connect it with the OpenAPI specification and Express. Install scalar/express-api-reference using your preferred Node.js package manager. If you use npm, use the snippet below:

npm install @scalar/express-api-reference

Copy and paste the code snippet below into src/app.js:

import express from "express";
import router from "./router.ts";
import { generateOpenAPIDocument } from "./lib/openapi.ts";
import { apiReference } from "@scalar/express-api-reference";

const app = express();
app.use(express.json(), express.urlencoded({ extended: true }));

app.get("/", function (req, res) {
  return res.send("OK");
});

app.use("/api", router);

const apiDocJsonContent = generateOpenAPIDocument();

app.use(
  "/docs", // documentation route
  apiReference({
    content: apiDocJsonContent,
    title: "Users API",
    pageTitle: "Users API",
  }),
);

export default app;

In the code snippet above, generateOpenAPIDocument is imported from src/lib/openapi.ts, and apiReference is imported from @scalar/express-api-reference. When executed, generateOpenAPIDocument returns the OpenAPI specification, which is stored in apiDocJsonContent for caching to improve perfoemance.

A GET /docs route is then created, with the Scalar apiReference function acting as the controller. It accepts apiDocJsonContent and returns a web page whenever the GET /docs route is accessed.

With this setup in place, run the application using npm run serve and visit the documentation page at http://localhost:3000/docs in your browser. You should see a user interface similar to the image below:

To view the codebase at this point, run git checkout set-up-openapi-scalar .

Document the Endpoints

You have set up zod-to-openapi and connected it with Scalar. You have also hooked it up with a route in the backend application. In this section, you will write code to document the endpoints in the application for generating the OpenAPI specification and rendering it on the documentation UI.

To document the route for creating users ( POST /api/users ), in src/modules/users/router.ts , import registry, the schemas and zod using the snippet below:

import z from "zod";
import { registry } from "../../lib/openapi.ts";
import { 
    UserSchema, 
    UserListItemSchema,
    UpdateUserSchema, 
    CreateUserSchema, 
} from "./types.ts";

Copy and paste the code below above the create user route to document the create user endpoint:

registry.registerPath({
  method: "post",
  path: "/api/users",
  summary: "Create user",
  tags: ["users"],
  request: {
    body: {
      content: {
        "application/json": {
          schema: CreateUserSchema,
        },
      },
      description: "Create user payload",
      required: true,
    },
  },
  responses: {
    201: {
      description: "User created",
      content: {
        "application/json": {
          schema: z.object({
            message: z.string().openapi({ example: "User created" }),
            data: UserSchema,
          }),
        },
      },
    },
  },
});

Visit the documentation page and you will find see a web page similar to the image below:

The UI result of some of the input fields of registry.registerPath have been labelled in the image above. The description in the API endpoint is italicised because its value is Markdown in a template string.

By registering the route path for creating users with registry.registerPath and filling its values, you added the documentation of the route to the registry definitions and that makes it included in the OpenAPI specification.

To test the endpoint from the documentation UI:

click the Test Request button
fill in the payload in the dialog that appears and
click the Send button

To document the get user by id route (GET /api/users/:id ), import bearerAuth from src/lib/openapi.ts, copy the code snippet below and paste it above the get user by id route definition.

registry.registerPath({
  method: "get",
  path: "/api/users/{userId}",
  summary: "Get user details by id",
  tags: ["Users"],
  security: [{ [bearerAuth.name]: [] }],
  request: {
    params: z.object({ userId: z.int() }),
  },
  responses: {
    200: {
      description: "User retrieved",
      content: { "application/json": { schema: UserSchema } },
    },
  },
});

When the request.params field is defined using a Zod object, it generates an input UI on the documentation web page that enables users to provide values for path parameters such as userId, highlighted in the image below:

The complete code for the documentation of all endpoints in this section can be accessed when you check out the complete-project branch by running git checkout complete-project in your terminal. It contains documentation for the endpoint for uploading user photo, which demonstrates how to document endpoints that accept file uploads.

How to Use Scalar with NestJS

Scalar has a library that integrates with NestJS. You can use supply the Swagger document created by swagger/nestjs to the Scalar NestJS integration library to generate the Scalar documentation UI.

In root folder of your NestJS project, install the Scalar NestJS integration library:

npm install @scalar/nestjs-api-reference

Update the main.ts file of your NestJS project with the code snippet below:

import { NestFactory } from '@nestjs/core';
import { apiReference } from '@scalar/nestjs-api-reference';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const options = new DocumentBuilder()
    .setTitle('Cats example')
    .setDescription('The cats API description')
    .setVersion('1.0')
    .addTag('cats')
    .addBearerAuth()
    .build();

  const openApiSpecification = SwaggerModule.createDocument(app, options);
  
  // integrate the documentation with NestJS
  app.use(
    '/api/docs', // documentation route
    apiReference({
      content: openApiSpecification,
    }),
  )

  await app.listen(3000);
  console.log(`Application is running on: ${await app.getUrl()}`);
}

bootstrap();

With this setup in place, you can visit the /api/docs route in your browser to view the Scalar documentation for your NestJS application.

How to Resolve Content Security Policy (CSP) Errors When Used with Helmet

If you use Helmet in your Express or NestJS project, you will encounter CSP errors when you try to render the Scalar documentation UI. To resolve the errors, update the Helmet CSP configuration in your code to have the value of the object in the code snippet below:

{
    directives: {
      defaultSrc: [`'self'`],
      styleSrc: [`'self'`, `'unsafe-inline'`],
      imgSrc: [`'self'`, 'data:', 'validator.swagger.io'],
      scriptSrc: ['self', 'https:', 'unsafe-inline'],
    },
  }

Absence of AsyncAPI Documentation Feature

At the time of writing, Scalar does not fully support rendering AsyncAPI specifications for event-driven architecture APIs, although it is currently under development. You can track the progress of its development through the GitHub issue linked in the documentation to stay informed about its release.

Conclusion

You have learned about zod-to-openapi and how it makes it easier for you to generate an OpenAPI specification for your REST APIs than writing comments or large YAML files. You also learned how to use the specification document generated to render a beautiful API documentation UI which also functions as a lightweight API client. Endeavour to implement it in your projects that need a documentation uplift.

Feel free to connect with me on LinkedIn for questions or clarifications. Thank you for reading this far and I hope this helps you achieve what you intended to achieve. Don’t hesitate to share this article if you feel that it would help someone else out there. Cheers!

How to Build an In-Memory Rate Limiter in Next.js

Orim Dominic Adah — Fri, 09 Jan 2026 19:24:26 +0000

An API rate limiter is a server-side component of a web service that limits the number of API requests a client can make to an endpoint within a period of time. For example, X (formerly known as Twitter) limits the number of tweets that a specific user can make to three hundred every three hours.

Rate limiters enforce the responsible use of APIs by blocking requests that exceed the set usage limits.

By following along with this article, you will:

Learn how rate limiters work
Build an in-memory rate limiter for a Next.js pa router project
Use Artillery to load test the rate limiter for accuracy and resilience

Here’s What We’ll Cover:

Benefits of Rate Limiters
How Rate Limiters Work
Rate Limiting Algorithms
How to Build an In-Memory Rate Limiter
- How The In-Memory Rate Limiter Works
- The Request Handler
The Front End
How to Load Test the Rate Limiter for Resilience with Artillery
Conclusion

To get the most out of this article, you should have experience in building APIs with Next.js pages router, Express, or any other Node.js backend framework that uses middlewares.

Benefits of Rate Limiters

Rate limiters control how many requests are allowed within a given time window. They have several benefits you should know about if you’re considering using them.

First, they help prevent the abuse of web servers. Rate limiters guard web servers from overuse that needlessly increases their load. They block excessive requests from Denial of Service (DoS) attacks from bots so that the web service doesn’t crash from unnecessary overload and can continue to be available to legitimate users.

They also help manage the cost of using external APIs. Some API endpoints make requests to external APIs to complete their operations – for example, API endpoints that send emails through an email service provider. When an endpoint relies on paid external APIs and user access of the endpoint is not restricted, excessive usage can lead to increased and expensive costs for the web service. Rate limiters block the excessive usage of endpoints like these, helping to keep costs to a reasonable minimum.

How Rate Limiters Work

Rate limiters work using a three-step mechanism. The process includes tracking requests from specific clients, monitoring their usage, and blocking extra requests once the threshold has been exceeded.

In more detail, rate limiters:

Track requests: Rate limiters take note of API clients that make requests and attributes that are specific to the clients (for example, an IP address or a userId). These specific attributes are references or keys that are used to identify clients.
Monitor usage: Depending on the rate limiting mechanism, rate limiters increase or decrease the metric that is used to determine the threshold of use. For example, within a three-hour time period, Twitter can track and increase the number of times a user makes an API request to the create tweet endpoint.
Ensure threshold compliance: Rate limiters check the threshold of use for every request made. If it has been exceeded, it blocks the request from accessing the functionality of the API endpoint and responds with a status code of 429.

Rate Limiting Algorithms

You can implement rate limiting using different algorithms based on the requirements of the rate limiter. Each rate limiting algorithm has its merits and demerits. Below are some popular rate limiting algorithms you can play around with.

Fixed Window Algorithm

In the fixed window rate limiting algorithm, the number of requests made within a fixed time period is tracked and every request increases the request count tracked. If the number requests within the time frame is exceeded, any extra request that comes in within the time frame is blocked. At the end of the time period, the request count is reset and increases for every request made.

Its mechanism is easy to understand and it’s memory-efficient. Its challenge is that spikes in traffic close to the start or the end of a time window can allow more requests than permitted.

Sliding Window Algorithm

The sliding window algorithm fixes the issue with the fixed window algorithm where spikes in traffic close to the start or end of a time window can allow more requests than permitted.

It works as follows:

It keeps a track of the timestamps of requests made in a cache.
When there’s a new request, it removes all timestamps that are older than the start of the current time window and it appends the new request’s timestamp to the cache.
If the count of the requests in the cache is higher than the threshold, the request is blocked. Otherwise, it’s allowed.

Although this algorithm is more accurate than the fixed window algorithm, it consumes more memory because of the storage of timestamps.

Token Bucket Algorithm

In the token bucket algorithm, a bucket that contains a predefined number of tokens is assigned to a user. Tokens are added to the bucket at a predefined rate, for example 2 tokens may be added every second.

Once the bucket is full, no more tokens are added. Each request consumes one or more tokens, and if the tokens are exhausted, requests are blocked until the bucket has tokens again.

The Token Bucket algorithm has the benefits of being memory efficient, easy to implement, and accurate enough to block extra requests even during a burst in traffic.

In this tutorial, we’ll use the fixed window algorithm to build a rate limiter. We’ll also battle-test it for resilience and accuracy using Artillery.

How to Build an In-Memory Rate Limiter

If you’re a backend developer, you may have noticed that users sometimes abuse the reset password API endpoint in your Next.js application. This is a cause for concern because the API endpoint makes a request to your email service provider to send an email and you get charged for it.

Because of this, you may want to limit the requests that users make to this endpoint so that you can prevent the abuse of the API and save costs. And that’s where a rate limiter comes in.

You can get the code for this tutorial hereis tutorial here. You can clone it, install the dependencies with npm install, and run it following the instructions in the README file. You’ll need it to follow along with the rest of this article.

I built the project using Next.js and it uses the pages router. I’ve also built the rate limiter and you can find it here. You can see how to use it in the reset password API endpoint here.

It has a user interface that you can use to test the rate limiter – but let’s dive into the code first.

How The In-Memory Rate Limiter Works

To help you better understand the rate limiter, I've created this diagram. We'll walk through what's happening after:

The src/lib/server/rate-limiter.ts file exports a function called applyRateLimiter which accepts three parameters:

the request object
the response object
getOptsFn

getOptsFn is a function that accepts the request object and, when executed, returns properties specific to the request for tracking, monitoring, and blocking by the rate limiter. getOptsFn is a function and not a static object so that the specific properties of a request can be dynamically created by the request handler for each request.

src/lib/server/rate-limiter.ts also has an in-memory map called cache. cache stores the key (or unique identifier) of a request and maps it to its usage. An interval runs every minute to remove keys with expiredAt values that have passed from the cache. This helps to manage the amount of memory used by the cache.

type GetOptionsFn = (req: NextApiRequest) => {
  key: string;
  maxTries: number;
  expiresAt: Date;
};

const cache = new Map();

// clear stale keys from cache every minute
setInterval(() => {
  const currentDate = new Date();
  for (const [key, usage] of cache) {
    if (!usage) continue;

    if (currentDate > usage.expiresAt) {
      cache.delete(key);
    }
  }
}, 60000);

When the rate limiter is executed, it uses the getOptsFn to generate the following from the request:

key: The unique identifier for the request that can be used to track its usage
maxTries: The maximum number of times a request can be made within the specified time window
expiresAt: The expiry time of a time window

based on its content where it was created.

  const opts = getOptsFn(req);
  const usage = cache.get(opts.key);

  if (!usage) {
    cache.set(opts.key, {
      tries: 1,
      maxTries: opts.maxTries,
      expiresAt: opts.expiresAt,
    });

    return;
  }

The rate limiter then checks if the key of the request exists in the cache. If it doesn’t, it sets it in the cache, mapping it to the following values:

tries : The number of times that the request has been made without being blocked
maxTries: The maximum number of times that the request should be allowed within the time window without blocking
expiresAt: The expiry time of the time window

It also allows the request to continue by exiting the rate limiter through the return statement. The values set in cache will be used to determine if and when consecutive requests with the same key should be blocked or not.

If the request’s key exists in cache, the rate limiter checks if the number of unblocked tries (usage.tries) from cache is less than the number of allowed usage tries (usage.maxTries). If it evaluates to true, it means that the request has not exceeded its maximum tries. It also checks if the expiry time of the time window stored in cache for the request has elapsed.

The request is not blocked if one of the following conditions evaluates to true:

the request has not exceeded its maximum tries AND its time window has not elapsed
the current time window of the request usage in cache (usage.expiresAt) has elapsed

  const currentDate = new Date();
  const retryAfter = usage.expiresAt.getTime() - currentDate.getTime();
  const timeWindowHasElapsed = retryAfter < 0
  const canProceed = usage.tries < opts.maxTries && !timeWindowHasElapsed;

  if (canProceed) {
    cache.set(opts.key, {
      ...usage,
      tries: usage.tries + 1,
    });

    return;
  }

  if (timeWindowHasElapsed) { // if usage.expiresAt has elapsed
    cache.set(opts.key, {
      tries: 1,
      maxTries: opts.maxTries,
      expiresAt: opts.expiresAt,
    });

    return;
  }

If canProceed is truthy, the rate limiter increases the number of tries (usage.tries) that the request has in the cache and then allows the request to proceed by exiting the rate limiter using the return statement. If timeWindowHasElapsed is truthy, the rate limiter resets the usage of the request in the cache using values gotten from getOptsFn and then allows the request to proceed. If both conditions are falsy, the request is blocked with a 429 response status code.

  res.setHeader("Retry-After", retryAfter/1000);
  return res.status(429).json({
    error: { message: "Too many requests" },
  });

According to REST specifications, a 429 HTTP response may include a Retry-After header to let clients know how long to wait before making a new request. The value of the Retry-After header had been calculated beforehand and is set on the response object using res.setHeader.

The Request Handler

You can find the reset password request handler in src/pages/api/reset-password-init.ts. First, it performs validation checks on the request method and body to ensure that it is fit for its operations. The validation ensures that the request is a POST request and that the request body includes an email property. It ends the request with the appropriate response code if validation fails.

  if (req.method !== "POST") {
    return res.status(405).json({
      error: { message: "Not allowed" },
    });
  }

  if (!req.body.email || typeof req.body.email != "string") {
    return res.status(400).json({
      error: { message: "'email' is required" },
    });
  }

generateOptions is the function that is eventually passed as getOptsFn to the rate limiter. The generateOptions function generates the specific properties of the request for the rate limiter. In the case of this endpoint, the properties are:

key: A string in the format [method].[endpoint].[email]. For an email value of “Hello@me.com”, the key will be post.reset-password.hello@me.com which will be constant for every request for that email to this endpoint. This key value format makes it unique and specific to this request.
expiresAt: The time when the time window expires. If the request is in cache, this value is ignored by the rate limiter and it uses the value in the cache instead
maxTries: The maximum number of tries that should be allowed within the time window. If the request is in the rate limiter cache already, this value is ignored in preference of the value in cache.

  const generateOptions = function (req: NextApiRequest) {
    const now = new Date();
    const inFiveSeconds = new Date(now.getTime() + 5000);

    return {
      expiresAt: inFiveSeconds,
      key: `post.reset-password.${req.body.email.toLowerCase()}`,
      maxTries: 1,
    };
  };

For the reset password handler, requests are rate limited to one every five seconds. You can tweak the expiresAt and maxTries values to test how it works. applyRateLimiter is executed with its arguments and if it does not block the request, the handler can go on to send the mail and respond to the client.

The Front End

You can visit the user interface to test the rate limiter manually. Visit the URL shown (http://localhost:3000 by default) after you ran npm run dev. You should see the user interface shown below to test the rate limiter.

How to Load Test the Rate Limiter for Resilience with Artillery

Artillery is a tool for testing and reporting how well web applications can perform under heavy load. In this section, you will use Artillery to test how efficient and accurate the rate limiter that you built is.

To use Artillery, install it globally via the npm install -g artillery@latest command so that the artillery command can be available for use via the CLI.

The Load Test Configuration

In the loadtest folder located at the root of the project, you will find the setup.yaml file. It contains the instructions for Artillery to use to carry out the load test. The instructions tell Artillery to create virtual users that will make API requests to the application with the base URL identified by target in three phases:

Warm up: Make API requests for a duration of ten seconds, starting from one request per second and increase it to five requests per second.
Ramp up: After warm up, make API requests for a duration of thirty seconds, starting from five requests per second and increase it to ten requests per second.
Spike phase: After ramp up, make API requests for a duration of twenty seconds, starting from ten requests per second and increase it to thirty requests per second.

This brings the total time of the load test to sixty seconds.

config:
  target: http://localhost:3000/api

  phases:
    - duration: 10
      arrivalRate: 1
      rampTo: 5
      name: Warm up

    - duration: 30
      arrivalRate: 5
      rampTo: 10
      name: Ramp up

    - duration: 20
      arrivalRate: 10
      rampTo: 30
      name: Spike phase

The plugins section contains instructions for extensions you can use to analyse the results from Artillery and get reports. For example, the ensure plugin contains setups that will report “OK” if at least 99% of the request responses have a latency of 100ms or less.

  plugins:
    ensure:
      thresholds:
        - http.response_time.p99: 100
        - http.response_time.p95: 75

The metrics-by-endpoint plugin (not used in this project) is another Artillery plugin that is used to display response time metrics for each URL in the test.

A scenario is a sequence of steps that describes a virtual user session in the app. Each virtual user created in phases will make an API request to the end endpoint in flow and the requests in the loop will happen or loop only once per virtual user (because the flow count has a value of 1).

scenarios:
  - flow:
      - loop:
          - post:
              url: "/reset-password-init"
              headers:
                Content-Type: "application/json"
              json:
                email: "j.doe@email.com"

        count: 1

Run the Load Test

Make sure that the application is running and run the load test with the command artillery run loadtest/setup.yaml --output loadtest/results.json from the root folder of the project. This will run the load test on the rate-limited endpoint and save the output of the results in loadtest/results.json.

Review the Results

Regardless of the of the number of requests made, the setup of our rate limiter allows only one request every five seconds. This means that the number of requests that should be allowed within a space of sixty seconds is twelve.

If you take a look at loadtest/results.json, you will see that only twelve requests had a status code of 200. If you increase the values of arrivalRate or rampTo in any or all of the phases to increase the number of requests made to the endpoint and you run the load test again, only twelve requests will still have a status code of 200. This means that our rate limiter is remaining effective and accurate even under high loads.

For latency, you should consider the report of the ensure plugin which is logged to the terminal at the end of the test. A result such as:

Checks:
ok: http.response_time.p95 < 75
ok: http.response_time.p99 < 100

means that 95% of all requests made had a latency of less than 75 milliseconds and 99% of all requests made had a latency of less than 100 milliseconds. These are good results.

Conclusion

In this article, you have learned about rate limiters, rate limiting algorithms, and how to build and use an in-memory rate limiter in Next.js.

You also got a brief introduction to load testing with Artillery. Be sure to apply what you have learned in one of your Next.js projects when you need it.

How Does the Morgan Express Middleware Library Work? Explained with Code Examples

Orim Dominic Adah — Mon, 29 Sep 2025 18:14:54 +0000

Morgan is an Express middleware library that examines HTTP requests and logs details of the request to an output. It is one of the most popular Express middleware libraries with over 8,000 GitHub stars and more than 9,000 npm libraries dependent on it. GitHub reports that Morgan is used by at least 3.6 million repositories.

Prerequisites

This guide explains the Morgan library’s code to help you understand how it works under the hood. This is helpful if you have experience with Express and you're interested in understanding the inner workings that produce Morgan log lines. An understanding of closures in JavaScript is helpful for this guide but not necessary.

What is an Express Middleware?
A Brief Overview of How Morgan Works
What is a Morgan Token?
What Happens When Morgan is Initialised?
What Happens When Morgan Captures a Request?
Next Steps

What is an Express Middleware?

According to Express documentation, a middleware is a function that has access to the request and response objects and the next function of an Express request cycle. They are generally used to intercept requests to execute side-effects before or after the request is handled by its route handler.

A middleware can be used to:

Make changes to the request and the response objects: It can make changes to the request and response objects by attaching properties like headers and cookies to them.
Terminate the request-response cycle: It can terminate a request and send a response to the client before or after the request is handled by its route handler.
Execute the next middleware in the stack: It can trigger the execution of the middleware after it via the next function argument.

A function called next is usually the third argument of a middleware and it is used to pass the request to the next middleware. If the next function is not executed in a middleware and the request is not explicitly terminated by sending a response to the client, the request will be left hanging.

The interface of a middleware is shown in the code snippet below:

function middleware(request, response, next) {
    // operations to be performed when this middleware is executed
    next() // execute the next middleware
}

A middleware can intercept and handle cases where preceding middleware or route handlers throw unhandled errors. These middlewares are usually called error handler middlewares and accept four arguments as shown below:

function errorHandlerMiddleware(error, request, response, next) {}

The error argument represents the unhandled error.

Some middlewares like Morgan and cors are higher-order functions. They accept configuration arguments when initialised and return a middleware function, executed by Express when hit by a request.

function initialise(...configArgs) {
    // make use of configArgs here
    return function middleware(request, response, next) {
        // can also make use of configArgs here
        // operations to perform when this middleware is hit by a request
        next() // execute the next middleware
    }
}

A Brief Overview of How Morgan Works

import morgan from "morgan"
// morgan(format, [options])
morgan("tiny") // initialise morgan and return a middleware
// Sample output: GET /tiny 200 2 - 0.188 ms

Morgan is initialised by executing it with a required format argument and an optional options argument. The format argument may be:

A predefined Morgan format name
A format string containing predefined tokens (a token set)
A custom format function that returns a log output in the form of a string

The options argument is optional. It is an object with three properties:

immediate (boolean): If true, the log output will be created on receiving requests and not when a response is sent. It defaults to false.
skip (function): The function accepts the request and response objects as arguments and returns a boolean value based on the logic in it. If the value returned is true, the log line for a request is not logged. skip defaults to false.
stream (WritableStream): Output stream for writing log lines. It defaults to process.stdout but it could be a file.

When Morgan is initialised, it stores its initialisation arguments in closure variables and returns a middleware function. The function is executed when a request hits it and it outputs a log line for the request. The format and where the log line is output to are determined by the initialisation arguments.

What is a Morgan Token?

A Morgan token is a string prefixed by a colon, corresponding to property of the request or response objects or a user-generated value. For example, the request method’s token is ':method' and the response status code’s token is ':status'. A token can also accept an argument to customise its behaviour. For instance, in ':date[format]', format can be replaced with clf, iso or web to set the format of the date that would be in the log line. An understanding of Morgan tokens is crucial to understanding how Morgan works.

You can create new tokens using the morgan.token function. The code snippet below creates a new token called ':type' which corresponds to the response Content-Type header:

morgan.token('type', function (req, res) {
    return res.headers['content-type']
})

Morgan has predefined named format (tiny, dev, short, combined, common) strings containing a set of tokens and each named format has its specific token set and configuration. The token set for tiny is ':method :url :status :res[content-length] - :response-time ms'. Morgan can accept these named formats as the value of the format argument.

Aside from accepting named formats, Morgan can also accept a token set (for example ':method :url :status :res[content-length] - :response-time ms') as the format argument. A third argument type that Morgan accepts as the format argument is a format function. A format function accepts three arguments and returns a string that forms the log line for each request. For example, the format function described below:

morgan(function (tokens, req, res) {
    return `method: ${tokens.method(req, res)}
path: ${tokens.url(req, res)}
code: ${tokens.status(req, res)}`
})

This will produce a log line output like:

method: GET
path: /
code: 200

tokens.method, tokens.url and tokens.status are examples of functions on the morgan object that can generate values to be logged. To illustrate, the table below shows sample token methods, their token and sample output values:

Token method	Token	Sample output
method	`“:method”`	GET
url	`“:url”`	/
status	`”:status”`	200

The next sections of this article explain how Morgan works under the hood. To follow along, open up Morgan’s index.js file on GitHub.

What Happens When Morgan is Initialised?

When Morgan is initialised, it makes a copy of the arguments provided to it. For arguments that were not provided, Morgan sets default values for them. For instance, if no format string argument was provided, Morgan uses the 'default' named format and logs a deprecation notice afterwards with a suggested fix.

Morgan then sets up the formatLine function - the function that creates and returns the log line for a request when executed. How does it create the log line?

First, Morgan checks if format is a format function. If it is, the format function is assigned to formatLine and next, Morgan sets up the output stream. If format is not a function, it is passed as an argument to getFormatFunction. getFormatFunction accepts format and looks up Morgan’s object store to check if format is:

One of Morgan’s named formats or a user-defined named format created via morgan.format
A token set

If it is neither of the two, Morgan uses the default named format.

function getFormatFunction (name) { // `name` is also `format`
  var fmt = morgan[name] || name || morgan.default

  return typeof fmt !== 'function'
    ? compile(fmt)
    : fmt
}

If the named format corresponds to a format function after the lookup, Morgan returns the format function, which is then assigned to formatLine, else, it corresponds to a token set. Morgan compiles the token set into a format function through the compile function - one of the most important functions in the Morgan package.

How the `compile` Function Works

The compile function accepts a token set and returns a function that has the interface of a format function. How does it do this?

With the JavaScript replace method, it uses a RegEx to search for all occurrences of a token in the token set and replaces each occurrence. If the token set is ':method :res[content-length] - :response-time ms' , the RegEx replace method replaces the tokens as illustrated in the table below:

name	arg	replacement string
‘method’	`undefined`	`(tokens["method"](req, res)
‘res’	`’content-length’`	`(tokens["res"](req, res, "content-length")
‘response-time’	undefined	`(tokens["response-time"](req, res)

The result of the RegEx replace is prefixed with "use strict"\n return "" and ends up producing the string below:

"use strict" 
    return "" +  
    (tokens["method"](req, res) || "-") + " " +   
    (tokens["res"](req, res, "content-length") || "-") + " - " + 
    (tokens["response-time"](req, res) || "-") + " ms"

The string above is used to create a format function using the Function constructor and returned as:

function (tokens, req, res) {
  "use strict"
  return "" +
    (tokens["method"](req, res) || "-") + " " +
    (tokens["res"](req, res, "content-length") || "-") + " - " +
    (tokens["response-time"](req, res) || "-") + " ms"
}

The format function is eventually stored in formatLine.

When formatLine is executed with morgan as the tokens argument, it will create a log line. In the case of the sample token set, it will create a log line that will look like GET 20 - 1.233 ms.

After creating the formatLine function, Morgan uses the createBufferStream function to set up the streaming of the log lines created to the preferred output if set by options.stream. If options.stream is not set, it uses process.stdout.

Morgan does all this setting up so that it can create log lines quickly on capturing a request. It will be inefficient to do all of these for each request.

What Happens When Morgan Captures a Request?

When Morgan captures a request, it stores the IP address of the client using the getip function. Next, it stores the time that the request was triggered in the startAt property of the request object.

Then Morgan tries to generate the log line for the request and log it by executing the logRequest function. Morgan checks if the log line should be output on request, and if it should, Morgan executes logRequest and executes next thereafter to pass the request to the next middleware.

if (immediate) {
  logRequest()
} else {
  onHeaders(res, recordStartTime)
  onFinished(res, logRequest)
}

next()

If the log output should be created on response, Morgan registers two functions on the response object event listeners:

An function to be run when headers start to be written to the response object: When this listener is triggered, it records the time when headers start to be written to the response object as _startAt and startTime. These values are used to calculate the response time and the total time of the request.
A function to be run when the request closes, finishes or errors: It executes logRequest when this event occurs.

Just when Node.js starts sending a response to the client, a _startAt property – the time when the response starts getting sent – is attached to the response object. The absolute difference between _startAt on the request object and _startAt on the response object is the response time of the request and can be seen through ":response-time".

":total-time" is the total time taken from when the request was received to when the response was completely sent. In practice, total-time will be equal to or slightly greater than response-time, depending on how long it takes to write the response body to the stream after the response has started.

Within logRequest, Morgan checks the value of the skip option. If it is a function, it is executed and if it returns true, Morgan doesn’t create a log output for the request and it exits.

function logRequest () {
  if (skip !== false && skip(req, res)) {
    debug('skip request')
    return
  }

  var line = formatLine(morgan, req, res)

  if (line == null) {
    debug('skip line')
    return
  }

  stream.write(line + '\n')
};

If skip is false or executing it evaluates to false, Morgan generates the log line for the request using formatLine. If the log line is null, Morgan exits, else it sends the log line to the output medium and exits.

Next Steps

You have learned how the Morgan Express middleware outputs logs. You now have foundational skills to pick up another middleware or Node.js library like helmet or cors that you use and study it to see how it works. Choose one, study it, write about it, and share it with others.

If you have any questions, you can connect with me on LinkedIn. I’ll be happy to respond.

How to Use Postman Scripts to Simplify Your API Authentication Process

Orim Dominic Adah — Mon, 08 Sep 2025 14:24:49 +0000

Postman is a platform used by developers, API testers, technical writers and DevOps teams for testing, documenting and collaborating on API development. It provides a user-friendly interface for making different types of API requests (HTTP, GraphQL, gRPC), inspecting responses, and organizing API calls into collections for collaboration and automation.

Performing repetitive tasks while testing APIs is stressful and time-wasting. For example, the process of retrieving, copying and pasting new authentication tokens for use in Postman is repetitive. You can simplify this process by using Postman scripts to store auth tokens and then reuse them without repeating the copy and paste steps.

To practice along with this guide, you should have:

The Postman API client installed on your computer
Experience in making API requests with Postman
A backend application that uses JWT authentication and has its documentation in your Postman client

If you don’t have a backend application setup, I created one that you can clone from GitHub at orimdominic/freeCodeCamp-postman-api-jwt.

By the end of this article, you should be able to simplify the process of obtaining and reusing authentication tokens across your API requests. You should also have a practical understanding of some scripts necessary for use in other areas of software testing with Postman.

Table of Contents
What are Postman Scripts?
How to Simplify Your JWT Authentication Process
Next Steps

What are Postman Scripts?

Postman scripts are blocks of JavaScript code that you can write and run within the Postman API client to automate and enhance API testing workflows. You can use Postman scripts to add code to run before and after API requests. These scripts can be used to:

Add logic and process data from API requests
Write test assertions for API responses
Run automated tests on API endpoints

You can find Postman scripts under the Scripts tab of an API request. Code written in the Pre-request tab runs before the request is made and code written in the Post-response tab runs after the response is made.

How to Simplify Your JWT Authentication Process

In summary, you will carry out the following steps to achieve the objective of this tutorial:

Authenticate to get the token
Save the token in a collection variable with Postman scripts
Use the variable in an API request

Authenticate to Get the Token

To get started, carry out the following steps:

Start your backend application and make sure it is running successfully.
Open up your Postman application and go to the API request for signing in to get a JWT.
Make an API request to the sign in endpoint and take note of the JSON response schema.

The highlighted part of the image above shows the JSON response from a successful sign in request. In the response schema, the auth token to be used for authorization is in the data.token field. You will use Postman scripts to store this token in a variable and then use the variable in the Authorization header of requests that require authorization.

How to Save the Token in a Variable with a Postman Script

In Postman, click on the Scripts tab next to the Body tab. If the Postman application window is small, you may need to click a dropdown to see it. Next, click on the Post-response tab. In the text area to the right, you will write the script to capture the auth token from the response and store it in a Postman variable. Copy the JavaScript code below and paste it into the text area.

if (pm.response.code == 200) {
    const token = pm.response.json().data.token
    pm.collectionVariables.set("auth_token", token)
}

Postman scripts use the pm identifier to access and modify information in the Postman environment. The script above uses pm to first ensure that the request was successful by checking if the response status code is 200.

Inside the conditional statement, pm.response.json().data.token is used to get the authentication token from the JSON response and store it in a collection variable called auth_token. If auth_token doesn’t exist already, it is created and its value is set to the value of token. If it exists already, its value is replaced.

To confirm that auth_token has been set, click on the name of the collection (labelled 1 in the screenshot above) and then click on the Variables tab (labelled 2 in the screenshot above). Next, instead of repeatedly copying the token and pasting it in the Authorization header of your requests, you will use auth_token in the Authorization header of your requests.

How to Use the Variable in a Request

Reference the collection variable in the Authorization header by surrounding it with double curly braces {{auth_token}}. When you make an API request, Postman will use the value referenced by {{auth_token}} as the Authorization header.

If another authentication request causes the value of auth_token to be updated, you no longer need to copy the new auth token. The script in the post-response tab will update the auth_token value and you can go on with making API requests smoothly. No need for repeatedly copying and pasting - Don’t Repeat Yourself (DRY).

Next Steps

In this tutorial, you have learnt how to use Postman scripts to set environment variables in Postman. You have also learnt how to eliminate the process of repeatedly copying and pasting auth tokens for use in API requests.

For guides on writing assertion tests for your APIs, check out the Test API Functionality and Performance in Postman guide by Postman.

Common Open Source Contribution Myths – Debunked

Orim Dominic Adah — Tue, 02 Sep 2025 14:49:17 +0000

Many developers shy away from contributing to open source, as it can be intimidating and hard to get started. Even though your contributions might seem inconsequential at first, they can potentially have a huge impact on your career.

In this article, we’ll discuss some common misconceptions that might be holding you back from contributing to open source. I’ll show you what you’re missing out on, and give you some advice to help you begin.

What is Open Source?
Key Factors Influencing Open Source Contributions
Why People Hesitate to Contribute
Start Contributing to Open Source Today

What is Open Source?

Open source refers to software that has its code publicly available for viewing, modification, and use. The code is usually hosted on platforms like GitHub where developers can contribute to the codebase and share their expertise with the project.

Although open source software code is publicly accessible, it doesn’t mean that the software has to be free. Creators of the software can make money by charging a fee for things like optional plugins, consultation about the software, and so on.

Nginx is an example of open source software that charges a fee for additional but optional plugins. NestJS is open source too, but has an official paid course (and its maintainers charge a consultation fee for more complex uses of the software).

Key Factors Influencing Open Source Contributions

In 2023, roughly 10% of Alphabet’s full-time workforce actively contributed to open source projects. And according to GitHub’s 2024 Open Source Survey, respondents reported that the top five factors that influenced their contribution to open source projects, in order of importance, were:

Whether the project had an open source license or not. Having an open source license was considered favourable.
The responsiveness of the project’s maintainers. Fast and positive responses are encouraging.
A welcoming community, indicating support from the maintainers and others contributing to the project.
The level of activity on the project – lots of activity signifies an actively maintained project (which is more rewarding and useful to work on).
Whether the project had a contribution guide that helps developers ease into contributing to the project.

But even though many projects are attractive, and their maintainers are welcoming, some people still hesitate to contribute for reasons not linked to the projects themselves.

Why People Hesitate to Contribute

After looking into responses from various discussions, I found that there are three primary barriers developers face when they’re considering contributing to open source:

You feel like an impostor
You have to do it for free
You have a busy schedule

The rest of this article will address (and hopefully break down) these barriers. I hope that by the end, you’ll be encouraged to contribute to open source.

You feel like an impostor

Many people think that you have to know a lot about a project to work on it, but this misconception is one of the biggest barriers that holds developers back from contributing to open source. Some people say to themselves “I don't have the experience”, “I have nothing to contribute”, “What if I break something?”, “I don’t know enough”.

Here’s some advice from How to Overcome Imposter Syndrome that can help:

Stop obsessing over not being good enough. It’s unproductive.
Everyone excels at different things. You likely excel at some things that others don’t.
Don’t compare yourself with others who are more experienced than you. In fact, stop comparing yourself with anyone else. You are unique.

Try to contribute to projects that you have used. You already understand them better than projects that you haven’t used. As a beginner, working on issues labeled “good first issue”, “up-for-grabs”, “beginner-friendly” and so on is a great place to start. If you find an issue that interests you, read the discussions under it if there are any so you can understand it better. State that you are interested in working on it and an experienced contributor will likely respond to let you know if you can proceed. They can also provide you with more information if you need it.

Put in the work to resolve it yourself first, and if you have any issues, then you can ask more questions. When you try to resolve it yourself before asking questions, it tells maintainers that you have put in the effort and they will be more willing to help. It also makes your question(s) sound thoughtful and direct.

“The three most powerful motives are curiosity, delight, and the desire to do something impressive. “

— How to Do Great Work by Paul Graham

I shared my experience in an article titled You Don't Need to Know It All to Contribute where I found out that the author of a popular JavaScript project was not the one that wrote the TypeScript part of the project and he was happy to receive my contribution.

If you still feel like you are not good enough, try to look at it as an opportunity to learn from a codebase built by developers with a wide range of experiences and expertise. If you dive into the code and try to improve it, you’ll learn things that you won’t find in online tutorials and blog posts.

Just keep in mind that you don’t always have to contribute code. Even though the majority of contributions are usually code-based, there are other areas that need attention, too, and are often overlooked. What happens if the documentation is nonexistent or outdated? What happens when issues aren’t triaged? You can help with these issues by:

Discussing them with project maintainers and other contributors to clarify and improve docs and other resources
Giving feedback on pull requests
Adding labels for organising issues into proper categories

By doing this, you provide value to these projects. What matters is your interest in solving problems and your ability to do the required research.

You have to do it for free

Another misconception is that devs always do open source without getting paid. But this isn't true for all cases. Some open source repositories reward contributors via bounties, for example. With bounties, prize money is placed on an an issue and whoever solves it gets the prize money or reward. I earned money through this via my first contribution to Remotion.

And there are other benefits of contributing to open source projects aside from getting paid. And often, people contribute primarily for these other reasons.

For example, for beginner developers, there aren’t many opportunities to get hands-on experience building “real” projects, or to learn what working on a tech team is really like.

But by contributing to an open source project and becoming part of that community, you get to practice teamwork, contribute to code that’s constantly changing and growing, and solve real-life problems. This gives you valuable experience that’ll help prepare you for the workforce (and that you can put on your résumé). The image below is a screenshot of two people who received a scholarship from the Linux Foundation for their contributions to open source.

So as you can see, even if you don’t get monetary rewards, contributing to open source presents many other opportunities. You get to:

Work with people from diverse cultures
Develop clear written technical communication skills
Improve your knowledge of various tools/frameworks
Prove yourself to be a self-motivated developer
Work asynchronously with people across multiple time zones

You also get the opportunity to network with other developers and grow your reputation and credibility in the software development space. Prosper Otemuyiwa and Anthony Fu are great examples and beneficiaries of this type of career growth.

You have a busy schedule

Having other pressing commitments is a reasonable barrier to contributing to open source. We’re all human, and our resources (time and energy) are limited – so we have to manage them judiciously.

But have you considered what would happen if the open source project that you use had a serious bug that affects your performance or deliverables at work? What happens when the problem you are trying to solve at work requires expert knowledge of that open source project that you heavily depend on?

Contributing to open source projects in the little ways that you can will give you insight into how the projects work. Since you have to maintain a rapport with other developers on the project, you’ll form a professional bond with them and they’ll be glad to help you out if you have questions or require expert opinions on the project. If you are a major contributor, you may have the chance to influence the project’s roadmap.

Continuing to develop your skills is paramount to you as a developer. If you can make time to improve your skills, then you can make time to contribute to open source because it offers more rewards than just skill improvement. You can start small – try dedicating, for example, one hour a week before work, or a couple hours on the weekend. Then you can ramp up once you get into the rhythm and find more time. Contributing to open source doesn’t have to be overly demanding.

You’re already solving problems. Why not solve them in a visible way that helps others and builds your own credibility?

Start Contributing to Open Source Today

We all should contribute to open source one way or another. If you feel that you don’t know enough, just keep in mind that other people feel (or felt, before starting) the same way. And know that nobody can claim to know it all – not even the founder of the project. So don’t let the feeling of impostor syndrome hold you back.

Remember also that Rome was not built in a day. It wasn’t also built by one person’s hand – but by countless laborers over many centuries and millennia. You could be part of building the next great open source project (or helping maintain the many great ones that are already out there and need your help).

So consider contributing today by visiting the issues tab of any of the open source projects that you use extensively and pick up something. You can find links to beginner-level issues from the following websites:

If you see an issue that you are interested in, take the following steps as a new contributor:

Look for a CONTRIBUTING.md file and read it for guidance on how to contribute
Clone the repository and set it up locally
State your intention to work on the issue by making a comment on the issue

Ask a question if an issue is unclear to you and you’ll get guidance.

Good luck on your open source journey!

How to Assign Unique IDs to Express API Requests for Tracing

Orim Dominic Adah — Tue, 19 Aug 2025 17:50:34 +0000

The ability to track what happens with API requests is an important aspect of monitoring, tracing and debugging back-end applications. But how do you differentiate between the reports of two consecutive API requests to the same API endpoint?

This article aims to show you how to:

Properly assign a unique ID to API requests in your Express applications,
Store and access the ID using the AsyncLocalStorage API in Node.js, and
Use it in request logging.

Experience in creating API endpoints and using middleware in Express will be helpful as you follow along with this guide. You can also apply ideas from this article to frameworks like NestJS and Koa.

Getting Started with the Starter Repository
Set Up Logger Utilities
What is AsyncLocalStorage and Why is it Important?
Store the Request ID in AsyncLocalStorage
Use the Request ID in the Logger Utilities
Set Header to have X-Request-Id (Optional Challenge)
Conclusion

Getting Started with the Starter Repository

To make it easier to follow along, I’ve created a starter project and hosted it on GitHub. You can clone it from here. To get it up and running on your local computer, install its dependencies using your preferred JavaScript package manager (npm, yarn, pnpm, bun). Then start the application by running the npm start command in the terminal of the project.

If the application starts successfully, it should log the snippet below on the terminal:

Listening on port 3333

The application has only one API endpoint currently – a GET / . When you make an API request to the endpoint using curl or a browser by visiting http://localhost:3333, you will get an “OK” string as the payload response:

$ curl -i http://localhost:3333

OK%

If the snippet above is what you see, then congratulations! You have set the project up correctly.

Set Up Logger Utilities

The first step is to set up custom loggers for logging messages to the terminal. The loggers will log the events that occur during the process of handling an API request and log the summary of the request.

To achieve this, you’ll need to install two Express middlewares – morgan and winston – using your preferred package manager. If you use npm, you can run the command below in the folder terminal of the project:

$ npm install morgan winston

If the above command is successful, morgan and winston will be added to the dependencies object in package.json. Create a file named logger.js in the root folder of the project. logger.js will contain the code for the custom logger utilities.

The first logger utility you will create is logger, created from the winston package you installed earlier. logger is an object with two methods:

info for logging non-error messages to the terminal
error for logging error messages to the terminal

// logger.js

const winston = require("winston");

const { combine, errors, json, timestamp, colorize } = winston.format;

const logHandler = winston.createLogger({
  level: "debug",
  levels: winston.config.npm.levels,
  format: combine(
    timestamp({ format: "YYYY-MM-DD hh:mm:ss.SSS A" }), // set the format of logged timestamps
    errors({ stack: true }),
    json({ space: 2 }),
    colorize({
      all: true,
      colors: {
        info: "gray", // all info logs should be gray in colour
        error: "red", // all error logs should be red in colour     
        },
    })
  ),
  transports: [new winston.transports.Console()],
});

exports.logger = {
  info: function (message) {
    logHandler.child({}).info(message);
  },

  error: function (message) {
    logHandler.child({}).error(message);
  },
};

In the code snippet above, winston.createLogger is used to create logHandler. logger is exported out of the logger.js module and logger.info and logger.error are functions that use logHandler to log messages to the terminal.

The second logger utility will be a middleware that will log information about the request just before the request response is sent to the client. It will log information such as how long it took to run the request and the status code of the request. It will be called logRequestSummary and will use the morgan package and the http method of logHandler.

// logger.js

const winston = require("winston");
const morgan = require("morgan");

const { combine, errors, json, timestamp, colorize } = winston.format;

const logHandler = winston.createLogger({
  // ...
  format: combine(
    // ...
    colorize({
      all: true,
      colors: {
        // ...
        http: "blue", // 👈🏾 (new line) logs from logRequestSummary will be blue in colour
      },
    })
  ),
  // ...
});

exports.logger = {
    // ...
};

exports.logRequestSummary = morgan(
  function (tokens, req, res) {
    return JSON.stringify({
      url: tokens.url(req, res),
      method: tokens.method(req, res),
      status_code: Number(tokens.status(req, res) || "500"),
      content_length: tokens.res(req, res, "content-length") + " bytes",
      response_time: Number(tokens["response-time"](req, res) || "0") + " ms",
    });
  },
  {
    stream: {
      // use logHandler with the http severity
      write: (message) => {
        const httpLog = JSON.parse(message);
        logHandler.http(httpLog);
      },
    },
  }
);

The JSON string returned by the first function when the morgan function is executed is received by the write function of the stream object in the second argument passed to the organ function. It’s then parsed to JSON and passed to logHandler.http to be logged with the winston.npm http severity level.

At this point, two objects are exported from logger.js: logger and logRequestSummary.

In index.js, create a new controller to handle GET requests to the /hello path. Also import and use the exported objects from logger.js. Use logger to log information when events occur in controllers and include logRequestSummary as a middleware for the application.

// index.js
const express = require("express");
const { logRequestSummary, logger } = require("./logger");

const app = express();

app.use(
  express.json(),
  express.urlencoded({ extended: true }),
  logRequestSummary // logger middleware utility
);

app.get("/", function (req, res) {
  logger.info(`${req.method} request to ${req.url}`); // logger utility for events
  return res.json({ method: req.method, url: req.url });
});

app.get("/hello", function (req, res) {
  logger.info(`${req.method} request to ${req.url}`); // logger utility for events
  return res.json({ method: req.method, url: req.url });
});

// ...

Stop the application (with CTRL + C or OPTION + C), and start it again with npm start. Make API requests to both API endpoints, you’ll see output similar to the snippet below in the terminal – an event log first and a log of the summary of the request after.

{
  "level": "info",
  "message": "GET request to /",
  "timestamp": "2025-08-16 10:35:06.831 PM"
}
{
  "level": "http",
  "message": {
    "content_length": "26 bytes",
    "method": "GET",
    "response_time": "9.034 ms",
    "status_code": 200,
    "url": "/"
  },
  "timestamp": "2025-08-16 10:35:06.844 PM"
}

You can view the latest state of the code by switching to the 2-custom-logger-middleware branch using git checkout 2-custom-logger-middleware or by visiting branch 2-custom-logger-middleware of the repository.

Now that you’re able to log and view events that occur for each API request, how do you differentiate between two consecutive requests to the same endpoint? How do you figure out which API request logged a specific message? How do you specify the API request to trace when communicating with your teammates? By attaching a unique ID to each request, you’ll be able to answer all these questions.

What is AsyncLocalStorage and Why is it Important?

Before AsyncLocalStorage, users of Express stored request context information in the res.locals object. With AsyncLocalStorage, Node.js provides a native way to store information that’s necessary for executing asynchronous functions. According to its documentation, it’s a performant and memory-safe implementation that involves significant optimizations that would be difficult for you to implement by yourself.

When you use AsyncLocalStorage, you can store and access information in a similar manner to localStorage in the browser. You pass the store value (usually an object, but it can be a primitive value, too) as the first argument and the asynchronous function that should access the store value as the second argument when you execute the run method.

James Snell, one of the leading contributors of Node.js explains it further in this video Async Context Tracking in Node with Async Local Storage API.

Store the Request ID in AsyncLocalStorage

In the project, create a file with the name context-storage.js. In this file, you’ll create an instance of AsyncLocalStorage (if it hasn’t been created yet) and export it. This instance of AsyncLocalStorage will be used in storing and retrieving the request IDs for the logger and any other context that needs the request ID.

// context-storage.js
const { AsyncLocalStorage } = require("node:async_hooks");

let store;

module.exports.contextStorage = function () {
  if (!store) {
    store = new AsyncLocalStorage();
  }

  return store;
};

You’ll create another file called set-request-id.js which will create and export a middleware. The middleware will intercept API requests, generate a request ID, and store it in the instance of AsyncLocalStorage from context-storage.js if it doesn’t exist in it already.

You can use any ID-generating library you want, but here we’ll use randomUUID from the Node.js crypto package.

// set-request-id.js
const { randomUUID } = require("node:crypto");
const { contextStorage } = require("./context-storage");

/**
 * Preferably your first middleware.
 *
 * It generates a unique ID and stores it in the AsyncLocalStorage
 * instance for the request context.
 */
module.exports.setRequestId = function () {
  return function (_req, _res, next) {
    requestId = randomUUID();
    const store = contextStorage().getStore();

    if (!store) {
      return contextStorage().run({ requestId }, next);
    }

    if (store && !store.requestId) {
      store.requestId = requestId;
      return next();
    }

    return next();
  };
};

In the setRequestId function in the snippet above, the instance of AsyncLocalStorage created in context-storage.js is retrieved from the return value of executing contextStorage as store. If store is falsy, the run method executes the next Express callback, providing requestId in an object for access anywhere within next from contextStorage.

If store has a value but doesn’t have the requestId property, set the requestId property and its value on it and return the executed next function.

Lastly, place setRequestId as the first middleware of the Express application in index.js so that every request can have an ID before carrying out other operations.

// index.js
const express = require("express");
const { logRequestSummary, logger } = require("./logger");
const { setRequestId } = require("./set-request-id");

const app = express();

app.use(
  setRequestId(), // 👈🏾 set as first middleware
  express.json(),
  express.urlencoded({ extended: true }),
  logRequestSummary
);

// ...

You can check the current state of this project if you run the git checkout 3-async-local-storage-req-id command on your terminal or by visiting 3-async-local-storage-req-id of the GitHub repository.

Use the Request ID in the Logger Utilities

Now that the requestId property has been set in the store, you can access it from anywhere within next using contextStorage. You’ll access it within the functions in logger.js and attach it to the logs so that when messages are logged to the terminal for a request, the request ID will appear with the logged message.

// logger.js
const winston = require("winston");
const morgan = require("morgan");
const { contextStorage } = require("./context-storage");

const { combine, errors, json, timestamp, colorize } = winston.format;

const logHandler = winston.createLogger({
  level: "debug",
  levels: winston.config.npm.levels,
  format: combine(

    // 👇🏽 retrieve requestId from contextStorage and attach it to the logged message
    winston.format((info) => {
      info.request_id = contextStorage().getStore()?.requestId;
      return info;
    })(),
    // 👆🏽 retrieve requestId from contextStorage and attach it to the logged message

    timestamp({ format: "YYYY-MM-DD hh:mm:ss.SSS A" }),
    errors({ stack: true }),
    // ...
  ),
  transports: [new winston.transports.Console()],
});

// ...

In the combine function from winston, you’ll include a function argument that accepts the message to be logged – info – as an argument and attach the request_id property to it. Its value is the value of requestId retrieved from contextStorage. With this modification, any message logged for a request will have the request ID for that request attached to it.

With this complete, stop the project from running if it’s running already and run it again with the npm start command. Make API requests to the two endpoints and you’ll see output similar to the snippet below on the terminal:

{
  "level": "info",
  "message": "GET request to /hello",
  "request_id": "c80e92d0-eafe-42c7-b093-e5ffce014819",
  "timestamp": "2025-08-17 07:58:13.571 PM"
}
{
  "level": "http",
  "message": {
    "content_length": "31 bytes",
    "method": "GET",
    "response_time": "9.397 ms",
    "status_code": 200,
    "url": "/hello"
  },
  "request_id": "c80e92d0-eafe-42c7-b093-e5ffce014819",
  "timestamp": "2025-08-17 07:58:13.584 PM"
}

Unlike the previous log output, this one contains the request ID of each request. By using AsyncLocalStorage to efficiently store the value of the request ID and access it for use in the loggers, you can accurately trace logged messages to their API requests.

You can access the current state of the project if you run the git checkout 4-use-context-in-logger command on the terminal or by visiting 4-use-context-in-logger of the GitHub repository.

Set Header to have X-Request-Id (Optional Challenge)

You have been able to store, access, and attach a request’s ID to its logged message. Can you set the request ID as a header on the response? The challenge is to set a header, X-Request-Id, on the response so that every request response has the value of the request ID as the value of the X-Request-Id response header.

This is useful for communicating with the frontend when trying to debug requests.

Conclusion

When API requests can be monitored, you can track performance metrics to discover areas that need improvement and attention, identify issues like failed requests and server errors and why they happened, and study patterns in request volume metrics for planning and scalability.

When you attach a unique identifier to an API request, you can use it to trace the events that occurred within the lifetime of the request and differentiate it from other requests of the same type.

Aside from using AsyncLocalStorage to store request IDs, you can also use it to store other request context information such as the authenticated user details. Using AsyncLocalStorage to store request context information is considered a best practice.

How to Write Tests Using the Node.js Test Runner and mongodb-memory-server

Orim Dominic Adah — Thu, 13 Feb 2025 16:33:20 +0000

I recently migrated some tests from Jest to the Node.js test runner in two of my projects that use MongoDB. In one of those projects, test runtime was reduced from 107 seconds to 25 seconds (screenshot below). In the other project, test runtime was reduced by about 66%.

I decided to share with you how I was able to implement this. I think you’ll find it helpful, as it’s more cost-effective (in terms of reducing money spent on running tests in CI/CD), and it also improves your developer experience.

Prerequisites
The Node.js Test Runner
MongoDB In-Memory Server
How to Write the Tests
Conclusion

Prerequisites

To follow along with this guide, you should have experience working with Node.js, MongoDB, and Mongoose (or any other MongoDB object data mapper). You should also have Node.js (at least v20.18.2) and MongoDB installed on your computer.

The Node.js Test Runner

The Node.js test runner was introduced as an experimental feature in version 18 of Node.js. It became fully available in version 20. It gives you the ability to:

Run tests
Report test results
Report test coverage (still experimental at version 23)

It’s a good idea to use the in-built test runner when writing tests in Node.js because it means that you have to use fewer external dependencies. You don’t need to install an external library (and its peer dependencies) to run tests.

The built-in best runner is also faster. Based on my experience using it on two projects (which formerly used Jest), I saw improvements of at least a 66% reduction in the time taken to run tests completely.

And unlike other testing frameworks or libraries, the Node.js test runner was built specifically for Node.js projects. It doesn’t try to accommodate the specifics of other programming environments like the browser. The specifics of Node.js are its main and only priority.

MongoDB In-Memory Server

For tests that involve making requests to a database, some developers prefer to mock the requests to avoid making requests to a real database. They do this because making a request to a real database requires a lot of setting up which can cost time and resources.

Writing and fetching data using a real database is slower compared to writing and fetching data from memory. When running automated tests, using a real MongoDB server will be slower than using an in-memory database server, and that is where mongodb-memory-server becomes useful.

According to its documentation, mongodb-memory-server creates and starts a real MongoDB server programmatically from within Node.js, but uses an in-memory database by default. It also allows you to connect to the database server it creates using your preferred object data mapper such as Mongoose, Prisma, or TypeORM. In this guide, we’ll use Mongoose (v8.9.6).

Since the data stored by mongodb-memory-server resides in memory by default, it’s faster to read from and write to than when using a real database. mongodb-memory-server is also easier to set up. These benefits make it a good choice for using it as a database server for writing tests.

Note: Make sure to install v9.1.6 of mongodb-memory-server to follow this guide. v10 currently has issues with cleaning up resources after tests are done. See this issue titled Node forking will include any --import from the original command.

The issue has been resolved at the time of writing this article, but the fix has not been merged for installs.

How to Write the Tests

Now I’ll take you through the following steps to get you started writing tests:

Set up the project
Set up mongoose schema
Set up services
Set up tests
Write tests
Pass tests
Use TypeScript (Optional)

1. Set Up the Project

I created a GitHub repository to make it easier for you to follow this guide. Clone the repository at nodejs-test-runner-mongoose and checkout branch 01-setup.

In 01-setup, the dependencies for the project are in the package.json file. Install the dependencies using the npm install command to set up the project. To make sure that the setup is complete and correct, run the node . command in the terminal of your project. You should see your version of Node.js as an output on the terminal.

# install dependencies
npm install
...
# run the node command
node .
# the output
You are running Node.js v22.13.1

2. Set up Mongoose Schema

We’ll set up the schema for two collections (Task and User) in branch 02-setup-schema using Mongoose. The task/model.mjs and user/model.mjs files contain the schema for the Task and the User collection, respectively. We’ll also set up a database connection in index.mjs to ensure that the schema setup works correctly.

I won’t go into detail about Mongoose models and schema in this article because they are outside its scope.

When you run the node . command after implementing the changes in 02-setup-schema, you should see a similar result in the console as in the snippet below:

node .
You are running Node.js v22.13.1
Created user with id 679f1d7f73fbeaf23b2007df
Created task "Task title" for user with id "679f1d7f73fbeaf23b2007df"

You can see the differences between 01-setup and 02-setup-schema via the 01-setup <> 02-setup-schema diff on GitHub.

3. Set Up Services

Next, we create service files (task/service.mjs and user/service.mjs) in branch 03-setup-services. Both files currently contain empty functions that we’ll write tests for later. These functions will contain business logic and also communicate with the database. We’re using JSDoc comments for typing parameters and return values.

Click 02-setup-schema <> 03-setup-services diff to see the code changes between 02-setup-schema and 03-setup-services.

4. Set Up Tests

In branch 04-set-up-tests, we set up the codebase to run tests. We create test.setup.mjs which contains code that will be run before each test file is executed.

In test.setup.mjs, the connect function creates a MongoDB In-Memory server and connects to it with Mongoose for running the tests. The closeDatabase function closes the database connection and cleans up all resources to free memory.

The connect and closeDatabase functions get executed in the t.before hook and the t.after hook respectively. This ensures that, before a test file is run, a database connection is established through t.before. Then after tests for the file have been completely run, the database connection is dropped and the resources used are cleared up through t.after.

In package.json, we’ll update the npm test script to node --test --import ./test.setup.mjs. This command ensures that the test.setup.mjs ES Module is preloaded and executed through the --import CLI command before each test file is run.

Then we’ll create the test files with empty tests in the __tests__ folders for user and task. After implementing the new changes in 04-set-up-tests, running the test script with npm run test should display output similar to the snippet below:

npm run test

> nodejs-test-runner-mongoose@1.0.0 test
> node --test --import ./test.setup.mjs

...

ℹ tests 8
ℹ suites 5
ℹ pass 8
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 941.768873

All tests currently pass because there are no assertions that fail in them. We’ll write tests with assertions in the following section.

5. Write Tests

Now it’s time to write tests for the functions in the service files in the 05-write-tests branch. We’re using the Node.js assert library to ensure that values returned from the functions are what we expect. You can view the tests we’ve written when you compare the differences between 04-set-up-tests and 05-write-tests

When the tests script is run, all tests fail because we haven’t written the functions in the service files yet. You should see output similar to the snippet below when you run the test script:

npm run test

> nodejs-test-runner-mongoose@1.0.0 test
> node --test --import ./test.setup.mjs

...

ℹ tests 8
ℹ suites 5
ℹ pass 0
ℹ fail 8
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 1202.031961

6. Pass Tests

In 06-pass-tests, we write the functions in the service files to pass the tests. Only 6 out of 7 tests pass when the test script is run because we skipped the test for the getById function in user/service.mjs has with t.skip. We haven’t finished the getById function in user/service.mjs. I figured we could leave it as an exercise.

When you run the test script, you should get a similar output in the terminal as below:

ℹ tests 7
ℹ suites 4
ℹ pass 6
ℹ fail 0
ℹ cancelled 0
ℹ skipped 1
ℹ todo 0
ℹ duration_ms 1287.564918

You can see the code we wrote to pass tests in the code changes between 05-write-tests and 06-pass-tests.

7. Use TypeScript (Optional)

If you intend to run tests with TypeScript, you can checkout branch 07-with-typescript. You need to have Node.js >=v22.6.0 installed because we’re using the --experimental-strip-types option in the test. To set up tests to run with TypeScript, go through the following steps:

Install TypeScript using the npm install typescript --save-dev command
Install tsx using the npm install tsx command
Create a default tsconfig.json file at the root of the project using the npx tsc --init command

In package.json, update the test script to this:

"test": "node --test --experimental-strip-types --import tsx --import ./test.setup.mjs"

--experimental-strip-types helps strip out types before each test file is executed.
Preloading tsx with the --import helps execute the TypeScript file. Without it, the test runner will not be able to find files imported without the .ts extension. For example, user/model.ts imported with the code snippet below will not be found.
```
  import { UserModel } from "./model";
```

The rest of the changes from 06-pass-tests to 07-with-typescript involve updating types, changing file extensions from .mjs to .ts and updating import statements.

Conclusion

In this guide, you have learned how to use the built-in Node.js test runner and why it’s often a better choice over other testing libraries and frameworks. You have also learned how to use mongodb-memory-server as a replacement for a real MongoDB server, as well as why it’s a good idea to use this instead of a real MongoDB server for tests.

Most importantly, you have learned how to set up and run tests in Node.js using the Node.js test runner and mongodb-memory-server. You should now know how to set up your projects to run the tests if you use TypeScript.

If you find the nodejs-test-runner-mongoose repository useful, kindly give it a star. It encourages me. Thank you.

How to Write Code That's Easy to Read – Tips for Developers

Orim Dominic Adah — Wed, 04 Dec 2024 17:57:23 +0000

Programs are meant to be read by humans and only incidentally for computers to execute. - Donald Knuth

Have you ever heard that programmers spend more time reading code than writing it? Well, I’ve found that this is often true: as a developer, you’ll often spend more time reading and thinking about code than actually writing code.

This means that, however optimally you intend to make your code run, it’s also important that it’s delightful and easy to read.

In this article, we’ll look at an example function: createOrUpdateUserOnLogin. It lives in a JavaScript codebase far away and it’s begging to be made delightful to read. We will look at createOrUpdateUserOnLogin, highlight what makes it hard to read and why, and eventually refactor it to make it easier to read and understand.

The function is written in JavaScript and uses JSDoc to document its parameters. Knowledge of JavaScript is not necessarily important because the logic in the function will be explained in detail. JSDoc is only used to document what the function’s parameters represent.

The Problematic Function

This function is not made-up. It is a real function in the codebase of an application with more than a thousand users. Here it is:

/**
 * @param {Object} dto
 * @param {string} dto.email
 * @param {string} dto.firstName
 * @param {string} dto.lastName
 * @param {string} [dto.photoUrl]
 * @param {'apple' | 'google'} [dto.loginProvider]
 * @param {string} [dto.appleId]
 * @returns {string} token - access token
 */
async function createOrUpdateUserOnLogin(dto) {
  let user;

  if (dto.loginProvider == "apple") {
    user = await findOneByAppleId(dto.appleId);
    if (user?.isDisabled) {
      throw new Error("Unable to login");
    }

    if (user && !user.verified) {
      user = await setUserAsVerified(user.email);
    }

    if (!user) {
      user = await findOneByEmail(dto.email);

      if (user && dto.appleId) {
        user = await updateUserAppleId(user, dto.appleId);
      }

      if (user && !user.verified) {
        user = await setUserAsVerified(user.email);
      }
    }
  } else {
    user = await findOneByEmail(dto.email);
    if (user?.isDisabled) {
      throw new Error("Unable to login");
    }

    if (user && !user.photoUrl && dto.photoUrl) {
      user.photoUrl = dto.photoUrl;
      user = await updateUserDetails(user._id, user);
    }

    if (user && !user.verified) {
      user = await setUserAsVerified(user.email);
    }
  }

  if (!user) {
    user = await this.usersService.create(loginProviderDto);
  }

  return await this.createToken(user);
}

Perhaps you can tell by reading through and studying the code that it is quite hard to follow. If you leave your computer for a break right after reading this function, there is a good chance you won’t remember what exactly it does when you get back.

But this isn’t, and shouldn’t be, the case when you read a good story, regardless of its length. You can follow it easily and remember the basic details after hearing it.

The function is executed when a user attempts to sign in or sign up. Users can be authenticated using their Google account or their Apple account and the function has to return an access token on a successful attempt.

Some users have disabled their account. Those users are not allowed to authenticate successfully. The logic of the function also includes operations for updating the data of already-registered users based on some conditions.

The function does one of two things:

It creates an authentication token for an existing account and returns it after updating the account details or,
It creates an account if none exists and returns an authentication token.

This violates the Single Responsibility Principle – but fixing that is a challenge for another article.

The goal here is to refactor this function so that it reads so well that even a non-programmer can read it and understand what it does. Even better, we also want them to be able to remember it after they’ve been away from it for a while.

The function is well-tested, so there are no worries about breaking any functionality while refactoring. Tests will report any breaking changes.

What Makes This Code Hard to Read?

A number of factors make this code harder to read. Here are the main ones:

Deep nesting (if statements within if statements) makes it hard to keep track of the changes that occur through the execution of the code. In the case of createOrUpdateUserOnLogin, it is nested conditionals. Other cases can include logic like an if statement inside a while loop which is nested inside another if statement.

Deep nesting increases the complexity of reading and understanding code. Its flow isn’t pleasant to the eyes and it makes writing tests more complicated because you have to cater for the operations inside the nested code blocks.
Complex conditionals like user && !user.photoUrl && dto.photoUrl hold a lot of logic which has to be kept in your short-term memory and remembered as you read on.
Haphazard flow which makes it hard for you to tell at a glance what the function is doing. The function seems to be doing a lot, but it really is not. Two operations are repeated: preventing disabled users from logging in (twice) and updating users’ verification status (three times). Finding a user by email is also repeated twice.

How to Refactor the Code for Easier, More Delightful Reading

After examining the function for issues that make it difficult to read, here are a couple of changes you’ll want to implement:

Handle failure cases first: Consider failure cases first and get them out of the story so that the function can focus on the success cases for a smooth narration of the logic of the code.

This involves the use of return statements or throwing errors early in the function for operations that prevent the goal of the function from being achieved.

Rearrange the flow: If it’s possible that some operations can occur before others and it will make the flow of the code memorable and enjoyable to read, while still achieving the purpose of the function, then you should rearrange it accordingly.

Use everyday grammar: This involves updating identifiers and compressing complex conditionals into memorable identifier names. Everyday grammar is easy to read because it is familiar and relatable.

Avoid nested code blocks: When debugging code mentally or trying to understand it, changes in the value of identifiers in nested code blocks are hard to keep track of. This is because with each nested conditional, there is at least a 2x increase in the number of paths that the logic execution can take to update the value of one identifier – and that gets worse if there is more than one identifier that is updated.

This means that your mind has to keep track of those paths which can escalate quickly into a mental memory overload, potentially resulting in mental grief and bugs when updating the code.

The visual effect of nested code is also not pleasant to the eyes and it makes writing tests more complex than it should be.

After refactoring the code using the guidelines above, we have the following snippet (I’ve numbered different parts of the code for reference in the explanations below):

async function updateUserOnLogin(dto) {
  let user = await findUserByEmail(dto.email); // 1
  if (!user) {
    user = await createUser(dto);
  }

  if (user.isDisabled) { // 2a
    throw new Error("Unable to login"); // 2b
  }

  const userIsNotVerified = Boolean(user.isVerified) == false // 3a
  if (userIsNotVerified) { // 3b
    await setUserAsVerified(user.email);
  }

  const shouldUpdateAppleId = dto.loginProvider == "apple" && dto.appleId // 4a
  if (shouldUpdateAppleId) { // 4b
    await setUserAppleId(user.email, dto.appleId);
  }

  const shouldUpdatePhotoUrl = !user.photoUrl && dto.photoUrl // 5a
  if (shouldUpdatePhotoUrl) { // 5b
    await updateUserDetails(user._id, { photoUrl: dto.photoUrl });
  }

  return await this.createToken(user);
}

Alright, now let’s see what exactly we’ve done here to make the code more enjoyable to read.

1. Rearranging the Flow

Judging by the JSDoc comment above the function, email is a required argument field. Existing accounts have an email address irrespective of their login provider. We can fetch an account by email first and decide to create a new one if none exists (code section 1). By doing this, failure cases are handled early.

Choosing to throw an error if the account is disabled at the beginning (section 2b) is also an attempt to handle failure cases early. This does not affect new accounts because new accounts are not disabled by default.

Handling failure cases early helps us understand the code easier because we’re free to consider only what is going to happen without keeping track of error cases from before (like remembering if the user object has a value or not (section 5)) as we read on.

The refactored code has also eliminated nested conditionals and still works as expected.

2. Using Everyday Grammar

In trying to make the code read like everyday grammar, we’ve used clear and relatable variable names (see sections 2a, 3, 4, 5). Written this way, even non-programmers like product managers can read the code and understand what is happening.

Everyday grammar reads like pseudocode - “If user is not verified then set user to verified” and “If should update apple id then update appleId”.

Using everyday grammar is key to making code read like a story.

Conclusion

Code that is delightful to read promotes maintainability and thus, longevity of software. Contributors can read it, understand it, and eventually update it with ease. Like reading a well-written story, reading code can be an enjoyable activity.

Image credit: Work illustrations by Storyset

How to Handle MongoDB Migrations with ts-migrate-mongoose

Orim Dominic Adah — Wed, 27 Nov 2024 14:06:04 +0000

Database migrations are modifications made to a database. These modifications may include changing the schema of a table, updating the data in a set of records, seeding data or deleting a range of records.

Database migrations are usually run before an application starts and do not run successfully more than once for the same database. Database migration tools save a history of migrations that have run in a database so that they can be tracked for future purposes.

In this article, you’ll learn how to set up and run database migrations in a minimal Node.js API application. We will use ts-migrate-mongoose and an npm script to create a migration and seed data into a MongoDB database. ts-migrate-mongoose supports running migration scripts from TypeScript code as well as CommonJS code.

ts-migrate-mongoose is a migration framework for Node.js projects that use mongoose as the object-data mapper. It provides a template for writing migration scripts. It also provides a configuration to run the scripts programmatically and from the CLI.

How to Set Up the Project
How to Configure ts-migrate-mongoose for the Project
How to Seed User Data with ts-migrate-mongoose
How to Build an API Endpoint to Fetch Seeded Data
Conclusion

How to Set Up the Project

To use ts-migrate-mongoose for database migrations, you need to have the following:

A Node.js project with mongoose installed as a dependency.
A MongoDB database connected to the project.
MongoDB Compass (Optional – to enable us view the changes in the database).

A starter repository which can be cloned from ts-migrate-mongoose-starter-repo has been created for ease. Clone the repository, fill the environment variables and start the application by running the npm start command.

Visit http://localhost:8000 with a browser or an API client such as Postman and the server will return a "Hello there!" text to show that the starter application runs as expected.

How to Configure ts-migrate-mongoose for the Project

To configure ts-migrate-mongoose for the project, install ts-migrate-mongoose with this command:

npm install ts-migrate-mongoose

ts-migrate-mongoose allows configuration with a JSON file, a TypeScript file, a .env file or via the CLI. It is advisable to use a .env file because the content of the configuration may contain a database password and it is not proper to have that exposed to the public. .env files are usually hidden via .gitignore files so they are more secure to use. This project will use a .env file for the ts-migrate-mongoose configuration.

The file should contain the following keys and their values:

MIGRATE_MONGO_URI - the URI of the Mongo database. It is the same as the database URL.
MIGRATE_MONGO_COLLECTION - the name of the collection (or table) which migrations should be saved in. The default value is migrations which is what is used in this project. ts-migrate-mongoose saves migrations to MongoDB.
MIGRATE_MIGRATIONS_PATH - the path to the folder for storing and reading migration scripts. The default value is ./migrations which is what is used in this project.

How to Seed User Data with ts-migrate-mongoose

We have been able to create a project and connect it successfully to a Mongo database. At this point, we want to seed user data into the database. We need to:

Create a users collection (or table)
Use ts-migrate-mongoose to create a migration script to seed data
Use ts-migrate-mongoose to run the migration to seed the user data into the database before the application starts

1. Create a users Collection using Mongoose

Mongoose schema can be used to create a user collection (or table). User documents (or records) will have the following fields (or columns): email, favouriteEmoji and yearOfBirth.

To create a Mongoose schema for the user collection, create a user.model.js file in the root of the project containing the following code snippet:

const mongoose = require("mongoose");

const userSchema = new mongoose.Schema(
  {
    email: {
      type: String,
      lowercase: true,
      required: true,
    },
    favouriteEmoji: {
      type: String,
      required: true,
    },
    yearOfBirth: {
      type: Number,
      required: true,
    },
  },
  {
    timestamps: true,
  }
);

module.exports.UserModel = mongoose.model("User", userSchema);

2. Create a Migration Script with ts-migrate-mongoose

ts-migrate-mongoose provides CLI commands which can be used to create migration scripts.

Running npx migrate create in the root folder of the project will create a script in the MIGRATE_MIGRATIONS_PATH folder (./migrations in our case). is the name we want the migration script file to have when it is created.

To create a migration script to seed user data, run:

npx migrate create seed-users

The command will create a file in the ./migrations folder with a name in the form --seed-users.ts. The file will have the following code snippet content:

// Import your models here

export async function up (): Promise<void> {
  // Write migration here
}

export async function down (): Promise<void> {
  // Write migration here
}

The up function is used to run the migration. The down function is used to reverse whatever the up function executes, if need be. In our case, we are trying to seed users into the database. The up function will contain code to seed users into the database and the down function will contain code to delete users created in the up function.

If the database is inspected with MongoDB Compass, the migrations collection will have a document that looks like this:

{
  "_id": ObjectId("6744740465519c3bd9c1a7d1"),
  "name": "seed-users",
  "state": "down",
  "createdAt": 2024-11-25T12:56:36.316+00:00,
  "updatedAt": 2024-11-25T12:56:36.316+00:00,
  "__v": 0
}

The state field of the migration document is set to down. After it runs successfully, it changes to up.

You can update the code in ./migrations/-seed-users.ts to the one in the snippet below:

require("dotenv").config() // load env variables
const db = require("../db.js")
const { UserModel } = require("../user.model.js");

const seedUsers = [
  { email: "john@email.com", favouriteEmoji: "🏃", yearOfBirth: 1997 },
  { email: "jane@email.com", favouriteEmoji: "🍏", yearOfBirth: 1998 },
];

export async function up (): Promise<void> {
  await db.connect(process.env.MONGO_URI)
  await UserModel.create(seedUsers);}

export async function down (): Promise<void> {
  await db.connect(process.env.MONGO_URI)
  await UserModel.delete({
    email: {
      $in: seedUsers.map((u) => u.email),
    },
  });
}

3. Run the Migration Before the Application Starts

ts-migrate-mongoose provides us with CLI commands to run the up and down function of migration scripts.

With npx migrate up we can run the up function of a specific script. With npx migrate up we can run the up function of all scripts in the ./migrations folder with a state of down in the database.

To run the migration before the application starts, we make use of npm scripts. npm scripts with a prefix of pre will run before a script without the pre prefix. For example, if there is a dev script and a predev script, whenever the dev script is run with npm run dev, the predev script will automatically run before the dev script is run.

We will use this feature of npm scripts to place the ts-migrate-mongoose command in a prestart script so that the migration will run before the start script.

Update the package.json file to have a prestart script that runs the ts-migrate-mongoose command for running the up function of migration scripts in the project.

  "scripts": {
    "prestart": "npx migrate up",
    "start": "node index.js"
  },

With this setup, when npm run start is executed to start the application, the prestart script will run to execute the migration using ts-migrate-mongoose and seed the database before the application starts.

You should have something similar to the snippet below after running npm run start:

Synchronizing database with file system migrations...
MongoDB connection successful
up: 1732543529744-seed-users.ts 
All migrations finished successfully

> ts-migrate-mongoose-starter-repo@1.0.0 start
> node index.js

MongoDB connection successful                      
Server listening on port 8000

Check out the seed-users branch of the repository to see the current status of the codebase at this point in the article.

How to Build an API Endpoint to Fetch Seeded Data

We can build an API endpoint to fetch the seeded users data in our database. In the server.js file, update the code to the one in the snippet below:

const { UserModel } = require("./user.model.js")

module.exports = async function (req, res) {
  const users = await UserModel.find({}) // fetch all the users in the database

  res.writeHead(200, { "Content-Type": "application/json" });
  return res.end(JSON.stringify({ // return a JSON representation of the fetched users data
    users: users.map((u) => ({
      email: u.email,
      favouriteEmoji: u.favouriteEmoji,
      yearOfBirth: u.yearOfBirth,
      createdAt: u.createdAt
    }))
  }, null, 2));
};

If we start the application and visit http://localhost:8000 using Postman or a browser, we get a JSON response similar to the one below:

{
  "users": [
    {
      "email": "john@email.com",
      "favouriteEmoji": "🏃",
      "yearOfBirth": 1997,
      "createdAt": "2024-11-25T14:18:55.416Z"
    },
    {
      "email": "jane@email.com",
      "favouriteEmoji": "🍏",
      "yearOfBirth": 1998,
      "createdAt": "2024-11-25T14:18:55.416Z"
    }
  ]
}

Notice that if the application is run again, the migration script does not run anymore because the state of the migration will now be up after it has run successfully.

Check out the fetch-users branch of the repository to see the current status of the codebase at this point in the article.

Conclusion

Migrations are useful when building applications and there is need to seed initial data for testing, seeding administrative users, updating database schema by adding or removing columns and updating the values of columns in many records at once.

ts-migrate-mongoose can help provide a framework for running migrations for your Node.js applications if you use Mongoose with MongoDB.

Orim Dominic Adah - freeCodeCamp.org

How to Create Dynamic Emails in Go with React Email

Table of Contents

What is React Email?

Go Templates

Go Template Delimiters

Create Dynamic Emails in Go with React Email

Set Up the Project

Set Up React Email

Create a React Email Template

Set Up Go Templates from HTML Files

Render the Dynamic Email in the Browser

Send and Test Email with go-mail and MailHog

Conclusion

How to Build a Voice-Powered AI Application with the Web Speech API

Table of Contents

Prerequisites

The Web Speech API

How to Use the Web Speech API in JavaScript for SEO

How the Application Works

How to Build the Application

Create the Backend Application with Node.js

Integrate an AI Assistant into the Node.js Application

Create the Frontend Application with Vite

Prompt AI with the Web Speech Recognition API

Test the Application Locally

Deploy the Backend Application with Google Cloud Run

Deploy the Frontend Application with Firebase

Connect the Deployed Applications

Conclusion

How to Create REST API Documentation in Node.js Using Scalar

Table of Contents

REST API Documentation Tools for Node.js

Swagger

Postman

ReDoc

zod-to-openapi and Scalar for REST API Documentation

How zod-to-openapi Works with Scalar

Benefits of Using zod-to-openapi and Scalar to Create REST API Documentation

OpenAPI Specification Support

Open Source and Free to Use

Better Documentation Experience

Guardrails with zod-to-openapi Methods

Avoid the Clumsiness of Comments and YAML Files

Accuracy and Auto-generation of Documentation

Developer-friendly UI

Markdown Support

How to Create the API Documentation

Set up the Project

How to Set Up zod-to-openapi

How to Generate the Documentation UI with Scalar

Document the Endpoints

How to Use Scalar with NestJS

How to Resolve Content Security Policy (CSP) Errors When Used with Helmet

Absence of AsyncAPI Documentation Feature

Conclusion

How to Build an In-Memory Rate Limiter in Next.js

Here’s What We’ll Cover:

Benefits of Rate Limiters

How Rate Limiters Work

Rate Limiting Algorithms

Fixed Window Algorithm

Sliding Window Algorithm

Token Bucket Algorithm

How to Build an In-Memory Rate Limiter

How The In-Memory Rate Limiter Works

The Request Handler

The Front End

How to Load Test the Rate Limiter for Resilience with Artillery

The Load Test Configuration

Run the Load Test

Review the Results

Conclusion

How Does the Morgan Express Middleware Library Work? Explained with Code Examples

Prerequisites

Table of Contents

What is an Express Middleware?

A Brief Overview of How Morgan Works

What is a Morgan Token?

What Happens When Morgan is Initialised?

How the `compile` Function Works