Technical writing - freeCodeCamp.org

How to Use Documentation as a Marketing Tool

Onyeanuna Prince — Fri, 20 Feb 2026 17:54:24 +0000

I was recently moved to the marketing team at my company, and that shift has made me reflect more deeply on the role documentation plays in our go-to-market strategy.

Before this move, we've had several product releases, and one requirement stayed constant across all of them: the documentation had to be ready at the time of release. This wasn’t because the product was unintuitive or unusable without docs. It was because the documentation was an integral part of the product experience. A release simply wasn’t considered complete without it.

At a glance, this pattern can be dismissed as operational hygiene. After all, good teams ship docs alongside code. But when you look closer, it points to something more fundamental about how users actually experience products today.

For many products, especially developer-facing ones, documentation is often the first real interaction users have with the product. Before they sign up, before they deploy anything, and sometimes even before they talk to sales, they read the docs. This is where they assess whether the product does what it claims, whether it fits their use case, and whether it is worth investing time and effort into.

In practice, documentation often carries more weight than landing pages or launch blogs. Marketing content may introduce the promise of the product, but documentation is where that promise is tested. It turns positioning into reality by showing how things actually work, what trade-offs exist, and how quickly a user can succeed.

Seen through this lens, documentation is not just a supporting artifact but a marketing tool in its own right. It communicates product value, builds trust at the moment of highest intent, and plays a direct role in adoption.

In this article, I want to unpack why documentation functions this way, and why teams should start treating it as a first-class part of their go-to-market strategy rather than an afterthought.

The Role of Documentation in a User's Journey
How to Build Trust at the Moment of Highest Intent
So, What Actually Builds Trust in Documentation?
Documentation and Marketing: A Partnership
Practical Implications: Treating Docs as Marketing
Conclusion

The Role of Documentation in a User's Journey

The customer journey does not begin when someone clicks “Buy now” or "Start free trial."

Long before that moment, users are already forming opinions about whether a product is credible, usable, and worth their time. In traditional marketing models, this early phase is described as awareness and evaluation. But for technical products, that evaluation phase looks very different from what classic marketing funnels suggest.

Instead of relying primarily on demos, sales conversations, or brand messaging, technical buyers tend to self-educate. Research from Gartner shows that modern B2B buyers spend a majority of their decision-making process researching independently before ever speaking to sales, and this behavior is even more pronounced among technical audiences who prefer primary sources over promotional material.

For developer tools, APIs, and infrastructure products, documentation becomes one of those primary sources. Users move from high-level marketing pages into documentation to answer concrete questions such as how the product works, what it integrates with, what assumptions it makes, and what it will realistically take to adopt. This transition from marketing to documentation is a natural progression in the evaluation process.

In the book The Product Is Docs, the Splunk documentation team describes this transition as needing to be “seamless, cohesive, and logical.” Their point, much more than consistency in tone or branding, is about continuity of understanding.

When users move from marketing content into documentation, they are testing whether the product narrative holds up under scrutiny. If the documentation is incomplete, confusing, or disconnected from what marketing promised, confidence drops quickly, not only in the docs, but in the product itself.

This idea aligns closely with broader research on content-driven buying behavior. Studies on developer experience consistently show that documentation quality is a key factor in product evaluation and adoption. A report by SlashData found that poor or unclear documentation is one of the top reasons developers abandon tools during evaluation, even when the underlying technology is sound.

What this highlights is that documentation does not sit at the end of the user journey, after a purchase has been made. It sits directly in the middle of the decision-making process. It acts as the bridge between curiosity and commitment. Marketing may introduce the problem space and position the solution, but documentation is where users validate whether the solution is real, usable, and aligned with their needs.

The Splunk team refers to this as creating an “integrated content experience,” where marketing and documentation work together to guide users from initial awareness through evaluation, purchase, and successful implementation.

How to Build Trust at the Moment of Highest Intent

When users arrive at your documentation, they’re no longer casually exploring. They’re actively evaluating whether your product fits their needs and whether it’s worth committing time, effort, or money to. This is what makes documentation a uniquely high-intent touchpoint in the user journey.

In marketing terms, high-intent moments are rare and valuable. They occur when users are close to making a decision and are seeking confirmation.

For technical products, documentation is often the primary surface where this confirmation happens. Research from Google on decision-making behavior shows that users rely heavily on “trust signals” at moments of intent, and for technical buyers, accuracy and depth of information matter more than persuasive language.

This is why documentation quality has an outsized impact on outcomes. When users encounter clear and practical documentation during evaluation, confidence increases. When they encounter gaps, inconsistencies, or ambiguity, doubt sets in immediately. Unlike marketing content, documentation doesn’t get the benefit of abstraction. It’s expected to be precise and complete.

Documentation is part of a continuous guide that “holds a customer’s hand” from evaluation through purchase and into successful usage. This framing is important because it highlights that trust isn’t built once and forgotten. It’s maintained across stages. Documentation inherits the trust marketing creates, but it must earn its own by demonstrating technical credibility and practical value.

This is the point where many products fail because marketing successfully drives interest, but documentation breaks the trust loop by failing to support the claims made earlier. When that happens, users don’t just lose confidence in the docs but also in the product and, by extension, the company behind it.

So, What Actually Builds Trust in Documentation?

Trust in documentation isn’t subjective. It’s shaped by specific, observable qualities that users quickly pick up on during evaluation.

Accuracy is the foundation. When examples work as described, and behavior matches documentation, users feel safe moving forward. When it doesn’t, you have a problem. Studies on developer experience consistently rank inaccurate documentation as one of the fastest ways to lose adoption, even when the underlying product is powerful.

Completeness is a signal of maturity. Documentation that covers core workflows, edge cases, and limitations tells users that the product has been thought through. Gaps, missing sections, or “coming soon” pages suggest instability or unfinished work. For evaluators, this raises red flags about long-term viability.

Another point is honesty, which plays an equally important role. Strong documentation doesn’t hide constraints or trade-offs. Instead, it acknowledges them clearly. Research in trust psychology shows that transparency, even about limitations, increases perceived credibility because it reduces uncertainty and surprises later.

Also, more recently updated docs reflect better on team health. Updated documentation signals active maintenance and ongoing investment. On the other hand, outdated docs suggest abandonment or stagnation. For technical buyers, this is often interpreted as a warning sign about support and future development.

Finally, usability determines whether trust can even form. Documentation that is difficult to navigate, poorly structured, or even hard to search fails before its content is evaluated. Nielsen Norman Group’s research on information-seeking behavior shows that users abandon content quickly when they cannot find answers with minimal effort, regardless of quality.

Together, these factors shape how users perceive not just the documentation, but the product and organization behind it.

Documentation and Marketing: A Partnership

In the book The Product is Docs, the authors observe that documentation teams and marketing teams "have more in common than you might think." Both are responsible for communicating product value to audiences, both create content that influences buying decisions, and both play crucial roles in the customer journey.

Yet these teams often operate separately, thereby creating disconnected experiences for users.

Marketing promises capabilities without understanding technical constraints, while documentation focuses on implementation details without connecting to broader use cases or business value.

The result of this is a jarring transition from marketing to product that undermines both efforts.

So, how can marketing help documentation?

Marketing teams bring a valuable perspective to documentation:

Customer insights: Marketing interacts directly with prospects and customers through demos, events, and demand generation. These interactions surface real questions and pain points that documentation should address.
Competitive intelligence: Understanding how competitors document their products can reveal opportunities for differentiation or improvement.
Strategic priorities: Knowing which features marketing will emphasize helps documentation teams focus their effort where it will have the most impact.
Target audience definition: Marketing's customer research and personas can inform documentation structure and examples.

And...how can good documentation help marketing?

Documentation teams bring equally valuable assets to the partnership:

Technical accuracy: Documentation teams can review marketing materials for technical correctness and help refine messaging to be both compelling and accurate.
Content leverage: Well-written documentation can be adapted into blog posts, white papers, and other marketing content.
User feedback: Documentation teams often receive direct feedback from users about what's confusing or what features resonate most.
Writing expertise: Technical writers can help develop clearer, more effective marketing content.

The Splunk team emphasizes that this collaboration should span the entire release cycle: "Before you write" (to align on priorities and naming), "As you write" (to validate approaches), and "After you write" (to ensure consistency and quality).

Figure 1: Embedding docs in the release cycle

Practical Implications: Treating Docs as Marketing

If documentation is indeed a marketing tool, what changes in how we approach it?

1. Documentation should ship with product launches

This is where my own experience began. Documentation can't be an afterthought that ships weeks after launch. If docs are part of how users evaluate and adopt the product, they need to be ready when the product is. This means involving documentation teams early in the development process, not at the end.

As the Splunk team notes in their discussion of Agile development: "There is no definition of ‘done’ without docs. Customer documentation is part of the working software." This principle should extend to marketing launches as well.

2. Invest in documentation quality and discoverability

If documentation influences buying decisions, it deserves the same attention to quality and user experience as marketing websites. This means:

Professional design and navigation
Fast search functionality
Clear information architecture
Mobile-friendly formatting
SEO optimization for relevant queries

Too often, documentation sites are neglected from a UX perspective while marketing pages receive constant refinement. This sends a message about priorities that users notice.

3. Create an integrated content experience

The transition from marketing to documentation should feel natural. This requires:

Consistent terminology: Features should be named the same way in marketing materials and documentation.
Aligned narratives: The use cases highlighted in marketing should have detailed implementation guides in the documentation.
Cross-linking: Marketing pages should link directly to relevant documentation sections, and vice versa.
Shared success metrics: Both teams should care about the same outcomes – not just awareness or signups, but successful implementation and adoption.

The Splunk team describes this as helping customers avoid feeling "disoriented or, worse, feel misled." Good documentation delivers on marketing's promises with specifics on how to achieve the outcomes that were advertised.

4. Measure documentation impact on conversion

If documentation is part of the marketing funnel, it should be measured as such. As a documentation team, you should track metrics like:

Documentation page views from prospective customers
Time spent in docs before conversion
Most-viewed pages during evaluation periods
Correlation between documentation engagement and trial-to-paid conversion
Customer feedback on documentation quality during the buying process

These metrics help demonstrate documentation's business impact and justify investment in quality improvements.

If you're curious about examples of docs that embody these strategies, then you might want to check out Twilio, Stripe, or, as mentioned earlier, the Splunk docs.

Why does all this matter now?

The role of documentation in driving adoption has always been important, but several trends are making it more critical:

First, as more companies adopt PLG strategies, the product experience, including documentation, becomes the primary sales vehicle. There's no sales team to answer questions or guide implementation. The docs must do that work.

Second, technical buyers increasingly want to evaluate products independently before engaging with sales. Documentation is often their primary evaluation tool.

We’re also seeing shorter sales cycles. When buying cycles compress, there's less time for demos and sales engineering. Documentation needs to answer questions immediately.

And finally, for developer tools and infrastructure products, individual contributors often drive adoption from the bottom up. These users rely heavily on documentation for their evaluation process.

In this environment, treating documentation as an operational necessity rather than a strategic asset is a competitive disadvantage. Companies that recognize documentation as a core part of their go-to-market strategy and invest accordingly see better conversion rates and stronger customer relationships.

Conclusion

Documentation is not just a post-purchase support resource. It's an active participant in the customer journey, influencing buying decisions and driving adoption.

For technical products, especially, documentation often carries more weight than traditional marketing materials.

This doesn't mean documentation should become marketing copy. It means recognizing that documentation performs a marketing function such as communicating value and building credibility, even while maintaining its technical accuracy and practical focus.

As the Splunk documentation team wisely notes, the goal is to create an integrated content experience where marketing and documentation work together to guide users from initial interest through successful implementation.

So, the requirement that documentation be ready at release time wasn't just operational hygiene. It was recognition that our product wasn't truly ready for market until users could both evaluate it and successfully use it. That's what makes documentation a marketing tool, not because it makes exaggerated claims, but because it delivers on the promise that marketing makes.

How to Use to Docker with Node.js: A Handbook for Developers

Oghenekparobo Stephen — Tue, 18 Nov 2025 22:18:07 +0000

In this handbook, you’ll learn what Docker is and why it’s a must-have skill for backend and full-stack developers. And, most importantly, you’ll learn how to use it in real-world projects from start to finish.

We will go far beyond the usual “Hello World” examples and walk you through containerizing a complete full-stack JavaScript application (Node.js + Express backend, HTML/CSS/JS frontend, MongoDB database, and Mongo Express admin UI).

You’ll learn about networking multiple containers, orchestrating everything with Docker Compose, building and versioning your own images, persisting data with volumes, and securely pushing your Images to a private AWS ECR repository for sharing and production deployment.

By the end, you’ll be able to eliminate “it works on my machine” issues, confidently manage multi-service applications, deploy consistent environments anywhere, and integrate Docker into your daily workflow and CI/CD pipelines like a pro.

Since Docker is such a key skill for backend developers, we’ll start by covering its basic concepts.

Prerequisites

This technical handbook is designed for developers who have some practical, hands-on experience in full-stack development. You should be comfortable deploying applications and have a basic understanding of CI/CD pipelines.

While we’ll cover Docker from the ground up, this guide is not for absolute beginner developers. I assume you have real-world development experience and want to level up your workflow with Docker.

Finally, a basic familiarity with AWS and general deployment concepts will also be useful, though you don’t need to be an expert. This handbook is ideal for developers looking to enhance their production-grade skills and confidently integrate Docker into their projects.

What is a Container?
Docker vs Virtual Machines
Docker Installation
Basic Docker Commands
Practice with JavaScript
How to Run the Mongo Container
How to Run the Mongo Express Container
How to Connect Node.js to MongoDB
How to Use Docker Compose
- Why Use Docker Compose?
How to Build Our Own Docker Image
How to Manage Your Containers
How to Create a Private Docker Repository
Assignment: Create and Push a New Version
Docker Volumes
Conclusion

What is a Container?

A container is a way to package an application together with everything it needs, including its dependencies, libraries, and configuration files.

Because containers are portable, they can be shared across teams and deployed on any machine without worrying about compatibility.

Where Do Containers Live?

Since containers are portable and can be shared across teams and systems, they need a place to live. That’s where container repositories come in – special storage locations for containers. Organizations can have private repositories for internal use, while public ones like Docker Hub let anyone browse and use shared containers.

If you visit the catalog page on Docker Hub, you will see a variety of container repositories, both official and community-made, from developers and teams like Redis, Jenkins, and many others.

In the past, when multiple developers worked on different projects, each had to manually install services on their own systems. Since different developers often use different operating systems like Linux, macOS, and Windows, the setup process was never the same. It took a lot of time, led to plenty of errors, and made setting up new environments a real headache, especially when you had to repeat it for multiple services.

Docker changed the game for developers and teams. Instead of manually installing every service and dependency, you can just run a single Docker command to start a container. Each container has its own isolated environment with everything it needs, so it runs the same on any machine, no matter if it’s Windows, macOS, or Linux. This makes collaboration smoother and eliminates all the bottlenecks that come from different setups, missing dependencies, or version mismatches.

In short, Docker is a platform that packages your app and its dependencies into a single, portable container, so it runs the same way everywhere.

Docker vs Virtual Machines

Docker and virtual machines (VMs) are both ways to run apps in a “virtual” environment, but they work differently. To understand the differences, it helps to know a bit about how computers run software.

A quick look at the layers:

Kernel: This is the part of the operating system that talks to your computer’s hardware, like the CPU, memory, and disk. Think of it as the middleman between your apps and your computer.
Application layer: This is where programs and apps run. It sits on top of the kernel and uses it to access hardware resources.

So, now let’s get into a bit more detail about Virtual Machines. A VM virtualizes the entire operating system, which means it comes with its own kernel and its own application layer. When you download a VM, you are basically getting a full OS inside your computer, often several gigabytes in size.

Because it has to boot its own OS, VMs start slowly. But VMs are very compatible, and can run on almost any host because they include everything they need.

Docker, on the other hand, only virtualizes the application layer, not the full OS. Containers share the host system’s kernel but include everything the app needs, dependencies, libraries, and configuration.

Docker images are small, often just a few megabytes. Containers start almost instantly because they don’t boot a full OS. A Docker container can run anywhere Docker is installed, no matter what operating system your computer uses.

In simple terms, to summarize:

A VM is like running a whole computer inside your computer – big, heavy, and slow.
A Docker container is like a self-contained app package – small, fast, and portable.

Here’s a quick comparison:

Feature	Virtual Machine	Docker Container
Size	GBs (large)	MBs (small)
Startup Speed	Slow	Fast
OS Layer	Full OS + kernel	Shares host kernel
Portability	Runs on compatible host	Runs anywhere Docker is installed

Docker Installation

Alright, now that you know what Docker is, let’s get it running on your own machine.

Docker works on Windows, macOS, and Linux, but each system has slightly different steps. The official Docker documentation has clear instructions for all operating systems under Docker Docs: Install Docker.

If you are more of a visual learner, this YouTube video walks you through installing Docker on Windows and Linux step by step: Watch here.

Here is a simple roadmap:

First, check your system requirements. Docker won’t run on every computer, so make sure your OS version is supported (the official docs have a checklist).

Windows and macOS users:
- Newer systems: Download and install Docker Desktop. It’s the easiest way to get started.
- Older systems: If your computer doesn’t support Docker Desktop (for example, missing Hyper-V or older OS versions), you can use Docker Toolbox. Toolbox installs Docker using a lightweight virtual machine, so you can still run containers even on older machines.
Linux users: You will usually install Docker through your package manager (apt for Ubuntu/Debian, yum for CentOS/Fedora, etc.). The official docs show the commands for your distro.

Then verify your installation: Open a terminal or command prompt and type:

docker --version

If you see the Docker version displayed, congratulations! Docker is ready to go.

Once Docker is installed, you’ll be ready to start running containers, pulling images, and experimenting with your apps in a safe, isolated environment.

Tip for beginners:

If you’re on an older machine and using Docker Toolbox, commands are mostly the same, but you will run them inside the Docker Quickstart Terminal, which sets up the virtual machine for you.

Basic Docker Commands

So far, we have been throwing around terms like images and containers, sometimes even interchangeably. But there is an important difference:

Docker image: Think of an image as a blueprint or a package. It contains everything your app needs: the code, libraries, dependencies, and configuration, but it’s not running yet.
Docker container: A container is a running instance of an image. When you start a container, Docker takes the image and runs it in its own isolated environment.

A helpful way to remember it is this: the image is the recipe, while the container is the cake**.** You can have one recipe (image) and make multiple cakes (containers) from it.

Important note: Docker Hub stores images, not containers. So when you pull something from Docker Hub, you’re downloading an image. For example:

docker pull redis

Here’s what you’ll see:

This command downloads the Redis image to your machine. Once the download is complete, you can see all the images you have locally with:

docker images

From there, you can start a container from an image whenever you need it:

docker run -d --name my-redis redis

This command starts a container, my-redis, from the redis image you just pulled.

docker run tells Docker to start a new container from an image.
-d stands for “detached mode.” It means the container runs in the background so you can keep using your terminal.
--name my-redis gives your container a friendly name (my-redis) instead of letting Docker assign a random one. It makes it easier to manage later.
redis is the image you are using to start the container.

To see all containers that are currently running, you can use:

docker ps

This will list containers with details like:

Container ID
Name
Status (running or stopped)
The image it’s running from

If you want to see all containers, even ones that aren’t running, you can add the -a flag:

docker ps -a

How to Specify a Version of an Image:

By default, Docker pulls the latest version of an image. But sometimes you might need a specific version. You can do this using a colon (:) followed by the version tag. For example:

docker pull redis:7.2
docker run -d --name my-redis redis:7.2

To know which versions are available, you can visit Docker Hub or check the image tags online. Also, running docker images on your machine will show you all downloaded images and their versions.

How to Stop, Start, and Remove a Container

If you want to stop a running container, run this:

docker stop my-redis

To start it again:

docker start my-redis

You can also remove a container if you no longer need it:

docker rm my-redis

How to Restart a Container

You can restart a container using its container ID (or name) if something crashes, needs a refresh, or you just want to apply changes.

For example:

docker ps
CONTAINER ID   IMAGE     COMMAND                  CREATED         STATUS         PORTS      NAMES
c002bed0ae9a   redis     "docker-entrypoint.s…"   3 minutes ago   Up 3 minutes   6379/tcp   my-redis

Restart it like this:

docker restart c002bed0ae9a

or by name:

docker restart my-redis

Other handy ways:

Stop then start

  docker stop c002bed0ae9a
  docker start c002bed0ae9a

Start with logs

  docker start c002bed0ae9a && docker logs -f c002bed0ae9a

How to Run Multiple Redis Containers and Understanding Ports

Right now, you have a Redis container running:

docker ps

It shows something like this:

CONTAINER ID   IMAGE     COMMAND                  STATUS          PORTS      NAMES
c002bed0ae9a   redis     "docker-entrypoint.s…"   Up 20 minutes   6379/tcp   my-redis

Notice the PORTS column: 6379/tcp. This means the container is running Redis on its internal port 6379. By default, this port is inside the container and is not automatically exposed to your computer (the host). Docker maps it only if you specify it.

Trying to Run Another Redis Container on the Same Port

If you try:

docker run -d --name my-redis2 redis:7.4.7-alpine

It will fail to map the host port 6379 because the first container is already using it. This is where port binding comes in.

What is Port Binding?

Port binding (also called port mapping) is the mechanism Docker uses to connect a port inside a container to a port on your host machine (your laptop/desktop/server).

Without port binding, any service running inside a container is completely isolated: it can listen on its internal ports (for example, Redis on 6379, a Node.js app on 3000, MongoDB on 27017), but nothing outside the container, including your browser, another app on your computer, or even another container on a different network, can reach it.

Container Port: The port inside the container where the app is running (Redis defaults to 6379).
Host Port: The port on your computer that you want to use to access that container.

Docker lets you map a container port to a different host port using the -p flag.

Running a Second Redis Container on a Different Host Port

docker run -d --name my-redis2 -p 6380:6379 redis:7.4.7-alpine

-p 6380:6379 maps host port 6380 to container port 6379.

Now you can connect to Redis in the second container using localhost:6380.
Inside the container, Redis still runs on port 6379.

Check both containers:

docker ps

Output will look like this:

CONTAINER ID   IMAGE     STATUS          PORTS             NAMES
c002bed0ae9a   redis     Up 20 minutes   6379/tcp          my-redis
d123abcd5678   redis     Up 1 minute     0.0.0.0:6380->6379/tcp   my-redis2

The first container is running internally on 6379 (host port not exposed), while the second container is mapped so host port 6380 forwards traffic to container port 6379.

Think of each container as a room with a phone line (container port).

You want to call that room from the outside (host).
You can’t use the same external phone line for two rooms at the same time.
With port binding, you assign a different external line for each room, even if the internal phone number is the same.

Why Port Binding Exists

Avoid port conflicts on the host: Only one process on your computer can use a given port at a time. If you already have one Redis container using host port 6379, a second container cannot also bind to the same host port. Port binding lets you run many identical containers side-by-side by mapping each one to a different host port (6379 → 6380, 6381, etc.).
Access containerised services from your host: Your browser, Postman, MongoDB Compass, redis-cli, curl, etc., all run on the host. Without -p, they have no way to talk to services inside containers.
Selective exposure: You don’t have to expose every port a container uses. Only map the ports you actually need externally, keeping the rest private and secure.

It also gives you more flexibility in development and production. In development, you might map container 3000 to host 3000. But in production (for example, behind a reverse proxy), you might map container 3000 to host 80 or 443, or not expose it at all and let another container talk to it over Docker’s internal network.

How to Explore a Container

To explore a container, run:

docker exec -it my-redis2 /bin/sh

docker exec runs a command in the container.
-it interactive terminal (lets you type and see output).
/bin/sh starts a shell inside the container.

Once inside, your prompt changes to something like:

/data #

Now you can list files, navigate directories, or run programs, all inside the container, without affecting your host machine.

`docker run` vs `docker start`

We have been using docker run and docker start throughout this article, but here’s why the difference is important:

Avoid accidental duplicates: Using docker run every time creates a new container. If you just want to restart something you already set up, docker start is faster and safer.
Maintain configuration: docker start preserves the container’s original settings, ports, volumes, and names so you don’t risk breaking anything by changing options.
Work efficiently with multiple containers: When running multiple services or different versions of the same app, knowing when to run vs start helps you manage resources, avoid port conflicts, and keep your workflow smooth.
Speed up your workflow: Starting existing containers is almost instant, while creating a new one takes slightly longer.

Bottom line docker run = create something new, while docker start = resume what you already have.

Practice with JavaScript

Now that we have covered the core Docker concepts, let’s put them into action. In this section, we’ll containerize a simple JavaScript project that consists of:

A frontend: Built with HTML, CSS, and JavaScript
A backend: A simple Node.js server (server.js)
A database: A MongoDB instance pulled directly from Docker Hub
A UI for MongoDB: Using Mongo Express to visualize and manage our database

This example demonstrates how Docker can manage multiple components of an application, including code, dependencies, and services in isolated, consistent environments.

You can pull the starter project from GitHub here.

Or clone it directly using your terminal:

git clone https://github.com/Oghenekparobo/docker_tut_js.git
cd docker_tut_js

This contains the basic HTML and JavaScript files along with the Node.js backend.

Next, we will prepare to set up our database. Head over to Docker Hub and type “mongo” in the search box. You will see the official MongoDB image published by Docker.

How to Pull the MongoDB Image

Now that you have explored the official MongoDB image on Docker Hub, let’s actually pull it into your local environment.

Open your terminal, navigate to your project directory (for example, docker_tut_js), and run:

docker pull mongo

This command tells Docker to download the latest version of the MongoDB image from Docker Hub.

You will see output similar to this:

Using default tag: latest
latest: Pulling from library/mongo
b8a35db46e38: Already exists 
a637dbfff7e5: Pull complete 
0c9047ace63c: Pull complete 
02cd4cf70021: Pull complete 
dfb5d357a025: Pull complete 
007bf0024f67: Pull complete 
67fd8af3998d: Pull complete 
d702312e8109: Pull complete 
Digest: sha256:7d1a1a613b41523172dc2b1b02c706bc56cee64144ccd6205b1b38703c85bf61
Status: Downloaded newer image for mongo:latest
docker.io/library/mongo:latest

Here’s what’s happening:

“Using default tag: latest”: Docker pulls the most recent version of MongoDB since no specific version was provided.
“Pulling from library/mongo”: It’s downloading from Docker’s official image library.
“Pull complete”: Each line represents a layer of the image being successfully downloaded.
“Downloaded newer image for mongo:latest”: Confirms that the MongoDB image is now stored locally on your system.

You can confirm that it’s available by running:

docker images

You should see mongo listed in the repository column.

How to Pull the Mongo Express Image

Now that the MongoDB image is ready, let’s pull the Mongo Express image.

Mongo Express is a lightweight web-based interface that lets you view and manage your MongoDB collections through a browser, similar to how phpMyAdmin works for MySQL.

Open your terminal (still in your project directory) and run:

docker pull mongo-express

You’ll see output similar to this:

Using default tag: latest
latest: Pulling from library/mongo-express
b8a35db46e38: Already exists
a637dbfff7e5: Pull complete
4e0e0977e9c3: Pull complete
02cd4cf70021: Pull complete
Digest: sha256:3d6dbac587ad91d0e2eab83f09a5b31a1c8f9d91a8825ddaa6c7453c25cb4812
Status: Downloaded newer image for mongo-express:latest
docker.io/library/mongo-express:latest

Here’s what this means:

docker pull mongo-express downloads the official Mongo Express image from Docker Hub.
Each “Pull complete” line represents a successfully downloaded layer of the image.
mongo-express:latest confirms that the latest version is now stored locally.

To verify that both images are available, run:

docker images

You should see mongo and mongo-express listed in the output.

Now that both images are downloaded, the next step is to run the containers to make sure MongoDB is up and accessible, and then connect it to Mongo Express so we can manage it through the browser.

Before we do that, let’s briefly look at how these two containers will communicate.

Docker Network

When MongoDB and Mongo Express run in separate containers, they need a way to talk to each other. Docker handles this using something called a Docker Network, a virtual bridge that lets containers communicate securely without exposing internal ports to the outside world.

When you run containers in Docker, it automatically creates an isolated network for them. Think of it like a private space where your containers can talk to each other safely without exposing everything to the outside world.

For example, if our MongoDB container and Mongo Express container are on the same Docker network, they can communicate just by using their container names (like mongo or mongo-express). You don’t need to use localhost or port numbers, as Docker handles that part internally.

But anything outside the Docker network (like your host machine or a Node.js app) connects through the exposed ports.

So later, when we package our entire application, the Node.js backend, MongoDB, Mongo Express, and even the frontend (index.html) into Docker, all these containers will interact smoothly through the Docker network. The browser on your computer will then connect to your Node.js app using the host address and port we have exposed.

By default, Docker already provides a few built-in networks. You can see them by running:

docker network ls

You will get something like this:

NETWORK ID     NAME      DRIVER    SCOPE
712a7144f1a0   bridge    bridge    local
4ae27eedea5b   host      host      local
4806000201ce   none      null      local

These are automatically created by Docker. You don’t need to worry too much about them right now – we will just focus on creating our own custom network.

For our setup, we will create a separate network that both MongoDB and Mongo Express can share. Let’s call it mongo-network:

docker network create mongo-network

How to Run the Mongo Container

To make sure our MongoDB and Mongo Express containers can communicate, we need to run them inside the same Docker network. That’s why we created mongo-network earlier.

Let’s start with MongoDB. Remember, the docker run command is used to start a container from an image. In this case, we will run the official MongoDB image and attach it to our network.

We will also expose the default MongoDB port 27017 so it’s accessible from outside the container, and set up environment variables for the root username and password.

Here is the command:

docker run -p 27017:27017 -d \
  -e MONGO_INITDB_ROOT_USERNAME=admin \
  -e MONGO_INITDB_ROOT_PASSWORD=password \
  --name mongo \
  --network mongo-network \
  mongo

Here’s what each part does:

-p 27017:27017 maps the container’s MongoDB port to your host machine.
-d runs the container in detached mode (in the background).
-e sets environment variables for the database’s root credentials.
--name mongo gives the container a custom name for easier reference.
--network mongo-network connects the container to the network we created.

Once it runs successfully, your MongoDB instance will be up and running inside the Docker network, ready for other containers like Mongo Express to connect to it.

After creating your MongoDB container, you can easily check if it’s running and healthy.

First, run docker ps to see all active containers. You should see your MongoDB container (mongo) listed with its port 27017 exposed. To get more details about what’s happening inside the container, you can check its logs using docker logs mongo or, if you prefer, by using the container ID (for example: docker logs 7abb38175ae28). The logs will show startup messages from MongoDB, and you should look for lines indicating that the database started successfully and is ready to accept connections.

This is a quick way to verify that everything is working correctly before connecting other services, like Mongo Express, to it.

docker ps

This will list all running containers. You should see your MongoDB container (mongo) with its port 27017 exposed.

docker logs mongo or the id of the container e.g docker logs 7abb38175ae283429354609866c8d97521f37b535c475ae448295f8fc0ed947f

This will show startup messages. Look for lines indicating MongoDB started successfully and is ready to accept connections.

How to Run the Mongo Express Container

Now that MongoDB is up and running, we can run Mongo Express, which is a web-based interface to manage and view your MongoDB databases. We will connect it to the same network (mongo-network) so it can communicate with MongoDB.

Here’s the command:

docker run -d \
  -e ME_CONFIG_MONGODB_ADMINUSERNAME=admin \
  -e ME_CONFIG_MONGODB_ADMINPASSWORD=password \
  -e ME_CONFIG_MONGODB_SERVER=mongo \
  --name mongo-express \
  --network mongo-network \
  -p 8081:8081 \
  mongo-express

Here’s what each part does:

-d runs the container in detached mode (in the background).
-e ME_CONFIG_MONGODB_ADMINUSERNAME=admin sets the MongoDB admin username for Mongo Express to use.
-e ME_CONFIG_MONGODB_ADMINPASSWORD=password sets the corresponding MongoDB password.
-e ME_CONFIG_MONGODB_SERVER=mongo tells Mongo Express which MongoDB server to connect to. Here we use the container name mongo because both containers are on the same network.
--name mongo-express gives the container a friendly name for easier reference.
--network mongo-network connects the container to the same Docker network as MongoDB so they can talk to each other.
-p 8081:8081 exposes the Mongo Express web interface on port 8081 of your host machine.
mongo-express the name of the Docker image we’re running.

Once the container is running, you can open your browser and visit http://localhost:8081 to access Mongo Express and interact with your MongoDB instance.

For more details about the available environment variables and options, you can check the official Docker Hub page for Mongo Express here.

Before opening your browser at http://localhost:8081, it’s a good idea to check if the Mongo Express container is running properly. You can do this by viewing its logs:

docker logs 
# or
docker logs mongo-express

You should see output similar to this:

Waiting for mongo:27017...
No custom config.js found, loading config.default.js
Welcome to mongo-express 1.0.2
------------------------
Mongo Express server listening at http://0.0.0.0:8081
Server is open to allow connections from anyone (0.0.0.0)
basicAuth credentials are "admin:pass", it is recommended you change this in your config.js!

This confirms that Mongo Express is up and running and ready to connect to your MongoDB instance.

Take note of the basicAuth credentials shown in the logs (admin:pass). If these credentials are present, you’ll need to use them when accessing Mongo Express from your browser. Later, you can change them in a custom config.js file for better security.

Once everything looks good in the logs, you can safely visit http://localhost:8081 to access the Mongo Express interface.

If your browser asks for a username and password when accessing Mongo Express, use the basicAuth credentials shown in the container logs:

Username: admin
Password: pass

These are the default credentials, and it’s strongly recommended to change them later in a custom config.js file for better security.

When you open Mongo Express, you will notice some default databases already created. For this project, we will create a new database called todos. Once it’s created, your Node.js application can connect to this database to store and retrieve data.

How to Connect Node.js to MongoDB

You already have MongoDB running inside a Docker container (mongo). The container exposes the default MongoDB port 27017 to the host, so any process on your laptop/desktop can reach it via localhost:27017.

Important: The Node.js app is outside Docker (it’s just a regular node server.js process you start from your terminal).

Because the app is external, we must use localhost (or 127.0.0.1) as the host name – not the container name mongo.

Once we later containerise the Node.js app and put it on the same Docker network, we’ll switch the host to mongo. For now, keep it localhost.

Node.js Backend

Here’s a version of our server.js using MongoDB:

const express = require("express");
const multer = require("multer");
const path = require("path");
const fs = require("fs");
const { MongoClient, ObjectId } = require("mongodb");

const app = express();
const PORT = 3000;

// Host = localhost  →  talks to the MongoDB container via the exposed port
// Port = 27017      →  default MongoDB port
// User / Pass       →  admin / password (the credentials you gave the container)
const mongoUrl = "mongodb://admin:password@localhost:27017";
const dbName = "todos";
let db;

MongoClient.connect(mongoUrl)
  .then((client) => {
    db = client.db(dbName);
    console.log("Connected to MongoDB →", dbName);
  })
  .catch((err) => console.error("MongoDB connection error:", err));

const uploadDir = path.join(__dirname, "uploads");
if (!fs.existsSync(uploadDir)) fs.mkdirSync(uploadDir);

const storage = multer.diskStorage({
  destination: (req, file, cb) => cb(null, uploadDir),
  filename: (req, file, cb) => {
    const unique = Date.now() + "-" + Math.round(Math.random() * 1e9);
    cb(null, "photo-" + unique + path.extname(file.originalname));
  },
});
const upload = multer({ storage });

app.use(express.static(__dirname));
app.use("/uploads", express.static(uploadDir));
app.use(express.json());
app.use(express.urlencoded({ extended: true }));

app.get("/todos", async (req, res) => {
  const todos = await db.collection("todos").find().toArray();
  res.json(todos);
});

app.post("/todos", upload.single("photo"), async (req, res) => {
  const text = req.body.text?.trim();
  if (!text) return res.status(400).json({ error: "Text required" });

  const todo = {
    text,
    image: req.file ? `/uploads/${req.file.filename}` : null,
    createdAt: new Date(),
  };

  const result = await db.collection("todos").insertOne(todo);
  todo._id = result.insertedId;
  res.json(todo);
});

// Start server
app.listen(PORT, () => {
  console.log(`Server → http://localhost:${PORT}`);
});

Frontend

index.html:

html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Todo + Imagetitle>
    <style>
      body {
        font-family: sans-serif;
        margin: 2rem;
        max-width: 800px;
      }
      .todo {
        border: 1px solid #ccc;
        padding: 1rem;
        margin-bottom: 1rem;
        border-radius: 8px;
      }
      .todo img {
        max-height: 150px;
        margin-top: 0.5rem;
      }
      .error {
        color: red;
      }
      input[type="text"] {
        width: 100%;
        padding: 0.5rem;
        margin-bottom: 0.5rem;
      }
      #preview {
        max-width: 300px;
        margin-top: 0.5rem;
        display: none;
      }
    style>
  head>
  <body>
    <h1>Todo List with Imagesh1>

    <div id="addForm">
      <input type="text" id="textInput" placeholder="What needs to be done?" />
      <input type="file" id="imageInput" accept="image/*" />
      <img id="preview" alt="preview" />
      <button id="addBtn">Add Todobutton>
      <p id="status">p>
    div>

    <h2>Todosh2>
    <div id="todos">div>

    <script>
      const $ = document.querySelector.bind(document);

      const textInput = $("#textInput");
      const imageInput = $("#imageInput");
      const preview = $("#preview");
      const addBtn = $("#addBtn");
      const status = $("#status");
      const todosDiv = $("#todos");

      imageInput.addEventListener("change", () => {
        const file = imageInput.files[0];
        if (!file) {
          preview.style.display = "none";
          return;
        }
        const reader = new FileReader();
        reader.onload = (e) => {
          preview.src = e.target.result;
          preview.style.display = "block";
        };
        reader.readAsDataURL(file);
      });

      addBtn.addEventListener("click", async () => {
        const text = textInput.value.trim();
        if (!text) {
          status.textContent = "Please enter a todo text.";
          status.className = "error";
          return;
        }

        const form = new FormData();
        form.append("text", text);
        if (imageInput.files[0]) form.append("photo", imageInput.files[0]);

        try {
          const res = await fetch("/todos", { method: "POST", body: form });
          const data = await res.json();
          if (!res.ok) throw new Error(data.error || "failed");
          status.textContent = "Todo added!";
          status.className = "";
          textInput.value = "";
          imageInput.value = "";
          preview.style.display = "none";
          loadTodos(); // refresh list
        } catch (err) {
          status.textContent = "Error: " + err.message;
          status.className = "error";
        }
      });

      async function loadTodos() {
        const res = await fetch("/todos");
        const todos = await res.json();
        todosDiv.innerHTML = "";
        todos.forEach((t) => {
          const div = document.createElement("div");
          div.className = "todo";
          div.innerHTML = `${escapeHtml(t.text)}`;
          if (t.image) {
            div.innerHTML += `
${t.image}" alt="todo image">`;
          }
          todosDiv.appendChild(div);
        });
      }

      function escapeHtml(s) {
        const div = document.createElement("div");
        div.textContent = s;
        return div.innerHTML;
      }

      loadTodos();
    script>
  body>
html>

Now your Node.js app can connect to the MongoDB container running in Docker. Since the app is running outside Docker for now, it connects through localhost:27017 using the credentials you set (admin / password).

Once connected, your Node.js backend stores and retrieves todos directly from the todos database in MongoDB, replacing the in-memory array. Later, if you containerize the Node.js app and put it on the same Docker network as MongoDB, you can switch the host from localhost to the container name mongo. we are getting there

You can get the full backend and frontend code ready to run and tweak it for your setup here: GitHub repo.

How to Use Docker Compose

So we now have our Node.js app connected to MongoDB and Mongo Express, both running inside containers. We’ve created the network, started the containers, and everything is talking to each other perfectly.

But let’s be honest: typing out all those long docker run commands every time can get tedious. You probably want a simpler, cleaner way to spin everything up with just one command. That’s where Docker Compose comes in.

Docker Compose is a tool that lets you define and run multi-container applications with a single command. Instead of manually running multiple docker run commands, you describe your setup in a simple docker-compose.yml file, specifying each service (like your Node.js app, MongoDB, and Mongo Express), their configurations, environment variables, and shared networks.

Basically, it lets you manage multiple containers as one project, easy to start, stop, and maintain with a single file and a single command.

The standard naming convention is docker-compose.yml (or docker-compose.yaml. Both work, but .yml is more common).

Docker automatically detects it when you run:

docker compose up

So yeah, stick with docker-compose.yml for convention.

Now, to run the containers for MongoDB and Mongo Express, we can use the following two commands, respectively:

# MongoDB container
docker run -p 27017:27017 -d \
  -e MONGO_INITDB_ROOT_USERNAME=admin \
  -e MONGO_INITDB_ROOT_PASSWORD=password \
  --name mongo \
  --network mongo-network \
  mongo

# Mongo Express container
docker run -d \
  -e ME_CONFIG_MONGODB_ADMINUSERNAME=admin \
  -e ME_CONFIG_MONGODB_ADMINPASSWORD=password \
  -e ME_CONFIG_MONGODB_SERVER=mongo \
  --name mongo-express \
  --network mongo-network \
  -p 8081:8081 \
  mongo-express

Now, instead of typing these long commands every time, we will combine them and run everything at once using a Docker Compose file.

The docker-compose.yml file will be located at the root of our Node.js project.

Here’s how our docker-compose.yml file looks:

version: "3.8"

services:
  mongodb:
    image: mongo
    container_name: mongo
    ports:
      - "27017:27017"
    environment:
      MONGO_INITDB_ROOT_USERNAME: admin
      MONGO_INITDB_ROOT_PASSWORD: password

  mongo-express:
    image: mongo-express
    container_name: mongo-express
    ports:
      - "8081:8081"
    environment:
      ME_CONFIG_MONGODB_ADMINUSERNAME: admin
      ME_CONFIG_MONGODB_ADMINPASSWORD: password
      ME_CONFIG_MONGODB_SERVER: mongodb
    depends_on:
      - mongodb

Let’s break down what’s going on here:

version: "3.8": This defines the Compose file version. Each version has slightly different syntax rules and features. Version 3.8 is modern and works with the latest Docker Engine.
services:: All the containers we want to run are defined here. In our case, two services: mongodb and mongo-express.

MongoDB service:

image: mongo pulls the official MongoDB image from Docker Hub.
container_name: mongo gives the container a friendly name.
ports: "27017:27017" exposes MongoDB’s default port to our host, so Node.js or other apps can connect.
environment: sets up the root username and password for MongoDB.

Mongo Express service:

image: mongo-express is the official Mongo Express image.
container_name: mongo-express is a friendly name for easier reference.
ports: "8081:8081" exposes Mongo Express web interface on host port 8081.
environment: let’s Mongo Express know how to connect to MongoDB (username, password, host).
depends_on: - mongodb ensures MongoDB starts first, so Mongo Express can connect immediately.

Why Use Docker Compose?

Single command: Instead of running multiple long docker run commands, just run:

docker compose up -d

Automatic networking: Compose creates a default network so services can communicate using their service names (mongodb In our case)
Easier maintenance: You can stop, start, or rebuild all services with simple commands.

Before we run our new docker-compose.yml, it’s important to make sure no conflicting containers are running. Remember, we already had MongoDB and Mongo Express running from the previous docker run commands.

To avoid conflicts (like ports already in use), we should stop and remove any running containers first.

Here’s how:

# List all running containers
docker ps

# Stop a specific container (replace  with mongo or mongo-express)
docker stop mongo
docker stop mongo-express

# Remove the stopped containers
docker rm mongo
docker rm mongo-express

# Optional: stop and remove all running containers at once
docker stop $(docker ps -q)
docker rm $(docker ps -a -q)

docker ps shows currently running containers.
docker stop stops a container gracefully.
docker rm removes the container from Docker.
docker stop $(docker ps -q) stops all running containers.
docker rm $(docker ps -a -q) removes all containers (running or stopped).

Once all previous containers are stopped and removed, we’re ready to run our Docker Compose setup safely without conflicts.

Now that all previous containers are stopped, we can start MongoDB and Mongo Express together using our docker-compose.yml file.

From the root of your Node.js project (where the docker-compose.yml file is located), run:

docker compose up -d

Here’s what this does:

docker compose tells Docker to use Compose.
up builds (if needed) and starts all the services defined in the Compose file.
-d runs the containers in detached mode, meaning they run in the background.

After running this command, Docker will start both MongoDB and Mongo Express, connect them on the same internal network, and expose the ports we defined (27017 for MongoDB and 8081 for Mongo Express).

If everything worked correctly, after running:

docker compose up -d

You should see output similar to this:

[+] Running 3/3
 ✔ Network docker_tut_default  Created                                                                                               0.0s 
 ✔ Container mongo             Started                                                                                               0.6s 
 ✔ Container mongo-express     Started                                                                                               0.8s 
stephenjohnson@Oghenekparobo docker_tut %

What this means:

Network docker_tut_default Created: Docker Compose automatically creates a network for your services so they can communicate with each other.
Container mongo Started: Your MongoDB container is running.
Container mongo-express Started: Your Mongo Express container is running.

You can confirm that the containers are running by using:

docker ps

This will list all active containers. You should see both mongo and mongo-express with their respective ports (27017 for MongoDB and 8081 for Mongo Express) exposed.

To access Mongo Express, open your browser and go to http://localhost:8081 to interact with MongoDB through the web interface.
To access MongoDB, your Node.js app can connect to MongoDB at localhost:27017 using the credentials you set in the Compose file.

Compared to running long docker run commands for each container, using Docker Compose is easier because:

Starts multiple containers with one command.
Automatically sets up networking between containers.
Makes it easier to stop, remove, or rebuild containers later.

In short, Docker Compose simplifies and organizes everything, making it much easier to manage your development environment.

At this stage, it’s important to know that any data you add to MongoDB is temporary. If you stop or remove your containers and then start them again, you will notice that all your data is gone. This happens because data inside a container isn’t persistent by default.

Don’t worry, this is expected, and we’ll cover how to make data persistent later in the tutorial when we introduce Docker volumes. For now, just be aware that each time you restart your containers, MongoDB starts fresh with no previous data.

You can get a full sample, including the Dockerfile and the docker‑compose file, here.

How to Build Our Own Docker Image

Now that we have tested our Node.js application locally and seen it working perfectly with MongoDB and Mongo Express, the next step is preparing it for deployment.

Running the app directly on our machine works fine for development, but it’s not practical when we want to move it to another environment or server. By creating a Docker image, we can package the application together with all its dependencies, configuration, and environment setup into a single, portable unit. This image can then run anywhere Docker is installed, ensuring our app works the same way across development, testing, and production.

In short, building a Docker image is how we containerize our app and make it deployment-ready.

In order to containerize our Todo app, we need a Dockerfile. A Dockerfile is essentially a blueprint that tells Docker how to build an image for our application. It defines the base environment, copies our application code, installs dependencies, and specifies how the app should start. With this blueprint, Docker can create a consistent image that behaves the same way on any machine, making our Node.js app fully portable and ready for deployment.

In our Dockerfile, notice the capital D, which is the standard naming convention. Place this file in the root directory of your Node.js project. In simple projects like ours, our main app file (like server.js or index.js) is usually in the root too, along with package.json. Docker will use this file as a blueprint to build a container image of your application.

If your main app file is inside a subfolder, that’s fine too. Just make sure the Dockerfile’s COPY and CMD commands point to the correct location. The important thing is that the Dockerfile lives in the root so Docker knows where to start building your app.

Here’s how the contents of our Dockerfile look:

# Use full Node 18 (Debian-based)
FROM node:18

# Set environment variables
ENV MONGO_DB_USERNAME=admin \
    MONGO_DB_PASSWORD=password

# Set working directory
WORKDIR /home/app

# Copy package files
COPY package*.json ./

# Install dependencies
RUN npm install

# Copy source code
COPY . .

# Expose port
EXPOSE 3000

# Start the app
CMD ["node", "server.js"]

Let’s see what’s going on here:

FROM node:13-alpine is the base image for our container. It comes with Node.js installed and is very lightweight, keeping the image small.
ENV MONGO_DB_USERNAME=admin \ MONGO_DB_PASSWORD=password sets environment variables inside the container so the Node.js app can connect to MongoDB.
WORKDIR /home/app sets the working directory inside the container. All subsequent commands like COPY or RUN will run relative to this folder.
COPY . . copies all files from your local project into the container’s working directory. This includes your server.js, package.json, and any other files needed to run the app.
RUN npm install installs all the Node.js dependencies listed in package.json inside the container.
EXPOSE 3000 tells Docker that the container will listen on port 3000, which is the port our Node.js app runs on.
CMD ["node", "server.js"] defines the command that runs when the container starts, which launches our Node.js server.

By placing this Dockerfile in the root of your project, Docker knows exactly where to find your app’s files and dependencies. When we build the image, it packages everything inside a portable container that can run anywhere Docker is installed, making deployment straightforward and consistent.

Now that we have our Dockerfile ready, the next step is to build the Docker image for our Node.js app.

To build the image, open your terminal, make sure you are in the root directory of your project (where the Dockerfile is), and run:

docker build -t todo-app:1.0 .

todo-app is the name of your image.
:1.0 is the version tag (you can use any versioning scheme, like 1.0, v1, latest, etc.).
. tells Docker to use the current folder (root of your project) as the build context.

After running:

docker build -t todo-app:1.0 .

Docker reads your Dockerfile, packages your Node.js app with all its dependencies, and creates a Docker image. You can confirm the image exists by running:

docker images

You should see output like this:

REPOSITORY      TAG       IMAGE ID       CREATED          SIZE
todo-app        1.0       d85dd4ed97f9   45 seconds ago   147MB
mongo           latest    1d659cebf5e9   2 weeks ago      894MB
mongo-express   latest    1133e12468c7   20 months ago    182MB

This shows that your todo-app image has been created successfully, alongside the images for MongoDB and Mongo Express.

Running Your Node.js App Container

Now that the image exists, the next step is to run a container from it. A container is basically a running instance of your image. To do this:

docker run todo-app:1.0

Here’s what this command does:

docker run starts a new container from the image.
todo-app:1.0 tells Docker which image to use (the one we just built).

Once this runs, your Node.js app will be live inside a container, separate from your local environment. You can open your browser at http://localhost:3000 and see your Todo app working just like it did locally.

To see all running containers, use:

docker ps

You’ll see something like:

CONTAINER ID   IMAGE           COMMAND         CREATED       STATUS       PORTS                  NAMES
d85dd4ed97f9   todo-app:1.0    "node server.js"  10s ago      Up 10s       0.0.0.0:3000->3000/tcp   awesome_todo

This confirms your container is running. If you ever need to stop it:

docker stop

Troubleshooting Errors

We started facing some issues here: when you run docker run todo-app:1.0 You'll see an error like this:

Server → http://localhost:3000 
MongoDB connection error: MongoServerSelectionError: getaddrinfo ENOTFOUND mongodb
    at Topology.selectServer (/home/app/node_modules/mongodb/lib/sdam/topology.js:346:38)
    ...
    [cause

especially when you try to perform an operation like creating a todo list.

The error getaddrinfo ENOTFOUND mongodb tells us that your Node.js container can't find MongoDB. Even though MongoDB is running in another container, your app container is isolated and doesn't know how to reach it.

Why This Happens:

Remember in our server.js, we connect to MongoDB using:

const mongoUrl = "mongodb://admin:password@localhost:27017";

The problem is with localhost. When you run your app locally on your machine (not in Docker), localhost works perfectly because MongoDB is running on the same machine. But when your app runs inside a Docker container, localhost refers to the container itself, not your host machine or other containers.

Think of it like this:

Running locally: Your app and MongoDB are like two people in the same room, localhost works
Running in Docker: Each container is like a separate room, localhost only refers to that specific room

The Solution

We need to change the MongoDB connection URL to use the Docker service name instead of localhost. Update your server.js file:

const mongoUrl = "mongodb://admin:password@localhost:27017";

To this:

const mongoUrl = "mongodb://admin:password@mongodb:27017";

Here's the complete updated server.js:

const express = require("express");
const multer = require("multer");
const path = require("path");
const fs = require("fs");
const { MongoClient, ObjectId } = require("mongodb");

const app = express();
const PORT = 3000;

// Host = localhost  →  talks to the MongoDB container via the exposed port
// Port = 27017      →  default MongoDB port
// User / Pass       →  admin / password (the credentials you gave the container)
const mongoUrl = "mongodb://admin:password@mongodb:27017";
const dbName = "todos";
let db;

MongoClient.connect(mongoUrl)
  .then((client) => {
    db = client.db(dbName);
    console.log("Connected to MongoDB →", dbName);
  })
  .catch((err) => console.error("MongoDB connection error:", err));

const uploadDir = path.join(__dirname, "uploads");
if (!fs.existsSync(uploadDir)) fs.mkdirSync(uploadDir);

const storage = multer.diskStorage({
  destination: (req, file, cb) => cb(null, uploadDir),
  filename: (req, file, cb) => {
    const unique = Date.now() + "-" + Math.round(Math.random() * 1e9);
    cb(null, "photo-" + unique + path.extname(file.originalname));
  },
});
const upload = multer({ storage });

app.use(express.static(__dirname));
app.use("/uploads", express.static(uploadDir));
app.use(express.json());
app.use(express.urlencoded({ extended: true }));

app.get("/todos", async (req, res) => {
  const todos = await db.collection("todos").find().toArray();
  res.json(todos);
});

app.post("/todos", upload.single("photo"), async (req, res) => {
  const text = req.body.text?.trim();
  if (!text) return res.status(400).json({ error: "Text required" });

  const todo = {
    text,
    image: req.file ? `/uploads/${req.file.filename}` : null,
    createdAt: new Date(),
  };

  const result = await db.collection("todos").insertOne(todo);
  todo._id = result.insertedId;
  res.json(todo);
});

// Start server
app.listen(PORT, () => {
  console.log(`Server → http://localhost:${PORT}`);
});

Why `mongodb` Works

The hostname mongodb matches the service name we defined in our docker-compose.yml:

services:
  mongodb:    # ← This is the hostname other containers use
    image: mongo
    container_name: mongo
    ...

When containers run in the same Docker Compose network, Docker provides an internal DNS that resolves service names to the correct container IP addresses. So when your app tries to connect to mongodb:27017, Docker automatically routes it to the MongoDB container.

Rebuild Your Docker Image

Now that we have updated the code, we need to rebuild the Docker image to include this change:

docker build -t todo-app:1.0 .
``

You should see output confirming the build completed successfully:
```
[+] Building 8.1s (10/10) FINISHED
 => [internal] load build definition from Dockerfile
 => => transferring dockerfile: 443B
 ...
 => => naming to docker.io/library/todo-app:1.0

Add Your App to Docker Compose

Now update your docker-compose.yml file to include the todo-app service:

version: "3.8"

services:
  mongodb:
    image: mongo
    container_name: mongo
    ports:
      - "27017:27017"
    environment:
      MONGO_INITDB_ROOT_USERNAME: admin
      MONGO_INITDB_ROOT_PASSWORD: password

  mongo-express:
    image: mongo-express
    container_name: mongo-express
    ports:
      - "8081:8081"
    environment:
      ME_CONFIG_MONGODB_ADMINUSERNAME: admin
      ME_CONFIG_MONGODB_ADMINPASSWORD: password
      ME_CONFIG_MONGODB_SERVER: mongodb
    depends_on:
      - mongodb

  todo-app:
    image: todo-app:1.0
    container_name: todo-app
    ports:
      - "3000:3000"
    depends_on:
      - mongodb

The todo-app service includes:

image: todo-app:1.0 that uses the Docker image we just rebuilt
container_name: todo-app that gives the container a friendly name
ports: "3000:3000" that exposes the app on port 3000
depends_on: mongodb that ensures MongoDB starts before the app

Start All Services

First, stop any running containers:

docker compose down

If you have port 3000 running in your local system, then stop it (that is, free up port 3000).

We were running the server locally before, but now that we’ve built a Docker image, the app runs inside a container, so it’s no longer dependent on the local machine’s environment.

node server.js
Server → http://localhost:3000

Now stop it with Ctrl + C in that terminal. That’s it.

Then start everything together:

docker compose up -d
```

You should see:
```
[+] Running 4/4
 ✔ Network docker_tut_default  Created
 ✔ Container mongo             Started
 ✔ Container mongo-express     Started
 ✔ Container todo-app          Started

Verify Everything Works

Check that all containers are running:

docker ps
```

Expected output:
```
CONTAINER ID   IMAGE           COMMAND                  CREATED          STATUS          PORTS                      NAMES
a1b2c3d4e5f6   todo-app:1.0    "node server.js"         30 seconds ago   Up 28 seconds   0.0.0.0:3000->3000/tcp     todo-app
3d7c797fde1d   mongo-express   "/sbin/tini -- /dock…"   30 seconds ago   Up 29 seconds   0.0.0.0:8081->8081/tcp     mongo-express
4511ade73c38   mongo           "docker-entrypoint.s…"   30 seconds ago   Up 29 seconds   0.0.0.0:27017->27017/tcp   mongo
```

## Test Your Application

Now let's verify everything works:

### 1. Access Your Todo App
Open your browser and go to:
```
http://localhost:3000
```

### 2. Create Some Todos
Add a few todo items to test the functionality. Try uploading images too!

### 3. Verify in Mongo Express
Open Mongo Express:
```
http://localhost:8081

Navigate to the todos database, then the todos collection. You should see all the todos you just created with their complete data.

What Changed and Why It Works

Before the fix:

Connection string used localhost:27017 ❌
Container looked for MongoDB on itself
Connection failed with ENOTFOUND error

After the fix:

Connection string uses mongodb:27017 ✅
Docker's internal DNS resolves mongodb to the MongoDB container
Connection succeeds and data flows properly

This is a crucial lesson in Docker networking: containers communicate using service names, not localhost. Docker Compose automatically creates a network where all services can find each other by name.

How to Manage Your Containers

Here’s a quick overview of how to manage your containers once you have them up and running. You’ll typically use these common commands:

Stop all services:

docker compose down

View logs from your app:

docker compose logs todo-app

View logs in real-time:

docker compose logs -f todo-app

Rebuild after code changes:

docker build -t todo-app:1.0 .
docker compose up -d --force-recreate todo-app

Your application is now fully containerized and production-ready. All three services work together seamlessly, and you can deploy this entire stack anywhere Docker is supported with just the docker-compose.yml file and your built image.

Get the full updated code here.

How to Create a Private Docker Repository

Now we want to store our custom Docker image in a private container registry (instead of our local machine only). This gives you three major advantages:

Controlled access – Only people or servers you explicitly authorize can pull (or push) the image. Your code and dependencies stay private and secure.
Reliable distribution – Anyone (or any server) with the correct AWS credentials can pull the exact same image from anywhere in the world, eliminating “it works on my machine” problems.
Versioning and lifecycle management – You can keep multiple tagged versions (1.0, 2.0, latest, and so on) and easily roll back if needed.

The first step is to create a private Docker repository, also known as a container registry. In this case, we will use AWS Elastic Container Registry (ECR). Amazon ECR is a fully managed container registry that makes it easy to store, manage, share, and deploy your container images and artifacts securely from anywhere.

Once you’re on the home page, just click on the Create button. Name the repository the same as your image, todo-app, and then click Create to finalize the setup.

Don’t worry about the extra options – this isn’t an AWS tutorial.

Note: In AWS ECR, each image has its own repository, where we store the different tagged versions of that image.

Now, to push our image into the private repository, we need to do two things. First, we have to log in to the private repo. This is necessary because you’ll need authenticate yourself before AWS allows you to push anything. In other words, when you push your local image to the repo, you’re basically saying, “Yes, I have access to this registry. Here are my credentials.”

In our case, since we’re using AWS ECR, we will authenticate through AWS instead of typing our username and password manually.

Step 1: Get Your AWS Access Keys

To locate your access keys in the AWS console, follow these steps:

Log in to the AWS Console at https://console.aws.amazon.com
Click your account name (top right corner) and go to Security Credentials
Scroll down to "Access keys" section
If you don't have an access key:
- Click "Create access key"
- Select "Command Line Interface (CLI)"
- Check the confirmation box and click Next
- Add a description (optional) and click "Create access key"
IMPORTANT: Copy both the access key ID (looks like: AKIAIOSFODNN7EXAMPLE) and the secret access key (looks like: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY). Save these immediately. The secret key is only shown once. If you lose it, you'll need to create a new key pair.

Alternatively, if someone else manages your AWS account, you’ll need to ask your AWS administrator for:

An IAM user with ECR permissions
The Access Key ID and Secret Access Key for that user

Step 2: Check if AWS CLI is installed

You can do this by running this:

aws --version

Step 3: Configure AWS CLI with your credentials

Here’s how you can do this:

aws configure
```

It will prompt you for 4 things:
```
AWS Access Key ID [None]: 
AWS Secret Access Key [None]: 
Default region name [None]: eu-north-1 or any region of your choice
Default output format [None]: json

Just paste your keys when prompted, type eu-north-1 or any region of your choice for region, and json for format (or just press Enter for format).

Step 4: Test your AWS configuration

Now you’ll want to test your config to make sure everything is set up properly:

aws sts get-caller-identity

This should show your AWS account details if everything is configured correctly.

Now, login to ECR:

aws ecr get-login-password --region eu-north-1 | docker login --username AWS --password-stdin 244836489456.dkr.ecr.eu-north-1.amazonaws.com

You should see: "Login Succeeded".

Understanding Image Naming in Docker Repositories

Every Docker image has a name that tells Docker where to find or store it. For example, when you run:

docker pull mongo:4.2

Docker is actually pulling from:

docker.io/library/mongo:4.2

Here’s what’s happening:

docker.io is the registry (in this case, Docker Hub)
library is the default namespace for official images
mongo is the repository name
4.2 is the image tag

If you build a local image like todo-app:1.0, that image exists only on your machine. Docker won’t know where to push it unless you include the full registry path.

For AWS ECR, the image name must include your ECR registry URL. For example:

docker tag todo-app:1.0 244836489456.dkr.ecr.eu-north-1.amazonaws.com/todo-app:1.0

Then you can push it with:

docker push 244836489456.dkr.ecr.eu-north-1.amazonaws.com/todo-app:1.0

Without that full path, Docker won’t know which remote repository you’re referring to. That’s why just todo-app:1.0 alone won’t work.

Step 6: Build, Tag, and Push your image

# Tag your local image with the full ECR path
docker tag todo-app:1.0 244836489456.dkr.ecr.eu-north-1.amazonaws.com/todo-app:1.0

# Now push it
docker push 244836489456.dkr.ecr.eu-north-1.amazonaws.com/todo-app:1.0

⚠️ Note: Be careful when tagging and pushing your image, as every ECR repository URL is tied to a specific AWS account and region.

For example, in this tutorial, we’re using:

244836489456.dkr.ecr.eu-north-1.amazonaws.com

But your own ECR URL will be different depending on your AWS account and the region you selected (like us-east-1, ap-south-1, and so on).

So before you run your docker tag or docker push commands, make sure to replace the registry URL and region with your own.

If you don’t, Docker will throw errors like “tag does not exist” or “repository not found.”

In short, stay calm, double-check your region, and always confirm the exact ECR URL shown in your AWS console before pushing.

If you successfully ran Step 6, you should see output similar to this in your terminal:

stephenjohnson@Oghenekparobo docker_tut % docker tag todo-app:1.0 244836489456.dkr.ecr.eu-north-1.amazonaws.com/todo-app:1.0
stephenjohnson@Oghenekparobo docker_tut % docker push 244836489456.dkr.ecr.eu-north-1.amazonaws.com/todo-app:1.0
The push refers to repository [244836489456.dkr.ecr.eu-north-1.amazonaws.com/todo-app]
4f94b5cbe8ab: Pushed 
85ba7bf54231: Pushed 
4ea46a43fa07: Pushed 
dee30873f229: Pushed 
e78159dbd370: Pushed 
a358a725b813: Pushed 
cd8a6003174c: Pushed 
abb63e49e652: Pushed 
6cc65bdde70e: Pushed 
41a4e3939504: Pushed 
3520c50ae60e: Pushed 
75ba6634710f: Pushed 
1.0: digest: sha256:51f07267936fc94d9b677db8a760801e6c5fd4764f4bb2bd7b4dd150c756a39b size: 2842

This confirms your image was successfully pushed to your private AWS ECR repository.

You can now go to the AWS Management Console and then ECR, and you should see your todo-app image listed there, along with the tag 1.0.

At this point, your image is safely stored in AWS ECR and ready to be pulled or deployed anywhere that has access to your repository.

Assignment: Create and Push a New Version of Your App

Now that your first image (todo-app:1.0) has been successfully pushed to AWS ECR, it’s time to simulate a real-world workflow where developers make updates and release new versions of their applications.

Now, you’ll make a small change to your Node.js app, rebuild it, and push the updated version as todo-app:2.0.

Deploying Our Image

Now it’s time to deploy our image using Docker Compose.

Up to this point, we have been running our app using a local image:

image: todo-app:1.0

But now that your image lives inside AWS ECR, we need to replace that line with the full ECR image URI, because Docker must know exactly where to pull the image from.

Local image:

image: todo-app:1.0

Private repository image (ECR):

image: 244836489456.dkr.ecr.eu-north-1.amazonaws.com/todo-app:1.0

Docker cannot magically guess where “todo-app:1.0” is stored. If you don’t include the full registry URL, Docker will assume it’s looking at your local machine, not AWS.

Here is the clean, fixed, properly formatted docker-compose file that pulls your app from ECR:

version: "3.8"

services:
  my-app:
    image: 244836489456.dkr.ecr.eu-north-1.amazonaws.com/todo-app:1.0
    container_name: my-app
    ports:
      - "3000:3000"
    depends_on:
      - mongodb

  mongodb:
    image: mongo
    container_name: mongo
    ports:
      - "27017:27017"
    environment:
      MONGO_INITDB_ROOT_USERNAME: admin
      MONGO_INITDB_ROOT_PASSWORD: password

  mongo-express:
    image: mongo-express
    container_name: mongo-express
    ports:
      - "8081:8081"
    environment:
      ME_CONFIG_MONGODB_ADMINUSERNAME: admin
      ME_CONFIG_MONGODB_ADMINPASSWORD: password
      ME_CONFIG_MONGODB_SERVER: mongodb
    depends_on:
      - mongodb

Why “my-app” instead of “todo-app”?

In this case, we renamed it to avoid confusion between:

our local “todo-app:1.0”
our ECR “todo-app:1.0”

This keeps things clean, but you can rename it back if you want.

Why Must We Use the Full Image URL for ECR?

Other containers like mongo and mongo-express work like this:

image: mongo
image: mongo-express

Because Docker knows these are on Docker Hub.

But for a private repo like AWS ECR, Docker has no idea where “todo-app” is unless you give the full path:

AWS_ACCOUNT_ID.dkr.ecr.REGION.amazonaws.com/repository_name:tag

This tells Docker:

which account
which region
which repo
which version

Without this URL, Docker can’t pull the image.

Every time we want to pull from a private ECR repo, including using Docker Compose, we must be logged in.

Run this:

aws ecr get-login-password --region eu-north-1 | docker login --username AWS --password-stdin 244836489456.dkr.ecr.eu-north-1.amazonaws.com

If you’re not logged in, Docker Compose will throw:

❌ pull access denied
❌ repository does not exist
❌ no basic auth credentials

Deploy Your App Using Docker Compose

Before deploying, it’s best practice to stop and remove any existing containers to avoid port conflicts or orphaned containers:

# Stop all running containers in this project
docker-compose down --remove-orphans

# Optional: verify nothing is running
docker ps

This ensures that port 3000 and other mapped ports are free, preventing errors when starting new containers.

Once the environment is clean, deploy your stack:

docker-compose up -d

Docker Compose will:

Connect to AWS ECR – Authenticate and pull the todo-app:1.0 image from your private repository.
Start MongoDB – Launch the database container with your configured credentials.
Start Mongo Express – Launch the web-based MongoDB admin interface.
Start your Node.js app – Launch the my-app container, linked to MongoDB.

Check the running containers:

docker ps

You should see:

mongo
mongo-express
my-app

If my-app fails to start, it’s usually because port 3000 is already in use. Ensure it’s free by stopping any process using it:

lsof -i :3000
kill -9   # if a process is using it

Then rerun:

docker-compose up -d

To access your app:

Node.js app: http://localhost:3000
Mongo Express: http://localhost:8081

This workflow ensures a clean start and avoids common port or container conflicts.

Once your Node.js app is pushed to AWS ECR, it’s safely stored in your private repository. But what if another developer, team member, or server needs to run that same image? Since it’s private, Docker cannot pull it automatically like public images (e.g., mongo or nginx). They need authenticated access.

Here’s how they can get and use your image:

1. Grant IAM Access

Your collaborator needs an AWS IAM user or role with permissions for ECR. At minimum, the policy should allow:

ecr:GetAuthorizationToken
ecr:BatchCheckLayerAvailability
ecr:GetDownloadUrlForLayer
ecr:BatchGetImage

You can create a dedicated IAM user for this and provide them an Access Key ID and a Secret Access Key.

2. Install and Configure AWS CLI

The collaborator must have the AWS CLI installed. Then they configure it with their credentials:

aws configure

They enter:

Access Key ID
Secret Access Key
Default region (the same region where the ECR repo exists, for example, eu-north-1)
Default output format (usually json)

3. Authenticate Docker with ECR

Before pulling the image, Docker must authenticate using the AWS credentials:

aws ecr get-login-password --region eu-north-1 | docker login --username AWS --password-stdin 244836489456.dkr.ecr.eu-north-1.amazonaws.com

If successful, Docker will respond with:

Login Succeeded

4. Pull the Image

Now the collaborator can pull the image using the full ECR URI, which includes your AWS account, region, repository name, and tag:

docker pull 244836489456.dkr.ecr.eu-north-1.amazonaws.com/todo-app:1.0

5. Run the Container

After pulling, they can run the container locally:

docker run -p 3000:3000 244836489456.dkr.ecr.eu-north-1.amazonaws.com/todo-app:1.0

Or include it in a Docker Compose file, replacing the image: field with the full ECR URI.

Public images like mongo don’t require this because Docker Hub is open. Private ECR images require explicit authentication.
Every pull from a private repository requires an active login**.** Docker cannot guess credentials.
Using the full image URI ensures Docker knows exactly where to fetch the image.

This setup allows your team to share, deploy, or run your application anywhere, on local machines, staging servers, or production, while keeping your repository private and secure.

Docker Volumes

When running containers like MongoDB, all data created inside a container is ephemeral. If the container stops or is removed, all data inside it disappears. This is fine for testing, but not suitable for production.

To solve this, Docker provides volumes, which allow containers to store data outside the container, either on the host machine or in Docker-managed storage, so it survives container restarts, rebuilds, or removals.

How Docker Volumes Work

Think of Docker volumes as persistent folders for containers:

Data written inside a volume remains safe, even if the container is removed.
Containers can read/write to these volumes.
Volumes are essential for databases, logs, file uploads, or any persistent data your application needs.

Types of Docker Volumes

Docker has three main types of volumes:

1. Named Volumes

Named volumes are user-defined volumes with a clear name, that are fully managed by Docker. You’d typically use them in production databases and for persistent data that containers can share.

Here’s an example:

volumes:
  mongo-data:

And in a service:

volumes:
  - mongo-data:/data/db

2. Bind Mounts

Blind mounts map a folder from your host machine into the container. They’re often used for development, live syncing files, logs, and uploaded files.

Here’s an example:

volumes:
  - ./uploads:/usr/src/app/uploads

3. Anonymous Volumes

These are volumes without a name. Docker just assigns them a random name. You’d use them for temporary data for testing (and they’re not commonly used in production).

Here’s an example:

volumes:
  - /data/tmp

Example Docker Compose File Using Volumes

Here’s a full docker-compose.yml file using the most common volume types for a Node.js + MongoDB + Mongo Express stack:

version: "3.8"

services:
  my-app:
    image: 244836489456.dkr.ecr.eu-north-1.amazonaws.com/todo-app:1.0
    container_name: my-app
    ports:
      - "3000:3000"
    depends_on:
      - mongodb
    volumes:
      - ./uploads:/usr/src/app/uploads  # bind mount for file uploads

  mongodb:
    image: mongo
    container_name: mongo
    ports:
      - "27017:27017"
    environment:
      MONGO_INITDB_ROOT_USERNAME: admin
      MONGO_INITDB_ROOT_PASSWORD: password
    volumes:
      - mongo-data:/data/db  # named volume for persistent database storage

  mongo-express:
    image: mongo-express
    container_name: mongo-express
    ports:
      - "8081:8081"
    environment:
      ME_CONFIG_MONGODB_ADMINUSERNAME: admin
      ME_CONFIG_MONGODB_ADMINPASSWORD: password
      ME_CONFIG_MONGODB_SERVER: mongodb
    depends_on:
      - mongodb

volumes:
  mongo-data:  # named volume definition

How this code is working:

MongoDB Volume (mongo-data): This is a named volume. It stores all database files under /data/db inside the container. It survives container restarts, removals, or rebuilds.
Node.js Uploads (./uploads): This is a bind mount. It maps the uploads folder on your host to /usr/src/app/uploads inside the container. Any uploaded files are immediately visible on your host.
Anonymous Volume: These are not shown in this file because it’s rarely used in production. Temporary data storage is created automatically by Docker if a volume is defined without a name.

Visual Concept (Simplified):

Host Machine
├─ /project/uploads  ← bind mount, synced with container
├─ Docker Volumes
│  └─ mongo-data    ← named volume, persistent MongoDB data

Containers
├─ my-app
│  └─ /usr/src/app/uploads  ← sees host uploads folder
├─ mongodb
│  └─ /data/db             ← uses named volume mongo-data
├─ mongo-express

Takeaways

Always use volumes for data you care about.
Named volumes are best for databases in production.
Bind mounts are best for development and live syncing.
Anonymous volumes are rarely needed outside testing.
Volumes separate container lifecycle from data lifecycle, which is a cornerstone of Docker best practices.

Start Your Application

Once your Docker Compose is configured with volumes, the next step is to start your application and make sure the volumes are working correctly. Here’s a simple step-by-step guide.

1. Start the Containers

Run:

docker-compose up -d

The -d flag runs the containers in detached mode (in the background).

Docker will:

Pull your app image from AWS ECR (if you’re logged in)
Start MongoDB with the named volume
Start Mongo Express
Start your Node.js app

2. Check Running Containers

To see if everything started correctly:

docker ps

You should see something like:

CONTAINER ID   IMAGE                                               STATUS          PORTS
2a2e120cc912   244836489456.dkr.ecr.eu-north-1.amazonaws.com/todo-app:1.0   Up 5s    0.0.0.0:3000->3000/tcp
f4d5a1ab1234   mongo                                               Up 5s          0.0.0.0:27017->27017/tcp
c3d5b2bc2345   mongo-express                                      Up 5s          0.0.0.0:8081->8081/tcp

3. Verify Volumes

List Docker volumes:

docker volume ls

You should see your named volume, for example mongo-data.

Inspect the volume:

docker volume inspect docker_tut_mongo-data

This will show where Docker stores your MongoDB data on the host, for example:

[
    {
        "Name": "mongo-data",
        "Driver": "local",
        "Mountpoint": "/var/lib/docker/volumes/mongo-data/_data",
        "Labels": {},
        "Scope": "local"
    }
]

Anything stored in /data/db inside MongoDB is actually saved here on your host.

4. Test Data Persistence

Connect to MongoDB or your app and add some data.
Stop and remove the container:

docker-compose down

Restart the app:

docker-compose up -d

Check your data again.

Because MongoDB uses the named volume, your data is still there.
This proves the volume is persistent.

5. Optional: Check Node.js Uploads (Bind Mount)

If you uploaded a file through your app, check your project folder ./uploads.
You should see the file appear on your host machine because bind mounts sync host and container directories.

Conclusion

Well done, you have made it to the end of this comprehensive Docker tutorial. From unraveling the basics of containers and images, to networking, Docker Compose, volumes, and even deploying to a private AWS ECR repository, you've built a fully containerized Node.js application stack that's production-ready and scalable. These are hands-on skills that will transform how you develop, collaborate, and deploy applications in real-world scenarios.

Thank you for sticking with it. Docker can feel overwhelming at first – those long commands, networking quirks, and persistent data challenges aren't trivial. But getting to this point? It means you've conquered a steep learning curve and reached new heights in your development journey. You're now equipped to eliminate "it works on my machine" headaches, streamline CI/CD pipelines, and level up as a backend or full-stack pro.

Keep experimenting: Tweak your todo-app, try multi-stage builds in your Dockerfile, or explore orchestration tools like Kubernetes next. The Docker ecosystem is vast, but with this foundation, you're ready to dive deeper. If you hit snags or have questions, the community on Docker Hub, Stack Overflow, or GitHub.

You can find the final code here: https://github.com/Oghenekparobo/docker_tut_js/tree/final

How to Start a Career in Technical Writing by Contributing to Open Source

Oluchi Nwenyi — Fri, 20 Jun 2025 17:03:51 +0000

One of the most common questions I’m asked is, “how can I get started in technical writing?” And honestly, I love that question because it means more people are beginning to see writing as a valid, valuable way to enter the tech industry.

Begin with open source. That's what I typically tell them.

It might sound intimidating at first, but open source is one of the most accessible and welcoming ways to learn by doing. You don’t need to be an expert. You don’t need to know how to code extensively. You just need to be willing to write, research, ask questions, and contribute.

In this article, I'll share what I've learnt from my own experience with starting a career in technical writing through open source.

Common Misconceptions About Technical Writing
Who is a Technical Writer?
What is Open Source?
Why You Should Build Your Technical Writing Career with Open Source
Your Role in Open Source as a Technical Writer
Technical Skills You’ll Need to Get Started
How to Build a Technical Writing Portfolio Through Open Source
After Contributing, What’s next?
Wrapping Up

Common Misconceptions About Technical Writing

Before we get into it, let’s get some misconceptions about technical writing out of the way.

“You don’t need to know how to code.”

This is simply not true. While you do not need to be a software engineer to write excellent documentation, understanding basic technical concepts is important, especially if you want to communicate effectively with developers or document complex tools.

That said, many technical writers, myself included, get to learn on the job. You can start with what you know and build your skills from there. The key skill is not necessarily coding – it’s being able to explain things clearly and ask the right questions.

“It’s just about writing things down clearly.”

It’s more than that. Technical writing is about understanding how something works, figuring out what users need to know, and then organising that information in a way that’s useful and accessible.

It involves research, asking questions, testing things out, and often working closely with developers or product teams. The real skill lies in turning complexity into clarity – not just in writing well, but in thinking clearly and structuring information in a way that helps people succeed.

“You need a technical writing degree or certification.”

Also false. While a course or certification can help you build confidence, they’re not required. Many people get started by contributing to open-source documentation, building a portfolio, and learning on the job. Your work speaks for itself, and open source gives you the opportunity to build that body of work publicly.

“Technical writing is boring.”

Not at all. Sure, you’re not writing fiction, but you are solving problems, helping people, and building bridges between developers and users. Every sentence you write could help someone figure something out faster or feel less frustrated. That’s real impact.

Having addressed that, let's proceed.

Who is a Technical Writer?

Technical writers are the bridge between engineers and everyone else. We make the complex things read more simply, and our work appears in documentation, tutorials, API references, onboarding guides, and more.

As a technical writer, how well you explain things may affect how people use a product, how developers get started, and how whole communities evolve. Good documentation is essential for adoption, and businesses seek writers who can explain technical information with the right empathy and structure.

A good technical writer does more than just write well. They listen, research, and think critically. Some of the core skills you’ll need as a technical writer include:

Clarity and structure in writing: Being able to explain things simply and logically.
Curiosity and a willingness to learn: Asking questions, exploring tools, and digging into unfamiliar concepts.
Empathy for the user: Understanding what people need and how they think.
Basic technical understanding: You don’t need to be a programmer, but being comfortable with tools, processes, or basic code reading helps you explain technical concepts better.

What is Open Source?

There are many open-source projects that power tools and technologies you might use every day and many more that power the internet. Projects like Linux, Python, Git, Wikipedia, Firefox, WordPress, and freeCodeCamp are open source projects.

Open source refers to the practice of making a project’s inner workings – whether it’s software, hardware, content, or research – openly available for anyone to view, use, modify, and improve.

Fundamentally, open source rests on several powerful principles:

Transparency: Anyone can inspect the project, understand how it works, learn from it, and contribute to it. Nothing is hidden.
Collaboration: People from all over the world can contribute, suggest improvements, and solve problems together.
Community-driven innovation: Progress happens through shared effort. The best ideas often emerge when diverse contributors come together.

Open source is about creating things in the open, together.

Why You Should Build Your Technical Writing Career with Open Source

To get started in technical writing, you need three things: a tool to document, an audience to write for, and a platform to share your work. Open source gives you access to all three and more.

Let’s talk about why contributing to open source is a powerful way to start and grow your technical writing career.

First of all, it can give you some great real-world experience. You get hands-on practice with documentation for actual tools and products used by real developers and users – not just hypothetical or practice projects.

Second, contributing to open source can help you develop your skills. From writing technical guides to improving onboarding flows, you’ll strengthen both your writing and technical understanding.

It also helps you build your portfolio, visibility, and credibility. Your contributions become a tangible way to showcase your skills in writing and working on different types of documentation projects.

Your public work, which is seen by maintainers, contributors, and even recruiters, can also help you build a reputation in the field.

Contributing also helps you develop skills in cross-functional collaboration. You’ll often work alongside developers, designers, and other members of the product team, just like a real job.

As a technical writer, your involvement also helps you gain insights into how they think and develop software, which improves your writing for technical audiences.

In addition to practicing what you already know, there will be many opportunities for you to learn new skills as well. If you’d like to learn new things while being hands-on, open-source is a great place for that. By working on open-source projects, you can gain hands-on experience with new tools, documentation platforms, and even programming languages.

You also get to meet so many people who are willing to mentor, review your work, and offer feedback, so you don’t grow in isolation.

And finally, you get to make a real impact. Good documentation empowers the people you’re writing for. Your writing could be the reason someone else joins a project or starts using a new tool.

You’re not just writing docs. You’re making technology more accessible, communities more welcoming, and learning more equitable.

Your Role in Open Source as a Technical Writer

In open source, technical writers play a crucial role in making projects usable, accessible, and scalable.

As a technical writer, your contributions might include:

Writing and improving documentation: From installation guides to API references, you help users get started and stay unblocked.
Creating onboarding resources: You make it easier for new contributors to join by documenting project structure, workflows, and best practices.
Clarifying technical concepts: You turn complex ideas into clear, accessible language for users of varying skill levels.
Organising content: You help structure docs logically so users can find what they need without frustration.
Spotting gaps: You ask important questions like, 'What’s missing?’ What’s unclear? What would I need to know as a first-time user?

Beyond writing, you become an advocate for the user’s perspective, identifying friction points, promoting clarity, and shaping the overall user experience of a project.

Your role extends beyond mere documentation – it’ll also involve bridging the gap between creators and users and helping open source communities grow by making their work more accessible to everyone.

Technical Skills You’ll Need to Get Started

You don’t need to be a developer to contribute as a technical writer in open source, but having a few foundational skills will make your journey smoother and more impactful.

The core technical skills to focus on include:

Git & GitHub/GitLab

Version control is essential in open source. Learn how to clone repositories, create branches, make commits and submit pull requests (PRs). These are the basic workflows for contributing to projects and collaborating with others.

Here’s a handbook that’ll teach you all the Git fundamentals you’ll need in your day-to-day routine.

Markdown

Markdown is the most common format for writing open source documentation. It’s simple and lightweight, used to add structure like headings, bullet points, code blocks, links, and images to documentation.

Here’s a cheat sheet that’ll teach you markdown basics – it’s geared towards technical writers.

Basic Command Line

Knowing how to navigate folders, run simple commands, and install tools from the terminal can help you test software and understand the context you're writing about.

You can learn about command line and bash scripting basics in this detailed tutorial.

And here’s a handbook that covers some of the most commonly used Linux commands you’ll need to know.

Text Editors

Tools like VS Code, Cursor, or even online editors on GitHub are commonly used to write and edit documentation. Knowing how to work in them will make your contributions easier.

You can learn how to use VS Code, one of the most popular editors among devs, in this crash course.

Reading Code

You don’t need to be a programmer, but being able to skim through code and understand file structures or function names can help when documenting how something works.

You don’t need to master everything before you start. These are skills you’ll need to develop along the way. The most important thing is to be curious, ask questions, and keep learning as you contribute.

How to Build a Technical Writing Portfolio Through Open Source

Open source is one of the most effective ways to build a strong, public portfolio and kickstart your career as a technical writer. Here’s a step-by-step guide to help you begin contributing to open source as a technical writer:

Create a GitHub (and optionally GitLab) account

Most open source projects are hosted on GitHub, so this is your gateway to finding and contributing to them. Make sure your profile is complete and professional – consider it to be your public résumé.

Here’s a peek at what a good GitHub profile can look like (it’s mine 🤗), with a clear bio, current work, interests, and ways to connect. You don’t need to overthink it – just make sure it reflects who you are and what you’re working on.

Explore documentation-focused opportunities

Look for repositories tagged with labels like documentation, good-first-issue, or help wanted. These typically signal that certain tasks (issues) are accessible to new contributors and often related to improving or creating documentation.

Some examples of open-source projects that are known to be welcoming to documentation contributors include Mautic, GitHub, Mozilla, Layer5, Kubernetes, etc.

You can also browse communities like Hashnode, Dev.to, or Reddit’s r/opensource for leads on projects seeking writing support.

Start with simple contributions

Ease into the process by tackling small but valuable tasks like fixing typos or grammar errors, enhancing clarity and structure, and improving formatting or consistency.

These types of edits help you learn the contribution workflow and gain confidence. As you grow more comfortable, take on larger tasks, like writing tutorials, onboarding guides, or reorganising documentation systems.

Engage with project maintainers

Before making changes, introduce yourself by opening an issue or commenting on an existing one. Ask if you can work on a specific improvement, and clarify expectations around style, tone, or structure.

Good communication shows respect for the project and increases the likelihood your contribution will be accepted.

Document your work as you go

For every contribution you make, keep track of it. Create a personal documentation portfolio with links to pull requests or merged contributions, screenshots or before-and-after comparisons, and explanations of what you improved and why.

This portfolio serves as compelling evidence of your skills and impact, which can be beneficial for job applications, freelance work, or community recognition.

After Contributing, What’s next?

Once you’ve started making contributions, you’re no longer “aspiring” – you’re already doing the work. That’s something to celebrate. But it’s also just the beginning. Here’s how to keep the momentum going and turn your contributions into a foundation for growth:

Reflect on what you’ve learned

After my first few open source contributions (fixing some formatting and clarifying contributing guides), I realized how much I learned just by navigating the repo, reading through issues, and figuring out how to submit a PR.

I wasn’t just improving docs. I was learning Git and understanding community norms. Ask yourself: What did you enjoy? What was tricky? What would you do differently next time?

Ask for feedback

Don’t be afraid to reach out to maintainers or fellow contributors. Thoughtful feedback can sharpen your writing, improve your collaboration skills, and help you grow faster.

I often left comments like: “Hey! I’ve submitted a small change to improve clarity in this section. I’d love your feedback on whether the tone and structure align with your existing style guide.”

Every time I did, I either got affirmation, or helpful advice, and both helped me grow faster.

Stay involved in the community

Contributing once is wonderful. But staying active, participating in discussions, joining meetings, or helping other newcomers deepens your understanding and strengthens your place in the project.

Contribute again (and again)

Look for other areas in the same project or explore new ones. As you gain experience, try tackling more complex documentation tasks or helping shape the docs strategy.

Document your experience through blog posts, tweets, or videos. Sharing showcases your work and inspires others to contribute.

I’ve written blog posts and Twitter threads reflecting on my learning process, not just to celebrate but to document what I did and help others who are a few steps behind me. Almost every time I published something on learning about open-source, someone reached out to say it helped them or ask questions.

You might be the nudge someone needs to start contributing too.

Join writing communities

Get connected with other writers through groups like Write the Docs, the Hackmamba community, or even local writing meetups. These communities offer support, resources, and new opportunities.

Turn it into a career

Use your contributions as a portfolio to apply for internships, fellowships, or junior tech writing roles. Pitch your writing to developer-focused blogs or publications like freeCodeCamp. And start freelance work for startups or open-source organisations.

Technical writing has so many paths – full-time roles, freelancing, developer education, content strategy, documentation engineering – and the work you do in open source can lead to any of them.

Keep learning

Technical writing is a skill you can continue to refine through courses, peer reviews, mentorship, and hands-on practice. You can explore new tools or pick up a little code; do whatever helps you grow.

Wrapping Up

Your first contribution proves that you can write for real-world tools, collaborate in technical spaces, and add value to communities. What comes next is up to you, but you’ve already taken the most important step: you’ve started.

Have questions or want to share your journey?
I’d love to hear from you. Feel free to connect or reach out to me on LinkedIn.

How to Write Documentation That Increases Sign-ups

Tooba Jamal — Thu, 19 Jun 2025 15:35:17 +0000

Writing documentation looks easy, but it is one of the most critical parts of your customer support and growth strategy. Too often, teams treat it as an afterthought – just add a few code snippets and move on.

But if you’re serious about product adoption, your docs need to do more than exist. They need to guide, support, and convert. In this tutorial, we’ll break down how to write documentation that actually helps users and gets them to stick around.

What’s the Problem with Most Documentation?
How to Write Documentation from the User’s Perspective
How Does Documentation Increase Sign-ups?
Making Complex Documentation Accessible

What’s the Problem with Most Documentation?

The most common problem with documentation is that its authors believe their audience knows everything. This leads to the loss of many potential leads – causing people to abandon your platform before even fully understanding it.

Here’s why:

It’s often dry and code-heavy, with snippets and vague bullet points.
It dumps information and expects the readers to figure it out.
It’s written from the developer’s point of view, not the user’s.
It rarely shows how the product fits into the user’s specific use case or workflow.
It combines different content types into a chaotic mess that’s difficult to follow or navigate.

How to Write Documentation from the User’s Perspective

Most documentation is written from a developer’s perspective: technical, feature-first, and dry. But at the end of the day, developers are also humans with problems like others, and when browsing your documentation, they are asking:

“Can this solve my problem?”
“How do I get it working for my use case?”
“What happens if I get stuck?”

Here’s how you can make people stay and come back to your documentation.

Start by Understanding Your Users

Before writing a single line of documentation, pause and ask: What do our users actually care about? And it's more than just “connect an API to their client’s app”. It's the intangible benefits they’re seeking, such as two hours saved due to your tool while connecting the API or collecting payments from different clients with a single workflow.

This means that you need to listen before you write.

Dig into conversations happening around your product, not just within it. What questions do users consistently ask during sales calls? What pain points come up in Reddit threads or support tickets? What complaints are circulating on social media that haven’t been addressed yet?

Pay close attention to the words they use while referring to your product.

When you use their words, not yours, your documentation starts to sound like a helpful guide, not a technical manual. That shift alone can be the difference between “let me try this tool” and “I’ll figure it out later.”

Supabase is a good example of user-friendly docs. It begins by categorizing content by product, module, and client library. Each category includes comprehensive documentation with real-world examples, practical use cases, tutorials, and built-in feedback support.

Structure Around the Four Documentation Types

Now that you know your customer, your job is to guide them to the correct answer fast. That’s hard to do if everything’s thrown together in one long page. Structure is what turns chaos into clarity.

The best documentation systems categorize information into four types, a framework originally proposed by Divio. Not just different sections, but completely different purposes. Each one meets your user at a different stage of their journey.

Let’s break them down:

1. Quickstart

This is the user’s first real experience with your product, and it’s where they decide whether to continue using it. So your job here isn’t to explain everything. It’s to walk them through one thing that works. Slowly. Clearly. And in their language.

Use examples. Don’t assume prior knowledge. Avoid jargon unless you’ve already explained it. The goal is to create that first “Oh, I get it now” moment. Because once they’ve had it, they’ll stick around for more.

For example, the React documentation gives beginners a simple walkthrough, from creating a component to passing data between them. It avoids jargon, focuses on one working example, and explains each step clearly. This helps users quickly grasp how React works, creating that first “Oh, I get it now” moment.

2. How-to Guides

These are for users who already know the basics and just want to solve a problem. “How do I connect this to Slack?” “How do I export this as a CSV?” They’re not here to learn concepts. They just want to follow instructions and get something done.

Start by telling them exactly what the guide will help them do. List prerequisites up front if needed. Then walk them through the steps.

For example, the TensorFlow documentation includes a step-by-step guide on how to build a Convolutional Neural Network (CNN) to classify images. It’s task-focused and practical, so anyone trying to implement image classification with TensorFlow knows exactly where to go and what steps to follow.

3. Technical Reference

This is where the raw details live. Your endpoints, CLI commands, Parameter lists, what happens when something fails, and so on. Think of it like a glossary of your tool.

People scan this portion of your documentation, so make it easy to scan. Organize it so someone can jump to what they need. Use consistent formatting and avoid explanations here, but add links to the explanations sections.

For example, the Kubernetes documentation includes a comprehensive API reference that lists all available resources, their fields, default values, and behaviors. It’s organized into categories like common parameters and workload resources, making it easy to navigate. Each section focuses on definitions and parameters, with links to related conceptual docs for deeper context.

4. Explanations

This is where you step back and explain the thinking behind your system. Why does your product rely on webhooks? Why did you structure your SDK a certain way? When should someone use one method over another?

This part differentiates your tool from the crowd and builds trust. Yet, many documentations miss this. Don’t forget to add a separate section on common errors beyond 404s here. The errors that people encounter when using your tool provide a straightforward solution to those errors.

For example, Divio has an explanation section in its documentation that covers each relevant concept in detail. It starts by explaining the concept itself, then shows how it works within Divio and what practical applications it has. This helps users understand the reasoning behind the system and how to use it effectively.

Make it Easy to Reach Out

Even with perfect docs, users will get stuck. And the worst thing you can do now is make them hunt for help.

Make it ridiculously easy to reach out.

Add a simple “Was this helpful?” prompt at the end of each page. If the answer is no, give them a quick way to say why.

Drop in a link to report bugs, outdated steps, or confusing content. You’ll get real-time feedback from real users.

Invite them to contact support or drop a question in your community Slack or Discord. It’s not just about solving issues. It’s about showing them you’re listening.

Keep Your Tech Team in the Loop

You don’t need to know how every line of code works. But you do need a clear path to someone who does.

Set up a shared document, Notion page, or Slack thread where your development team can casually share technical decisions, temporary errors, important workarounds, and other relevant information.

Also, don’t be afraid to ask your devs directly. A 3-minute voice note or quick message like “Does this sound right to you?” can prevent a dozen user errors later..

Reuse What You’ve Already Written

Chances are, you've already explained 80% of what needs to go in your docs you just didn’t call it “documentation” at the time.

Start by digging through what’s already there:

Sales or support Slack threads where you broke things down clearly
Onboarding emails that walk users through the first steps
Internal guides your team relies on
Blog posts where you’ve explained product decisions
FAQs your support team sends on repeat

Copy-paste, trim, reframe, and you’ve got a doc draft in minutes.

Get AI Help (The Smart Way)

AI tools can cut your documentation time in half, but only if you treat them like a collaborator. One powerful way to use them is by turning raw code into structured docs.

Just drop in a code snippet or feature file and prompt something like: “Write a reference doc for this API endpoint. Include usage, parameters, response structure, and a working example.”

Then take it a step further: “Now rewrite this for a non-technical product manager who’s using the tool for the first time.” This way, you get both the technical version and a plain-English explanation without switching tabs ten times.

I used AI to generate the documentation for the user.updated webhook event, and here’s what it came up with. While the generated doc is functional, I’d like to improve it further.

Here are my initial thoughts:

Avoid starting with generic phrases like “This document describes...”
Jump straight into what the user.updated event does
Remove unnecessary passive voice to improve clarity
For example, instead of:
"The user.updated event is triggered when a user's profile is updated in the system."
use:
"Whenever a user profile is updated in your system, the user.updated event is triggered."

If the generated text sounds robotic, you can use an AI humanizer to make it more natural. Then, give it a final review to remove unnecessary content, add your voice, and ensure accuracy.

Get Feedback Early

Don’t wait for the “final version” before asking for input. Documentation needs to be useful, and it’s better to get clarity early in the process. When you ask real humans for feedback on your documentation, you get a reality check before a customer spreads negative feedback about you.

Instead, test your docs in real-world conversations:

Drop a how-to guide in your support team’s Slack and ask, “Would you send this to a user?”
Ask a teammate or friend to follow your tutorial. Watch where they pause or get confused.
Run it by sales or customer success, they know exactly where users get stuck in onboarding.

And if you're just a small team of two people, ask each other. Then ask each other's friends. You don’t need a formal process, just honest reactions from real people.

How Does Documentation Increase Sign-ups?

When a developer first arrives at your documentation page, they give it a few minutes to decide whether your tool is worth using, especially if they’re still exploring options.

If they’re required to use your tool for any reason, they’ll likely spend a day or two trying to figure things out. If they can’t find the right information, the frustration builds and often escalates to upper management. That’s when you risk not just losing a user, but losing a team or even a larger client.

Good documentation prevents that.

It is well-structured, speaks to users at all levels, and is easy to navigate. It keeps users on your page longer and encourages them to test your tool instead of bouncing to a competitor. If you also offer feedback channels or live support, users are more likely to reach out when they get stuck, and that support interaction can make all the difference.

Good documentation:

Reduces support dependency, so users spend more time building and less time troubleshooting
Lowers frustration, which signals maturity and product quality
Builds trust by showing that your team has thought through user needs
Helps users get something working quickly, which often turns into a sign-up

Making Complex Documentation Accessible

Writing good docs requires careful planning, collaboration, and a solid understanding of your users. Whether your developers are writing it or you're working with a technical copywriter, excellent documentation is rarely a solo job. It requires input from the people who developed the product and those who support its users daily.

When done right, your docs don’t just explain things – they make your product more straightforward to use, build trust with potential customers, and drive sign-ups.

Liked what you read? I help SaaS companies clarify their messaging and build authority through content. You can connect with me on LinkedIn.

Learn TypeScript – A Handbook for Developers

Oghenekparobo Stephen — Fri, 07 Feb 2025 15:26:48 +0000

This handbook will teach you the basics of TypeScript, including what it is, why it is useful, and the key features it offers.

TypeScript was created by Anders Hejlsberg, a prominent software engineer at Microsoft who’s also known for his work on C# and Delphi. TypeScript was designed to enhance JavaScript by adding static types, making it easier to build and maintain large-scale applications.

We’ll start by using Vite to integrate TypeScript with a React project. Then you’ll learn about key concepts like type annotations, type inference, and how to handle objects and arrays.

After that, we’ll explore advanced topics such as union and any types, readonly properties, functions with specific parameter and return types, generics for flexible and reusable code, and the distinctive roles of type aliases and interfaces.

I’ll provide detailed examples and explanations throughout the handbook to give you a comprehensive understanding of how TypeScript's features can improve JavaScript development.

Prerequisites

I assume you are already familiar with the fundamentals of JavaScript and React. So in this handbook, I won’t be going into in-depth explanations of certain concepts, such as the file structure when scaffolding projects.

What is TypeScript?

Before diving into what TypeScript is, it's important to understand why it was created. JavaScript is a loosely typed language, meaning variables are defined and their types are determined at runtime. This flexibility can lead to unexpected behavior, especially in larger projects.

For example, you might accidentally assign a value of the wrong type to a variable, resulting in errors that you only discover when the code is executed.

Here’s an example of JavaScript that demonstrates this issue:

let userName = "Alice";
userName = 42; // No error during assignment, but this might break the code later.

function greetUser(name) {
  console.log("Hello, " + name.toUpperCase()); // Error at runtime if `name` is not a string.
}

greetUser(userName); // Throws an error because `userName` is a number, not a string.

This error can be challenging to debug, as it only surfaces at runtime, making large projects harder to maintain and more prone to bugs.

This is where TypeScript comes into the picture. TypeScript is a programming language that builds on JavaScript by adding static typing. Static typing means you can explicitly specify the types of variables, function arguments, return values, and more. Unlike dynamic typing, where types are determined at runtime, static typing allows TypeScript to catch type-related errors early during development, improving code quality and reducing bugs.

For example, here’s the same code written in TypeScript:

let userName: string = "Alice";
// userName = 42; // Error: Type 'number' is not assignable to type 'string'.

function greetUser(name: string): void {
  console.log("Hello, " + name.toUpperCase());
}

greetUser(userName); // Works perfectly since `userName` is correctly typed.

Setting Up the Project

We will be using Vite to set up our TypeScript project. Vite is a modern build tool designed to offer a faster and leaner development experience for web projects.

To get started, run the following command to create a new Vite project with TypeScript support:

npm create vite@latest

Then enter a name for your project (you may choose any name you prefer). Follow the instructions carefully in the subsequent steps

Select your project template by choosing ‘React’ from the available options. We will be using React with TypeScript for this project's development.

When prompted for a variant selection, choose 'TypeScript' from the available options.

After completing these steps, you will be prompted to navigate to your project directory and run npm install. You can use any code editor of your choice. For this example, I will be using VS Code.

After running npm install, run npm run dev to start the project on the local server. Once that’s up and running, we are ready to dive into learning TypeScript concepts.

But first, let's create our first TypeScript file, test.ts (you can choose to use .ts or .tsx). Create the test.ts file inside the src folder of your project, and add the following code to log a test message:

test.ts

console.log('Testing our first TypeScript file');

To view this in the console, import the test.ts file into the main.tsx file located in the src folder.

main.tsx

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import "./index.css";
import App from "./App.tsx";
import "./test.ts";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <App />
  StrictMode>
);

To view the log in the console, make sure to import the test.ts file into the main.tsx file located in the src folder. After that, check the console of your project running on the local server, and you should see the logged message displayed there.

Voilà!

Now let’s get down to the real business of learning TypeScript.

Type Annotations and Type Inference

What are Type Annotations?

Type annotations in TypeScript enable you to explicitly specify the type of a variable. This ensures that the variable is assigned only values of the specified type, enhancing type safety and making your code easier to maintain.

To define a type annotation in TypeScript, you simply append a colon : followed by the desired type after the variable name. This allows you to specify the type that a variable will hold, adding a layer of clarity and precision to your code. For instance, let’s specify a variable of type string in our test.ts file, ensuring that only a string value is assigned:

test.ts

let name: string = 'Stephen';

In this example, we have declared a variable name and specified that its type must be string. TypeScript will now ensure that only a string value can be assigned to name.

📄 Note: All code snippets are in a file called test.ts for demonstration purposes. You can rename the file or copy the snippets into your TypeScript project as needed. I don’t follow consistent file naming in this article.

Commonly Used Type Annotations

Here are some of the most commonly used type annotations in TypeScript:

string: Represents text values.
number: Represents numeric values (both integers and floating-point numbers).
boolean: Represents a value that is either true or false.
any: A fallback type that allows any value to be assigned to a variable, disabling type checking.
void: Typically used for functions that do not return a value.
null and undefined: Used to represent the absence of a value.

Once you define a variable with a type annotation, TypeScript ensures that it can only hold values of that specified type. You can also access the methods associated with that type. For example, if you declare a string variable, TypeScript provides access to all string methods, such as .toUpperCase().

test.ts

let name: string = 'Stephen';  // Type is explicitly set as string
name = 'John';  // This is fine, as it's still a string

// Accessing string method
console.log(name.toUpperCase());  // Output: JOHN

Here, the variable name is re-assigned to a new string value, 'John'. Since the type is still string, you can use string methods like .toUpperCase() without any issues.

You can also define arrays with type annotations. This ensures that the array only contains elements of a specific type. For example, if you define an array of numbers, TypeScript will allow you to use array methods that are specific to numbers.

test.ts

let numbers: number[] = [1, 2, 3];  // Type is explicitly set as an array of numbers
numbers.push(4);  // This is fine, as 4 is a number

// Accessing array method
console.log(numbers.length);  // Output: 4

In this case, numbers is an array of numbers. You can safely use array methods like .push() and .length, which are valid for number arrays.

If you try to reassign a variable to a value of an incompatible type, TypeScript will catch the error immediately during development, before the code is even run.

For instance:

test.ts

let name: string = 'Stephen';
name = 2;  // Error: Type '2' is not assignable to type 'string'

Here, you're trying to assign a number (2) to a variable that was previously declared as a string. TypeScript throws an error immediately, indicating that a number cannot be assigned to a string variable.

Similarly, for an array:

test.ts

let numbers: number[] = [1, 2, 3];
numbers = 'Hello';  // Error: Type 'string' is not assignable to type 'number[]'

Here, you're trying to assign a string ('Hello') to a variable that was previously declared as an array of numbers. TypeScript catches this error and highlights the mismatch.

Experiment with different types to see how TypeScript enforces type safety. For example, try using boolean, number, or other types in your arrays and variables.

Now that you've seen how type annotations work with strings and arrays, it's time to experiment with other types. TypeScript allows you to define arrays and variables with various types, ensuring type safety across your code. Try creating arrays with other data types such as boolean, number.

Example: Boolean Array

test.ts

let booleanArray: Array<boolean> = [true, false, true];

// Accessing array method
console.log(booleanArray.length);  // Output: 3

In this example, the array booleanArray is explicitly declared to hold only boolean values. Try adding string or number elements to see how TypeScript catches type errors.

Example: Number Array

test.ts

let numberArray: Array = [1, 2, 3];

// Accessing array method
console.log(numberArray[0] * 2);  // Output: 2

Feel free to play around with these examples and observe how TypeScript provides strong type safety and catches errors in real time. The more you explore, the better you'll understand how to leverage TypeScript's type system to write cleaner and more reliable code.

What is Type Inference?

Type inference in TypeScript is a powerful feature that allows the TypeScript compiler to automatically determine the type of a variable based on the value assigned to it. TypeScript is designed to be smart enough to infer types in many cases, reducing the need for explicit type annotations. This enhances code conciseness while maintaining the benefits of type safety.

With type inference, TypeScript can predict the type of a variable by analyzing the value assigned to it, ensuring that you don’t need to specify the type manually, yet still receive all the advantages of type checking.

Example 1: Inferred String Type

test.ts

let message = "Hello, TypeScript!";  // TypeScript infers 'message' as a string
console.log(message.toUpperCase());  // Output: HELLO, TYPESCRIPT!

In this example, TypeScript automatically infers the type of message as a string because the assigned value is a string.

Example 2: Inferred Number Type

test.ts

let count = 42;  // TypeScript infers 'count' as a number
console.log(count + 8);  // Output: 50

Here, TypeScript infers the type of count as a number based on the value 42, and you can perform arithmetic operations on it without type errors.

Example 3: Inferred Array Type

test.ts

let numbers = [1, 2, 3];  // TypeScript infers 'numbers' as an array of numbers (number[])
console.log(numbers.length);  // Output: 3

In this case, TypeScript infers that numbers is an array of type number[] because the array contains numbers.

Incorrect Examples:

Example 4: Mismatched Type Assignment

test.ts

let count = 42;  // TypeScript infers 'count' as a number
count = "Not a number";  // Error: Type 'string' is not assignable to type 'number'

Even though TypeScript inferred that count is a number, attempting to assign a string to it results in an error. TypeScript catches this as a type mismatch because count was initially inferred as a number.

Example 5: Inferred Array Type with Mixed Types

test.ts

let mixedArray = [1, "apple", true];  // TypeScript infers 'mixedArray' as (string | number | boolean)[]
console.log(mixedArray[0].toFixed(2));  // Error: Property 'toFixed' does not exist on type 'string | boolean'.

In this example, TypeScript infers mixedArray as an array containing multiple types (string | number | boolean). While this is allowed, accessing methods like .toFixed() on elements may result in errors because not all array elements support that method (for example, boolean and string do not have .toFixed()).

Example 6: Inferred Type with Incorrect Operation

test.ts

let price = 99.99;  // TypeScript infers 'price' as a number
price = "Free";  // Error: Type 'string' is not assignable to type 'number'

Here, TypeScript infers that price is a number, but trying to reassign it to a string leads to a type error, ensuring that the variable maintains its inferred type.

The Union and Any Types

In earlier examples, we used mixed types. Now, let’s properly define these concepts and expand on them with various examples:

What are Union Types?

Union types allow variables or parameters to hold multiple specific types, offering flexibility while maintaining type safety. You define a union type using the pipe (|) symbol.

Simple Union Type:

test.ts

let value: string | number;

value = "Hello";  // ✅ Correct
console.log(value.toUpperCase());  // Output: HELLO

value = 42;  // ✅ Correct
console.log(value + 8);  // Output: 50

value = true;  // ❌ Error: Type 'boolean' is not assignable to type 'string | number'.

In this example, value can either be a string or a number. Any other type of assignment results in a type error.

Union Type in Function Parameters:

test.ts

function printId(id: string | number): void {
  console.log(`Your ID is: ${id}`);
}

printId(12345);      // ✅ Correct
printId("abc123");   // ✅ Correct
printId(true);       // ❌ Error: Type 'boolean' is not assignable to type 'string | number'.

Here, the id the parameter can only accept a string or number, ensuring type safety while providing flexibility.

Custom Union Type:

You can create custom types using the type keyword for better readability and reusability.

test.ts

type ID = string | number;

function getUser(id: ID): void {
  console.log(`Fetching user with ID: ${id}`);
}

getUser(12345);      // ✅ Correct
getUser("abc123");   // ✅ Correct
getUser(true);       // ❌ Error: Type 'boolean' is not assignable to type 'string | number'.

What is the `any` Type?

The any type is the most flexible type in TypeScript. It allows a variable to hold any type of value, disabling type-checking for that variable.

The any type sacrifices type safety for maximum flexibility. This is useful in scenarios where you are unsure about the type or you’re working with dynamic data.

Example 1: Array of any Type

test.ts

let mixedArray: any[] = [1, "apple", true];

console.log(mixedArray[0]);  // Output: 1
console.log(mixedArray[1].toUpperCase());  // Output: APPLE
console.log(mixedArray[2]);  // Output: true

Here, the mixedArray can hold elements of any type without triggering type errors.

When to Use Union vs. `any`

Union Types: Use union types when the possible values are known or constrained to a few specific types. It provides type safety and avoids runtime errors.
any Type: Use any as a last resort when the type is unknown or dynamic.

Just remember that overusing any can negate the benefits of TypeScript’s type system. By carefully choosing between union types and any, you can write TypeScript code that is both flexible and type-safe.

Be Careful When Using `any` in TypeScript

The any type in TypeScript is a powerful yet risky feature. While this flexibility can sometimes be useful, it often leads to unintended behaviors or errors that TypeScript cannot catch at compile time.

Let’s explore an example to understand the potential pitfalls.

Here’s a function that demonstrates the risks:

function combineValues(value: any) {
  let anotherValue: number = 10;

  return value + anotherValue;
}

const result = combineValues(5); // No error here.
const anotherResult = result;

// Attempting to call a method on `anotherResult`
anotherResult.someUndefinedMethod(); // No compile-time error!

What happened here?

First, we didn’t have any type checking with any. The parameter value is of type any, meaning it can hold any value: a string, number, object, and so on. TypeScript skips enforcing type checks on value.

Second, the return value assumes any. Since value is any, the return type of combineValues is also inferred as any.

Third, there’s no error when calling an undefined method. After the function is called, anotherResult is also treated as any. TypeScript allows calling any method (even non-existent ones) on a variable of type any without throwing errors. In this case, someUndefinedMethod doesn’t exist, but TypeScript won’t warn you.

The Risks of Using `any`

Loss of type safety: You lose the benefits of TypeScript’s type system, like compile-time error checking. Potential runtime errors can go unnoticed during development.
Accidental behavior: The function could accept unexpected inputs (e.g., strings, arrays, or objects), leading to incorrect results or crashes.
Debugging complexity: Since the type is not enforced, debugging issues caused by incorrect types becomes more challenging.

How to Fix This

Use Explicit Types for Parameters and Return Values

Here’s an improved version with proper type annotations:

function combineValues(value: number): number {
  let anotherValue: number = 10;

  return value + anotherValue;
}

const result = combineValues(5);
// result.someUndefinedMethod(); // Error: Property 'someUndefinedMethod' does not exist on type 'number'.

Parameter type: The function now explicitly expects a number for the value parameter.
Return type: The return type is declared as number, ensuring that only numbers are returned.

This ensures that TypeScript will throw errors if you try to pass invalid types or call methods that don’t exist on the return value.

Key Takeaways

The any type disables TypeScript’s type checking, making your code vulnerable to runtime errors.
Avoid using any whenever possible. Instead, use explicit types or stricter alternatives like unknown (if the type cannot be determined upfront).
Explicit types enhance code clarity, maintainability, and reliability by leveraging TypeScript’s compile-time checks.

If you’re tempted to use any because the type isn’t clear, consider refactoring your code or using unknown combined with type guards for better safety.

Using `unknown` as a Safer Alternative to `any` in TypeScript

The unknown type in TypeScript is a stricter and safer alternative to any. While both any and unknown can hold values of any type, unknown requires you to perform type checks before using the value. This ensures greater type safety while still offering flexibility.

function processValue(input: unknown): string {
  if (typeof input === 'string') {
    return `The value is a string: ${input}`;
  } else if (typeof input === 'number') {
    return `The value is a number: ${input}`;
  } else {
    return 'The value is of an unknown type';
  }
}

console.log(processValue('Hello, TypeScript!')); // The value is a string: Hello, TypeScript!
console.log(processValue(42)); // The value is a number: 42
console.log(processValue(true)); // The value is of an unknown type

Using unknown instead of any has a few benefits:

Type-safe handling: Unlike any, unknown forces you to check the type of the value before using it. This prevents runtime errors caused by invalid operations on unexpected types.
Explicit type narrowing: TypeScript requires you to narrow unknown to a specific type (e.g., string, number) using type guards (typeof, instanceof, etc.) before you can access its properties or methods.
Enhanced code clarity: By using unknown, you signal to other developers that the type is deliberately uncertain and must be checked before use.

Key Differences: `any` vs. `unknown`

Feature	`any`	`unknown`
Type checking	No type checking	Requires type checks before usage
Flexibility	Can be used directly	Must narrow the type first
Common use case	Quick fixes (discouraged)	Safely handling uncertain types

So to summarize, use unknown over any whenever you deal with values of uncertain types. It helps maintain type safety and reduces the risk of errors. And try to avoid any unless necessary, as it bypasses TypeScript’s safety features.

Objects in TypeScript

In TypeScript, objects are collections of properties where each property has a name (key) and a value. TypeScript allows us to define types for these properties, ensuring that objects conform to a specific structure.

test.ts

let car = { car: 'Toyota', brand: 2024 };
console.log(car);

This works fine because TypeScript infers the types for car and brand automatically based on the values provided.

Explicit Object Types

When we want to define the shape of an object explicitly, we can use inline type annotations. This makes it clear what type each property should have. For example:

test.ts

let carOne: { car: string; brand: number } = { car: 'Evil Spirit', brand: 2025 };
console.log(carOne);

This ensures that carOne always has a car property of type string and a brand property of type number.

Let’s say we want to add a color property to carOne:

test.ts

let carOne: { car: string; brand: number } = { car: 'Evil Spirit', brand: 2025, color: 'Black' };

The code above will show a redline because color is not part of the defined type { car: string; brand: number }. The error will look something like this:

Type '{ car: string; brand: number; color: string; }' is not assignable to type '{ car: string; brand: number; }'. Object literal may only specify known properties, and 'color' does not exist in type '{ car: string; brand: number; }'.

Similarly, if you try to change the type of brand to a string:

test.ts

carOne.brand = "2026";

You’ll get another error:

Type 'string' is not assignable to type 'number'.

Having to write the full object type each time can get repetitive, especially for objects with many properties or when the same structure is used in multiple places. But don’t worry – I’ll soon introduce type aliases, which make defining and reusing object types much simpler. You’ll see how to use type aliases to simplify object types and make your code cleaner. After that, we’ll explore how to apply these concepts in React.

For now, focus on understanding the basics and how TypeScript enforces structure. It’s like peeking under the hood to see how TypeScript works behind the scenes.

Objects and Arrays

In TypeScript, we often deal with arrays of objects, where each object has a specific structure. TypeScript helps ensure that every object in the array conforms to the expected type.

Imagine you are managing a grocery store, and you want to keep track of your vegetables. Here’s how you might start:

let tomato = { name: 'Tomato', price: 2 };
let potato = { name: 'Potato', price: 1 };
let carrot = { name: 'Carrot' };

let vegetables: { name: string; price: number }[] = [tomato, potato, carrot];

When TypeScript checks this code, it throws an error because carrot doesn’t have a price property. The expected type for each item in the vegetables array is { name: string; price: number }. Since carrot is missing the price, TypeScript flags it as an error.

Type '{ name: string; }' is not assignable to type '{ name: string; price: number; }'. Property 'price' is missing in type '{ name: string; }' but required in type '{ name: string; price: number; }'.

If the price is not always known or applicable (for example, maybe the carrot's price is still being negotiated), you can make the price property optional. You can do this by adding a ? after the property name:

let vegetables: { name: string; price?: number }[] = [tomato, potato, carrot];

Now, TypeScript knows that the price property is optional. This means objects in the vegetables array can either include price or omit it without causing errors.

When a property is optional, TypeScript allows it to be either:

Present with the specified type.
Absent altogether.

This flexibility eliminates the error for objects like carrot, which lack the price property.

The `readonly` Modifier

In TypeScript, the readonly modifier is a great way to ensure that certain properties or entire objects remain immutable. This is particularly useful when you want to prevent accidental changes to your data.

Let’s continue with our vegetable store example and see how readonly works.

The Problem of Mutability

Imagine we have this setup:

let tomato = { name: 'Tomato', price: 2 };
let potato = { name: 'Potato', price: 1 };
let carrot = { name: 'Carrot' };

let vegetables: { name: string; price?: number }[] = [tomato, potato, carrot];

If someone accidentally tries to change the name of the tomato object or remove the carrot object from the vegetables array, TypeScript won’t complain:

vegetables[0].name = 'Cucumber'; // No error, but this could be unintended!
vegetables.pop(); // Removes the last vegetable, no warning.

We can use readonly to make these objects and arrays immutable, ensuring their original state cannot be altered.

Readonly on Object Properties

To make the properties of each vegetable immutable, you can do the following:

let vegetables: { readonly name: string; readonly price?: number }[] = [
  { name: 'Tomato', price: 2 },
  { name: 'Potato', price: 1 },
  { name: 'Carrot' },
];

Now, if you try to change the name or price of any vegetable, TypeScript throws an error:

typescriptCopy codevegetables[0].name = 'Cucumber'; // Error: Cannot assign to 'name' because it is a read-only

Readonly Arrays

You can also make the entire vegetables array immutable by declaring it as readonly:

let vegetables: readonly { name: string; price?: number }[] = [
  { name: 'Tomato', price: 2 },
  { name: 'Potato', price: 1 },
  { name: 'Carrot' },
];

This prevents operations that modify the array itself, such as push, pop, or splice:

vegetables.push({ name: 'Onion', price: 3 }); // Error: Property 'push' does not exist on type 'readonly { name: string; price?: number; }[]'.
vegetables.pop(); // Error: Property 'pop' does not exist on type 'readonly { name: string; price?: number; }[]'.

When to Use `readonly`

Immutable data: Use readonly when you want to enforce immutability for objects or arrays, especially in contexts where data should remain constant (e.g., configurations, initial states, constants).
Prevent bugs: Protect your data from accidental changes caused by other parts of the code.

Complete Example

Here’s an updated example with readonly in action:

let vegetables: readonly { readonly name: string; readonly price?: number }[] = [
  { name: 'Tomato', price: 2 },
  { name: 'Potato', price: 1 },
  { name: 'Carrot' },
];

// Attempting to modify data
vegetables[0].name = 'Cucumber'; // Error: Cannot assign to 'name' because it is a read-only property.
vegetables.pop(); // Error: Property 'pop' does not exist on type 'readonly { readonly name: string; readonly price?: number; }[]'.

console.log(vegetables);

Here’s what you should know about readonly, summarized:

readonly on properties ensures individual fields of objects cannot be changed.
readonly on arrays makes the array itself immutable, preventing operations like push and pop.
Combining both provides full immutability for objects within an array.

By using readonly, you create safer, more predictable code, reducing bugs caused by unintended mutations.

Function Params and Function Returns

Functions in TypeScript allow you to define both the parameters and the return types explicitly. This ensures that the function behaves as expected and avoids runtime errors. Let's break this down with a simple example.

Inferred Return Type

function arithmeticOp(price: number) {
  return price * 9;
}

const FP = arithmeticOp(2); // The result is 18.

The parameter price is explicitly defined as a number.
The return type is not explicitly stated, but TypeScript infers it to be a number because the function returns price * 9, which is a numeric operation.

TypeScript is smart enough to infer the return type of the function based on the return statement. In this case, it correctly infers that arithmeticOp returns a number.

Explicit Return Type

function arithmeticOp(price: number): number {
  return price * 9;
}

const FP = arithmeticOp(2); // The result is still 18.

The function explicitly declares the return type as number using the syntax functionName(parameters): returnType.
This doesn’t change the result but makes the function declaration clearer.

So why should you use explicit return types? Well, first of all it improves code readability and ensures that future changes don’t accidentally alter the return type. And second, it serves as documentation for other developers.

Return Type Mismatch

function arithmeticOp(price: number): number {
  if (hasDiscount) {
    return 'discount'; // Error here!
  }
  return price * 9;
}

const FP = arithmeticOp(2);

In the code above, the return type is explicitly declared as number. But the function attempts to return a string ('discount') in certain cases. This causes TypeScript to throw an error:

Type 'string' is not assignable to type 'number'.

This happens because TypeScript enforces the declared return type. If you say a function returns a number, it must always return a number, regardless of the logic inside the function.

If you want the function to return multiple types (for example, number or string), use a union type:

function arithmeticOp(price: number): number | string {
  if (hasDiscount) {
    return 'discount'; // Now valid!
  }
  return price * 9;
}

const FP = arithmeticOp(2);

The return type number | string tells TypeScript that the function can return either a number or a string. This resolves the type mismatch error.

Key Takeaways:

TypeScript infers return types when they are not explicitly defined but encourages explicit return types for clarity and maintainability.
The declared return type ensures the function only returns values of the specified type.
Type mismatches, like returning a string from a function expected to return a number, result in TypeScript errors.
Union types (type1 | type2) allow functions to return multiple types when needed.

Handling Optional, Default in TypeScript

When working with TypeScript functions, specifying parameter behavior is crucial for flexibility and preventing runtime errors. Let's explore how to handle optional and default parameters effectively with practical examples.

Example 1: Understanding the Problem with Missing Arguments

Consider the following function:

function calculateFinalScore(baseScore: number, deductions: number): number {
  return baseScore - deductions;
}

let scoreWithDeductions = calculateFinalScore(50, 10);
let scoreWithoutDeductions = calculateFinalScore(50); // Error

The first call to calculateFinalScore works perfectly. But the second call throws a TypeScript error:

⚠ Error (TS2554) | Expected 2 arguments, but got 1.
Tutorial.ts(7, 47): An argument for 'deductions' was not provided.

This happens because TypeScript expects both baseScore and deductions to be provided, as they are both required parameters. If the deductions value is omitted, TypeScript will not allow the function call.

Example 2: Fixing the Issue with Default Parameters

To resolve this issue, we can define a default value for the deductions parameter. Default parameters provide a fallback value if no argument is passed.

function calculateFinalScore(baseScore: number, deductions: number = 0): number {
  return baseScore - deductions;
}

let scoreWithDeductions = calculateFinalScore(50, 10); // 40
let scoreWithoutDeductions = calculateFinalScore(50);  // 50

In this updated example:

The deductions parameter defaults to 0 if it is not explicitly provided.
Both calls now work without errors.

Why This Solution Works

By defining deductions as a default parameter, TypeScript ensures that the function has all the arguments it needs to execute, even if some are omitted in the call. This approach increases the flexibility of the function while maintaining type safety.

Use default parameters when a value is required for the function to work but can safely have a fallback value if omitted. This approach improves code clarity and reduces the likelihood of runtime errors.

Rest Parameters

Rest parameters in TypeScript let you handle multiple arguments without knowing how many you’ll get in advance. You can pass as many arguments as you want—TypeScript will handle them. They’re perfect for situations where the number of inputs isn’t fixed.

To use rest parameters, you write three dots (...) before the parameter name, which gathers all the extra arguments into an array.

Let’s say you want to combine multiple words into a single sentence:

function joinWords(...words: string[]): string {
  return words.join(" ");
}

let sentence = joinWords("TypeScript", "makes", "coding", "fun");
console.log(sentence); // "TypeScript makes coding fun"

...words collects all the arguments into an array (["TypeScript", "makes", "coding", "fun"]).
The join method combines them into a single string, separated by spaces.

Rest Parameters with Numbers

Now, suppose you want to add multiple numbers:

function sumNumbers(...numbers: number[]): number {
  return numbers.reduce((total, num) => total + num, 0);
}

let total = sumNumbers(10, 20, 30);
console.log(total); // 60

...numbers gathers all the numbers into an array ([10, 20, 30]).
The reduce method adds them together to get the total.

We can also use rest parameters to merge multiple arrays into one:

function mergeArrays(...arrays: number[][]): number[] {
  return arrays.flat();
}

let combined = mergeArrays([1, 2], [3, 4], [5, 6]);
console.log(combined); // [1, 2, 3, 4, 5, 6]

...arrays collects each argument as an array into an array of arrays ([[1, 2], [3, 4], [5, 6]]).
The flat method combines them into one array.

Rest parameters must always come last in the parameter list. For example:

function example(a: string, ...others: number[]): void {
  console.log(a, others);
}

This ensures all remaining arguments go into the rest parameter.

Objects as Parameters in TypeScript

In TypeScript, functions can accept objects as parameters. This is particularly useful when dealing with multiple related values.

Using Objects with Specific Properties

Here's a function that takes an object with an id property and returns a new object:

function createEmployee({ id }: { id: number }): { id: number; isActive: boolean } {
  return { id, isActive: id % 2 === 0 };
}

const firstEmployee = createEmployee({ id: 1 });
console.log(firstEmployee); // { id: 1, isActive: false }

const secondEmployee = createEmployee({ id: 2 });
console.log(secondEmployee); // { id: 2, isActive: true }

The function createEmployee:

Takes an object with a single property, id, as a parameter.
Returns a new object with two properties: id and isActive.

The isActive property is determined by checking if the id is even (id % 2 === 0).

Destructuring is used in the parameter:

{ id } extracts the id property from the input object directly.

Accepting More Complex Objects

Now, let’s look at a function that takes an object with multiple properties:

function createStudent(student: { id: number; name: string }): void {
  console.log(`Welcome to the course, ${student.name}!`);
}

const newStudent = { id: 1, name: "John" };
createStudent(newStudent); // "Welcome to the course, John!"

The function createStudent:

Accepts an object with two properties: id and name.
Logs a welcome message using the name property.

The newStudent object matches the structure expected by the function, so it’s passed directly.

Why Use Objects as Parameters?

First of all, functions with objects as parameters are easier to read, especially when dealing with multiple related values. Also, using destructuring you can extract only the needed properties from an object, making the code more concise. And finally, objects can be reused across functions without creating new ones every time.

Excess Property Checks in TypeScript

In TypeScript, excess property checks help ensure that objects passed to functions only contain properties defined in the function’s parameter type. If there are extra properties, TypeScript will raise an error. Let's see how this works with simple examples.

1. Extra Property Error

Here’s a function that accepts an object with id and name, but no extra properties:

function createStudent(student: { id: number; name: string }): void {
  console.log(`Welcome, ${student.name}!`);
}

const newStudent = { id: 1, name: "John", age: 20 }; // Extra property 'age'

createStudent(newStudent); // Error: 'age' is not expected

TypeScript gives an error because the age property is not part of the expected object structure.

2. Fixing the Error

To avoid the error, just remove any extra properties:

const validStudent = { id: 1, name: "John" };
createStudent(validStudent); // This works fine

This works because the object only has the expected properties: id and name.

3. Using Type Assertion (Not Recommended)

If you really need to pass an object with extra properties, you can use type assertion to tell TypeScript to ignore the extra properties:

const studentWithExtras = { id: 1, name: "John", age: 20 };
createStudent(studentWithExtras as { id: number; name: string }); // Bypasses the error

While this works, it’s better to match the expected structure instead of using type assertion.

TypeScript expects objects to match the exact shape of the parameter type.
Excess properties cause errors to ensure the structure is correct.
Fix the object or use type assertion (carefully) if you need extra properties.

Excess property checks help keep your code safe and ensure only the right data is passed to functions.

Type Aliases in TypeScript

A type alias in TypeScript is essentially a short name or an alternative name for an existing type. It allows you to define a simpler or more readable name for a type that may be complex or used repeatedly in your code.

This doesn't create a new type, but instead gives an existing type a new identifier. The functionality of the code doesn't change when using a type alias – it simply makes your code more readable and reusable.

Here’s an example before using a type alias:

// Without type alias
function getUserInfo(user: UserInfo) {
  console.log(`User Info: 
    Name: ${user.name}, 
    Age: ${user.age}, 
    Address: ${user.address}`);
}

const user: UserInfo = { name: 'Alice', age: 30, address: '123 Main St' };

getUserInfo(user);

Now, let’s use a type alias for the function parameters to make the code more readable:

// Using type alias
type UserInfo = { name: string, age: number, address: string };

function getUserInfo(user: UserInfo) {
  console.log(`User Info: 
    Name: ${user.name}, 
    Age: ${user.age}, 
    Address: ${user.address}`);
}

const user: UserInfo = { name: 'Alice', age: 30, address: '123 Main St' };

getUserInfo(user);

In the example above:

Before the type alias, we define the parameters separately within the function.
After defining a type alias (UserInfo), we use it in the function parameter to make the function signature simpler and more readable.

This doesn’t change the functionality of the code. It just makes it easier to work with by using the alias. The alias acts as a reusable reference to a complex type, and if the shape of the UserInfo changes, we only need to update it in one place, making the code easier to maintain.

How to Use Type Aliases

A type alias allows you to define a new name for a type. This new name can represent a primitive type, an object structure, or even a union of types. The main benefit is to make your code more readable, reusable, and prevent mistakes.

You define a type alias using the type keyword followed by a name and the structure of the type.

ttype TypeName = TypeStructure;

For example, let’s create a type alias for a User object:

type User = {
  name: string;
  age: number;

This means User is a type that expects an object with two properties:

name should be a string.
age should be a number.

Why Use Type Aliases?

There are several reasons to use type aliases in your code. First of all, a type alias explicitly defines the structure of an object, so anyone reading the code knows exactly what to expect. Second, you can reuse the User type anywhere in your code without repeating the structure. And finally, TypeScript will check that any object assigned to the User type has the required properties with the correct types.

with Type Alias:

type User = {
  name: string;
  age: number;
};

function getUserDetails(user: User): string {
  return `${user.name} (${user.age} years old)`;
}

const user: User = { name: "Alice", age: 30 };
console.log(getUserDetails(user)); // "Alice (30 years old)"

In this example, we defined the User type alias to specify that user objects must have a name of type string and age of type number.

TypeScript will catch errors if you attempt to assign an object that does not match this structure, like this:

// This will result in a TypeScript error:
const invalidUser: User = { name: "Alice" }; // Missing 'age' property

What is an Intersection Type in TypeScript?

An Intersection Type is a powerful feature in TypeScript that allows you to combine multiple types into one. When you create an intersection, the resulting type must have all the properties from each of the types you intersect.

You can combine any number of types, and the resulting type must satisfy every condition of all the original types.

Syntax of Intersection Type

To define an intersection type, you use the & operator to combine two or more types.

type TypeA & TypeB;

Example of an Intersection Type

Imagine you want to extend the User type to include the user’s address. Instead of modifying the original User type, you can use an intersection type to combine User and Address.

type Address = {
  city: string;
  country: string;
};

type UserWithAddress = User & Address; // Intersection of User and Address

Now, UserWithAddress will require both the properties from User and the properties from Address.

Example with a Function

Here’s how you can use this in a function:

type User = {
  name: string;
  age: number;
};

type Address = {
  city: string;
  country: string;
};

type UserWithAddress = User & Address;

function getUserDetails(user: UserWithAddress): string {
  return `${user.name} (${user.age} years old), lives in ${user.city}, ${user.country}`;
}

const user: UserWithAddress = {
  name: "Alice",
  age: 30,
  city: "New York",
  country: "USA"
};

console.log(getUserDetails(user));
// Output: "Alice (30 years old), lives in New York, USA"

In this case:

UserWithAddress is an intersection type, which means the user object must have both the properties of User and Address.
TypeScript checks that both name and age (from User), as well as city and country (from Address), are present in the object.

If we missed any of these properties, TypeScript would show an error.

// This will result in a TypeScript error:
const incompleteUser: UserWithAddress = {
  name: "Alice",
  age: 30,
  city: "New York"
}; // Missing 'country'

Why Use Intersection Types?

Intersection types are useful in several scenarios. First, they let you extend existing types without modifying them, making the code more modular and flexible. They’re also useful when you need to merge multiple different structures into one, such as combining a User with an Address or OrderDetails. And you can easily see all the required properties that an object must have when you use intersection types.

Type Aliases vs Intersection Types:

Feature	Type Alias	Intersection Type
Definition	Defines a single type.	Combines multiple types into one.
Use case	Create reusable types for objects or primitives.	Combine multiple types, requiring all properties.
Combining Types	Not used for combining types.	Used to combine multiple types.
Example	`type User = { name: string, age: number };`	`type UserWithAddress = User & Address;`

When to Use Each One

Use type aliases when you want to define a single type for an object, function, or other data structure. They help with clarity, reuse, and type safety.
Use intersection types when you want to combine multiple types into one. It’s ideal for scenarios where an object needs to fulfill multiple contracts at once, such as when combining different types or extending the functionality of an existing type.

By leveraging Type Alias and Intersection Types in TypeScript, your code becomes easier to understand, safer, and more maintainable. These features provide structure to your data, helping to catch bugs earlier.

Interfaces in TypeScript

In TypeScript, an interface is a way to define the structure of an object, describing its properties and their types. Interfaces are used to enforce type-checking in your code, ensuring that objects adhere to a specific structure. Similar to type aliases, interfaces make your code more readable, reusable, and maintainable.

What is an Interface?

An interface is a blueprint for an object, defining what properties and methods it should have. Interfaces can be used to define custom types for objects, functions, or classes.

Here’s a basic example:

interface User {
  name: string;
  age: number;
  address: string;
}

function getUserInfo(user: User): string {
  return `${user.name} (${user.age} years old) lives at ${user.address}`;
}

const user: User = {
  name: "Alice",
  age: 30,
  address: "123 Main St",
};

console.log(getUserInfo(user)); // Output: Alice (30 years old) lives at 123 Main St

In this example:

The User interface defines the shape of the object.
Any object of type User must have name, age, and address properties with the specified types.
The getUserInfo function ensures the user parameter adheres to the User interface.

Similarities Between Interfaces and Type Aliases

Both interfaces and type aliases can define the structure of objects.
Both can be extended, though the syntax differs.
Both improve code readability and reusability.
In most cases, you can use interfaces or type aliases interchangeably to define object types.

Example with a type alias:

type User = {
  name: string;
  age: number;
  address: string;
};

const user: User = {
  name: "Bob",
  age: 25,
  address: "456 Elm St",
};

Both the type and interface achieve the same result in this scenario.

Differences Between Interfaces and Type Aliases

Let’s also summarize their key differences:

Feature	Interface	Type Alias
Syntax	Uses `interface` keyword.	Uses `type` keyword.
Extensibility	Can be extended using `extends`.	Can be extended using intersection (`&`).
Declaration Merging	Supports merging across multiple declarations.	Does not support declaration merging.
Union Types	Cannot define union types.	Can define union types.

Extending with Interfaces and Type Aliases

Extending Interfaces:

interface Address {
  city: string;
  country: string;
}

interface User extends Address {
  name: string;
  age: number;
}

const user: User = {
  name: "Alice",
  age: 30,
  city: "New York",
  country: "USA",
};

Using Type Alias for Intersection:

type Address = {
  city: string;
  country: string;
};

type User = {
  name: string;
  age: number;
} & Address;

const user: User = {
  name: "Alice",
  age: 30,
  city: "New York",
  country: "USA",
};

Both approaches result in the same outcome, but the syntax is different.

Advanced Concepts with Interfaces

1. Optional Properties:

Interfaces can define properties as optional using the ? symbol:

interface User {
  name: string;
  age?: number; // Optional
}

const user1: User = { name: "Alice" };
const user2: User = { name: "Bob", age: 25 };

2. Readonly Properties:

Use the readonly modifier to make properties immutable:

interface User {
  readonly id: number;
  name: string;
}

const user: User = { id: 1, name: "Alice" };
// user.id = 2; // Error: Cannot assign to 'id' because it is a read-only property.

3. Function Types:

Interfaces can define function signatures:

interface Add {
  (a: number, b: number): number;
}

const add: Add = (a, b) => a + b;
console.log(add(5, 3)); // Output: 8

4. Index Signatures:

Interfaces can define dynamic property names:

interface StringDictionary {
  [key: string]: string;
}

const dictionary: StringDictionary = {
  hello: "world",
  name: "Alice",
};

5. Extending Multiple Interfaces:

An interface can extend multiple interfaces:

interface A {
  propA: string;
}

interface B {
  propB: number;
}

interface C extends A, B {
  propC: boolean;
}

const obj: C = {
  propA: "Hello",
  propB: 42,
  propC: true,
};

When to Use Interfaces vs. Type Aliases

Use interfaces when you need to define object shapes, especially if you plan to extend them. Also use interfaces if you need declaration merging, as type aliases don’t support it.
Use type aliases for more complex types, such as unions or intersections

Tuples and Enums

A tuple in TypeScript is a special type of array that has a fixed number of elements, where each element can have a different type. Tuples ensure that the order and types of values remain consistent.

// A tuple with a string and a number
let user: [string, number] = ["Alice", 25];

console.log(user[0]); // Output: Alice
console.log(user[1]); // Output: 25

In this example, the tuple user contains a string (name) and a number (age). The order and types must be followed as defined.

Tuple with Optional Elements:

let person: [string, number, boolean?] = ["Bob", 30];

console.log(person); // Output: ["Bob", 30]

Here, the third element (boolean) is optional.

Tuple with Read-Only Property:

const coordinates: readonly [number, number] = [10, 20];

// coordinates[0] = 50; // Error: Cannot assign to '0' because it is a read-only tuple

The readonly keyword prevents modifying tuple values.

Enums

An enum in TypeScript is a way to define a set of named constants. Enums make code more readable and help manage a fixed set of values.

Numeric Enums (Default):

enum Status {
  Pending,   // 0
  InProgress, // 1
  Completed,  // 2
}

console.log(Status.Pending);   // Output: 0
console.log(Status.Completed); // Output: 2

By default, TypeScript assigns numeric values starting from 0.

Custom Number Values in Enums:

enum OrderStatus {
  Pending = 1,
  Shipped = 5,
  Delivered = 10,
}

console.log(OrderStatus.Shipped); // Output: 5

Here, custom values are assigned to each status.

String Enums:

enum Direction {
  Up = "UP",
  Down = "DOWN",
  Left = "LEFT",
  Right = "RIGHT",
}

console.log(Direction.Up); // Output: "UP"

String enums store fixed text values instead of numbers.

Using Enums in a Function:

function getStatusText(status: Status): string {
  switch (status) {
    case Status.Pending:
      return "Order is pending.";
    case Status.InProgress:
      return "Order is in progress.";
    case Status.Completed:
      return "Order is completed.";
    default:
      return "Unknown status.";
  }
}

console.log(getStatusText(Status.InProgress)); // Output: "Order is in progress."

This function takes an enum value and returns a message based on the status.

Tuples define fixed-length arrays with different data types, while enums provide named constants for better readability, making your code more structured and type-safe.

Type Assertion, Type Unknown, and Type Never in TypeScript

Type Assertion

Type assertion tells TypeScript to treat a value as a specific type. It does not change the value but helps the compiler understand the type.

let value: unknown = "Hello, TypeScript!";

// Using type assertion to treat 'value' as a string
let strLength: number = (value as string).length;

console.log(strLength); // Output: 18

Here, value is initially unknown, but type assertion (as string) allows treating it as a string.

And here’s an alternative way to write type assertion:

let num = <number>(10);
console.log(num); // Output: 10

The syntax also performs type assertion.

Type Unknown

Let’s briefly revisit the unknown type now. Remember that it’s a safer alternative to any and can hold any value – but TypeScript requires type checking before using it.

let data: unknown;

data = "Hello";
data = 42;
data = true;

// Type checking before using the value
if (typeof data === "string") {
  console.log(data.toUpperCase()); // Works only if data is a string
}

Since data is unknown, TypeScript does not allow direct operations without checking its type first.

Type Never

The never type represents values that never occur. It is often used for functions that never return or always throw an error.

function throwError(message: string): never {
  throw new Error(message);
}

// throwError("Something went wrong!"); // This function never returns

Here, throwError does not return anything because it always throws an error.

Example of Type Never in a Switch Case:

type Status = "success" | "failure";

function checkStatus(status: Status): void {
  switch (status) {
    case "success":
      console.log("Operation was successful.");
      break;
    case "failure":
      console.log("Operation failed.");
      break;
    default:
      const unexpected: never = status; // Ensures all cases are handled
  }
}

This ensures that all possible values of Status are handled, preventing unexpected behavior.

Here’s a quick comparison of these different approaches:

Feature	Description
Type Assertion	Tells TypeScript to treat a value as a specific type.
Unknown Type	Allows storing any value but requires type checking before use.
Never Type	Represents values that never occur, used for functions that never return.

Generics in TypeScript

Generics allow writing flexible, reusable, and type-safe code. Instead of specifying a fixed type, generics let a function, class, or interface work with multiple types while maintaining type safety.

Basic Generics

A generic function works with any type while keeping type safety.

function identity<T>(value: T): T {
  return value;
}

console.log(identity<string>("Hello")); // Output: "Hello"
console.log(identity<number>(42));      // Output: 42

Here, is a generic type parameter, allowing identity to work with any type.

Generics with Arrays

Generics help enforce type safety in arrays.

Here’s an example of reversing an array with generics:

function reverseArray<T>(arr: T[]): T[] {
  return arr.reverse();
}

console.log(reverseArray<number>([1, 2, 3]));  // Output: [3, 2, 1]
console.log(reverseArray<string>(["A", "B", "C"])); // Output: ["C", "B", "A"]

This ensures that the function always returns the same type of array it receives.

Generics with Interfaces

Generics can be used in interfaces to define flexible object structures.

interface StorageBox {
  content: T;
}

let numberBox: StorageBox<number> = { content: 100 };
let stringBox: StorageBox<string> = { content: "TypeScript" };

console.log(numberBox.content); // Output: 100
console.log(stringBox.content); // Output: "TypeScript"

Here, StorageBox allows storing different types while ensuring consistency.

Generics with Classes

Generics also work in classes, making them more reusable.

Here’s an example of a generic queue class:

lass Queue {
  private items: T[] = [];

  enqueue(item: T): void {
    this.items.push(item);
  }

  dequeue(): T | undefined {
    return this.items.shift();
  }
}

let numberQueue = new Queue<number>();
numberQueue.enqueue(10);
numberQueue.enqueue(20);
console.log(numberQueue.dequeue()); // Output: 10

let stringQueue = new Queue<string>();
stringQueue.enqueue("Hello");
stringQueue.enqueue("World");
console.log(stringQueue.dequeue()); // Output: "Hello"

This class works with any type while maintaining type safety.

Generics with Multiple Type Parameters

A function or class can accept more than one generic type.

Here’s an example of a function that swaps two values:

function swap<T, U>(first: T, second: U): [U, T] {
  return [second, first];
}

console.log(swap<string, number>("Age", 25)); // Output: [25, "Age"]
console.log(swap<boolean, string>(true, "Yes")); // Output: ["Yes", true]

Here, allows the function to work with different types at the same time.

Generics with Constraints

Sometimes, a generic type should follow certain rules. Constraints ensure that a type has specific properties.

Here’s an example of ensuring that a type has a length property:

function getLength<T extends { length: number }>(item: T): number {
  return item.length;
}

console.log(getLength("Hello"));   // Output: 5
console.log(getLength([1, 2, 3])); // Output: 3

Here, T extends { length: number } ensures that T has a length property.

Advanced: Generics with the `keyof` Operator

The keyof operator can be used to ensure valid property names.

Here’s an example of getting a property value by name:

typescriptCopyEditfunction getPropertyextends keyof T>(obj: T, key: K): T[K] {
  return obj[key];
}

let user = { name: "Alice", age: 30 };

console.log(getProperty(user, "name")); // Output: "Alice"
console.log(getProperty(user, "age"));  // Output: 30

Here, K extends keyof T ensures that key is a valid property of T.

Conclusion

In this handbook, you got an in-depth overview of how you can use TypeScript basics in React. We discussed important concepts like type annotations, type inference, and managing objects and arrays, showing how TypeScript improves code stability and maintenance.

We also covered some advanced topics such as union and any types, readonly properties, and the use of generics, type aliases, and interfaces. I hope the examples helped you understand how TypeScript can enhance your JavaScript development, making TS a valuable tool for building robust, large-scale applications.

How to Start Learning TypeScript – A Beginner's Guide

Akande Olalekan Toheeb — Fri, 24 Jan 2025 01:19:16 +0000

JavaScript is the most widely-used programming language for web development. But it lacks type-checking support, which is an essential feature of modern programming languages.

JavaScript was originally designed as a simple scripting language. Its loose nature and absence of crucial Object-Oriented Programming (OOP) features pose certain challenges for developers:

Limited documentation and auto-completion.
Inability to utilise OOP concepts.
Lack of type safety, leading to runtime errors.
Challenges in refactoring and maintenance.
Absence of interfaces and integration points.

TypeScript solves these problems. It was built to make JavaScript a more perfect modern programming language. It helps improve the developer experience, offers many useful features, and improves interoperability.

This article dives into TypeScript basics. I’ll teach you how to install TS and set up a project. Then we’ll cover some important fundamentals. You’ll also learn how TypeScript compiles into JavaScript, making it compatible with browsers and Node.js environments.

What we’ll cover:

Prerequisites
Getting Started – How to Install TypeScript
How to Organize Your TypeScript Projects
How Typing Works in TypeScript
How to Handle Objects, Arrays, and Function Types in TypeScript
How to Create Custom Types in TypeScript
How to Merge Types in TypeScript
- When to Use Each Approach
Bundling and Transformations in TypeScript
Building Better Code with TypeScript

Prerequisites

Before diving into TypeScript, it's important to have a foundational understanding of certain concepts to ensure a smoother learning journey. While TypeScript enhances JavaScript with static typing and other powerful features, it builds on core JavaScript principles. Here's what you should know:

1. JavaScript Fundamentals

TypeScript is a superset of JavaScript, meaning it extends JavaScript's capabilities. To effectively learn TypeScript, you should first have a solid grasp of JavaScript basics, including:

Syntax and data types: Understand how to declare variables (let, const, and var), work with primitive types (strings, numbers, booleans), and manage arrays and objects.
Control flow: Be familiar with loops (for, while), conditionals (if-else, switch), and how they control program execution.
Functions: Know how to define and invoke functions, work with parameters, return values, and understand concepts like arrow functions and closures.
Object-Oriented Programming (OOP): Learn about creating and working with objects, classes, and inheritance. TypeScript's class-based features build heavily on JavaScript's OOP model.
Error handling: Understand how to use try-catch blocks to handle runtime errors.

2. Basic HTML and CSS

Although TypeScript is a language used primarily with JavaScript, having a basic understanding of HTML and CSS is helpful, especially for front-end developers. This is because most TypeScript projects involve creating or working with web applications

HTML: Understand how to structure web pages using tags, attributes, and elements.
CSS: Learn how to style elements using selectors, properties, and values. Familiarity with CSS frameworks like Bootstrap is a bonus.

3. Familiarity with Development Tools

A code editor like Visual Studio Code, which has excellent TypeScript support and extensions.
Node.js and npm: Understand how to set up a development environment, run JavaScript outside the browser, and use npm (Node Package Manager) to install dependencies.
Version control (Git): Learn the basics of Git to track changes and collaborate effectively on TypeScript projects.

Getting Started – How to Install TypeScript

To get started working with TypeScript you’ll need to install it. It’s not a complicated process. With TypeScript installed, you can leverage its power to create high-quality solutions.

You can install TS in two ways:

Global Installation: enables you to access the compiler from any directory on your machine. To install TypeScript globally, execute the following command:

npm install -g typescript

This command leverages the Node.js package manager, npm. It installs TypeScript globally, making the command available in the command line.

Local Installation: in this case, TypeScript is installed only within a specific project. This method ensures version compatibility and consistency across team members. To install TypeScript locally, execute the following command:

npm install typescript --save-dev

Different from global installation, this command installs TypeScript as a development dependency. The tsc command is only available for project-specific usage, that is the specific project where you run the command.

Can you seamlessly install TypeScript now? I hope so!

How to Organize Your TypeScript Projects

Organizing a TypeScript project involves structuring its files with meaningful names and directories, separating concerns, and using modules for encapsulation and reusability.

The .ts extension denotes typeScript files and contains code that converts into JavaScript for execution.

TypeScript also supports .d.ts files, also known as type definition files. These files offer type information about external JavaScript libraries or modules, aiding in better type-checking and code completion as well as improving development efficiency. Below is an example of a good TS project structure:

my-ts-project/
├── src/ 
│   ├── components/ 
│   │   ├── Button.tsx
│   │   ├── Input.tsx
│   │   └── Modal.tsx
│   ├── services/ 
│   │   ├── api.ts
│   │   └── authService.ts
│   ├── utils/ 
│   │   ├── helpers.ts 
│   │   └── validators.ts
│   ├── models/ 
│   │   ├── User.ts
│   │   └── Product.ts
│   ├── index.tsx 
│   └── styles/ 
│       ├── global.css
│       └── theme.css
├── public/ 
│   ├── index.html
│   └── assets/ 
│       ├── images/
│       └── fonts/
├── tsconfig.json
└── package.json

Let’s understand what’s going on here:

src/: This directory houses all the source code for the project.
- components/: Contains reusable UI components (for example, Button, Input, Modal). Using .tsx (TypeScript JSX) allows you to write JSX with type safety.
- services/: Holds services that interact with external APIs or handle application logic (for example, api.ts for API calls, authService.ts for authentication).
- utils/: Contains helper functions and utility classes for common tasks (for example, helpers.ts for date formatting, validators.ts for input validation).
- models/: Defines TypeScript interfaces or classes to represent data structures (for example, User.ts, Product.ts).
- index.tsx: The main entry point of the application.
- styles/: Contains CSS or other styling files.
public/: This directory contains static assets that are not processed by TypeScript (for example, HTML, images, fonts).
tsconfig.json: The TypeScript configuration file, specifying compiler options.
package.json: The project's manifest file, listing dependencies, scripts, and other project metadata.

Just a quick note about naming conventions so you understand them here:

Use PascalCase for class names (for example, User, Product).
Use camelCase for function names and variable names (for example, getUser, firstName).
Use meaningful and descriptive names for files and directories.

This structure promotes modularity, reusability, and better organization, making your TypeScript projects easier to maintain and scale.

Properly organizing your TS projects enhances code maintainability, readability, and collaboration in TypeScript development workflows.

How Typing Works in TypeScript

Like any other typed programming language, TypeScript relies on type definitions, generally called Typing.

Typing is a term used in programming to define data types for variables, method parameters, and return values within the code.

Typing allows you to catch errors quickly and early in development, a superpower that helps maintain better code quality.

To specify a type in TypeScript, put a colon( :) and the desired data type after your variable name. Here’s an example:

let age: number = 2;

The above variable is declared with the number type. In TypeScript, this means it can store numbers only and nothing else.

Typing Techniques

In TypeScript, data can be typed in two main ways:

Static Typing: Static typing refers to explicitly specifying the data type of variables and other entities in the code during development. The TypeScript compiler enforces these type definitions, helping to catch type-related errors early. For example:

let age: number = 25;

Here, the variable age is explicitly declared to have the number type. This ensures that only numeric values can be assigned to it, reducing the risk of runtime errors.

Dynamic Typing: Dynamic typing in TypeScript refers to scenarios where the type of a variable is determined at runtime. This can occur when variables are assigned the any type, which allows them to hold values of any type. TypeScript does not perform type-checking on operations involving variables with the any type.

let value: any;
value = 25; // Number
value = "Hello"; // String

While TypeScript is primarily a statically typed language, dynamic typing can still be useful in specific cases, such as:

Working with third-party libraries that lack type definitions.
Interfacing with dynamically structured data (for example, JSON responses from APIs with unknown structures).
Rapid prototyping or when type information is unavailable during the initial development phase.

Static vs. Dynamic Typing in TypeScript

Static typing is significantly more common in TypeScript, as it is one of the core features that sets TypeScript apart from JavaScript. By enforcing strict type checks, static typing enhances code maintainability, reduces bugs, and improves developer productivity.

Dynamic typing is typically reserved for cases where flexibility is required or when dealing with data whose structure cannot be determined in advance. Just keep in mind that relying heavily on dynamic typing (for example, overusing the any type) is generally discouraged, as it undermines the benefits of TypeScript's static typing system.

So while dynamic typing has its place in certain edge cases, static typing is the preferred and more commonly used approach in TypeScript development.

Type Inference and Union Types

Type Inference

Type inference is a powerful TypeScript feature that allows the compiler to automatically deduce the type of a variable based on the value assigned to it during initialization. In simpler terms, TypeScript looks at the value you assign to a variable and decides what type it should be, even if you don’t explicitly declare the type.

For example:

typescriptCopyEditlet age = 25; // TypeScript infers that 'age' is of type 'number'
age = "hello"; // Error: Type 'string' is not assignable to type 'number'

In this example, the age variable is automatically inferred as a number because of its initial value, 25. Any attempt to reassign age to a value of a different type (like a string) will result in a type error.

Type inference is particularly useful because it reduces the need for explicit type annotations, making your code cleaner and more readable. However, it still provides the safety and reliability of TypeScript's type-checking.

When to use type inference:

Simple assignments: Use type inference for straightforward assignments where the type is obvious from the value.
Default values: When providing default values for variables or function parameters, type inference ensures the correct type is applied without requiring manual annotations.
Rapid prototyping: During early stages of development, type inference can reduce boilerplate code while still enforcing type safety.

Union Types

Union types allow a variable to hold values of multiple types. They are defined by placing a pipe (|) between the types. This feature is particularly useful when a variable may legitimately have more than one type during its lifecycle.

For example:

typescriptCopyEditlet numOrString: number | string; // 'numOrString' can hold either a number or a string
numOrString = 25; // Valid
numOrString = "hello"; // Valid
numOrString = true; // Error: Type 'boolean' is not assignable to type 'number | string'

You can even define union types with more than two possible types:

typescriptCopyEditlet multiType: number | string | boolean;
multiType = 42; // Valid
multiType = "TypeScript"; // Valid
multiType = false; // Valid

When to use union types:

Flexible function parameters: When a function can accept multiple types of input.

  typescriptCopyEditfunction printValue(value: string | number) {
    console.log(value);
  }

Handling diverse data structures: When working with APIs or external data sources where fields may vary in type.
Optional or multi-state variables: For example, a variable that can represent a loading state as a boolean, an error as a string, or valid data as an object:
```
  typescriptCopyEditlet status: boolean | string | { success: boolean; data: any };
```

How to Handle Objects, Arrays, and Function Types in TypeScript

To master TypeScript, you must understand the various data types supported in TypeScript and how and when to use them.

The JavaScript primitive types such as strings, numbers, booleans, and more also define the fundamental building blocks of data in TypeScript. But in particular, Objects, Arrays, and Functions are essential for building robust applications. With objects, arrays, and functions, you can better handle data and use them efficiently in development.

Object Types in TypeScript

Object types represent the blueprint for creating objects in TypeScript. You can use objects to define their shape, similar to how classes are used in object-oriented programming (OOP). But objects lack the behavioral aspects and encapsulation that classes offer.

To define an object type, explicitly define the object's blueprint after the colon(:). For Example:

// Object Type Initialization

let student: {
    name: string;
    age: number;
    matricNumber: string | number;
 };

// Assigning the Object with actual data

student = {
    name: "Akande"
    age: 21,
    matricNumber: 21/52 + "HP" + 19,
};

Notice that the properties end with a semi-colon; instead of a comma , which ends them in an actual object.

The above is the primary way to define an object in TypeScript. Another way is to use interfaces, which I’ll cover later in this article.

Array Types in TypeScript

Arrays in TypeScript allow you to store multiple values of the same or different data types in a single variable. They enhance the safety and clarity of your code by enforcing type consistency across the array elements.

In TypeScript, array types can be defined in two ways:

1. Using the `Array` model

This syntax uses the generic Array type, where type represents the type of elements the array can hold.

typescriptCopyEditlet numbers: Array<number> = [1, 2, 3, 4, 5];
let mixedArray: Array<number | string> = [1, 2, 3, 4, 5, "Hello"];

numbers Example: This array can only contain numbers. Attempting to add a string or other type to this array will result in a type error.

  typescriptCopyEditnumbers.push(6); // Valid
  numbers.push("Hello"); // Error: Type 'string' is not assignable to type 'number'

mixedArray Example: This array uses a union type (number | string), allowing it to store both numbers and strings.

  typescriptCopyEditmixedArray.push(42); // Valid
  mixedArray.push("TypeScript"); // Valid
  mixedArray.push(true); // Error: Type 'boolean' is not assignable to type 'number | string'

2. Using the `type[]` model

This syntax appends square brackets ([]) to the type of elements the array can hold.

typescriptCopyEditconst numbers: number[] = [1, 2, 3, 4, 5];
const mixedArray: (string | number)[] = [1, 2, 3, 4, 5, "Hello"];

numbers Example: Similar to the Array example, this array can only hold numbers.

  typescriptCopyEditnumbers[0] = 10; // Valid
  numbers.push("Hi"); // Error: Type 'string' is not assignable to type 'number'

mixedArray Example: Like the earlier mixedArray, this array allows both numbers and strings, providing flexibility where the type of data may vary.

  typescriptCopyEditmixedArray[1] = "World"; // Valid
  mixedArray.push(true); // Error: Type 'boolean' is not assignable to type 'string | number'

How to Use Arrays in TypeScript

Arrays are versatile and commonly used for storing collections of related data. Here are a few practical scenarios:

Storing Homogeneous Data:
When all elements in the array share the same type, such as a list of user IDs or product prices:

typescriptCopyEditconst userIds: number[] = [101, 102, 103];
const productPrices: Array<number> = [29.99, 49.99, 19.99];

Storing Heterogeneous Data:
When elements can have different types, such as a list of messages containing text and optional metadata:

typescriptCopyEditconst messages: (string | object)[] = [
  "Welcome",
  { type: "error", text: "Something went wrong" },
];

Iterating Over Arrays:
Arrays in TypeScript can be used in loops with full type safety:

typescriptCopyEditconst scores: number[] = [80, 90, 70];
scores.forEach((score) => console.log(score + 5)); // Adds 5 to each score

Function Parameters and Return Types:
Arrays can also be passed as function parameters or returned by functions with strict typing:

typescriptCopyEditfunction getNumbers(): number[] {
  return [1, 2, 3];
}
function printStrings(strings: string[]): void {
  strings.forEach((str) => console.log(str));
}

Function Types in TypeScript

Function types in TypeScript describe the shape of functions, including parameter types and return types. Function types are defined by explicitly specifying the parameter types during declaration. The return type is specified by adding : and the type to return immediately after the brackets. For Example:

function addition (a: number, b: number): number {
return a + b;
}

The above function takes in two numbers, adds them, and returns a number. The function will not work if any of its arguments are not numbers and if it returns anything else except a number. For example:

Calling the function with a string as the argument:

// This won't work because it expects numbers, and one of the arguments is a string

addition(1, "two");

Re-writing the function to return a string:

// Function will return an error because it's returning a string

function addition (a: number, b: number): string {
    let result = a + b;
    let returnStatement = `Addition of ${a} and ${b} is: ${result}`;
    return returnStatement;
}

Test the code out for yourself to see how these examples work.

Understanding and effectively handling objects, arrays, and functions in TypeScript empowers you to write type-safe and maintainable code, enhancing the reliability and scalability of your applications.

How to Create Custom Types in TypeScript

Often, your design pattern doesn't follow the built-in data types in TypeScript. For example, you might have patterns that use dynamic programming). And this can cause problems in your codebase. TypeScript offers a solution for creating custom types to address this issue.

Custom types allow you to define your data structure and shapes according to your needs. This enhances code readability and maintainability.

The Type Keyword

The type keyword lets you create type aliases, providing a way to create custom types. The types you create can be reused throughout your codebase. Type aliases help define union types or combine types into single aliases. The syntax for creating a custom type is as follows:

// Syntax

type TypeAlias = type;

And here’s an example:

The code above creates a custom-type UserName, a union of numbers and strings. It uses the type created to define two variables relatively to check if the type works.

Note that it’s recommended to start a type alias starts with a capital letter.

The type Keyword is generally used for primitives – but how about creating a custom object type?

This is where Interfaces come in.

TypeScript Interfaces

Interfaces in TypeScript are used to define the structure of objects. They serve as blueprints, specifying the properties an object should have and their respective types. This ensures that objects conform to a consistent shape, enabling type safety and clearer code.

Defining an interface

An interface is defined using the interface keyword. The syntax looks like this:

typescriptCopyEditinterface InterfaceName {
  property1: Type;
  property2: Type;
}

Example:

typescriptCopyEditinterface User {
  id: number;
  name: string;
  email: string;
}

const user: User = {
  id: 1,
  name: "Alice",
  email: "alice@example.com",
};

Here’s what’s going on in this example:

Interface declaration (interface User):
- Here, we define a blueprint for a User object. It specifies that any object of type User must have the following properties:
  - id of type number
  - name of type string
  - email of type string
Using the interface (const user: User):
- We declare an object user of type User.
- The object is required to have all the properties defined in the User interface, with values of the specified types. If a property is missing or its type doesn't match, TypeScript will throw a compile-time error.

For example:

    typescriptCopyEditconst invalidUser: User = {
      id: 1,
      name: "Alice",
      // Error: Property 'email' is missing in type
    };

So you might be wondering – why should you use interfaces?

Type safety: Ensures that objects conform to the expected structure, preventing runtime errors.
Reusability: The same interface can be reused across different parts of the application, reducing duplication.
Code clarity: Makes the code easier to read and understand by explicitly describing the shape of objects.

Advanced Features of Interfaces

Optional properties: You can make properties optional by adding a question mark (?).

 typescriptCopyEditinterface Product {
   id: number;
   name: string;
   description?: string; // Optional property
 }

 const product: Product = {
   id: 101,
   name: "Laptop",
 }; // Valid, as 'description' is optional

Readonly properties: Use readonly to prevent properties from being modified after initialization.

 typescriptCopyEditinterface Point {
   readonly x: number;
   readonly y: number;
 }

 const point: Point = { x: 10, y: 20 };
 point.x = 15; // Error: Cannot assign to 'x' because it is a read-only property

Extending interfaces: Interfaces can inherit properties from other interfaces, enabling composition.

 typescriptCopyEditinterface Person {
   name: string;
   age: number;
 }

 interface Employee extends Person {
   employeeId: number;
 }

 const employee: Employee = {
   name: "John",
   age: 30,
   employeeId: 1234,
 };

When to Use Interfaces

There are various scenarios when it’s a good idea to use interfaces. You can use them when you want to define and enforce the structure of objects passed around in your code.

They’re also useful in API responses, as they help you type-check objects received from APIs. This ensures that the data conforms to your expectations.

Interfaces are also handy when working with reusable types. When multiple parts of your application use objects with the same structure, interfaces prevent duplication.

By leveraging interfaces, you can create robust, maintainable, and type-safe applications. They are an essential feature of TypeScript that promotes clean and predictable code.

Generics and Literal Types

Generics in TypeScript allow you to create reusable components that can work with various data types. They let you write functions, classes, and interfaces without specifying the exact type upfront, making your code more flexible and maintainable.

Here's an example of a generic function and a generic interface in TypeScript:

// Generic interface for a box that can hold any value 

interface  Box { 
    value: T; 
}

// Usage examples

let  numberBox: Box<number> = { value: 10 };
let  stringBox: Box<string> = { value: "TypeScript" };

console.log(numberBox.value); // Output: 10  
console.log(stringBox.value); // Output: TypeScript

You can use generics when you’re unsure of your data type.

In contrast to Generics, Literal types allow you to specify exact values a variable can hold. This adds increased specificity and type safety to your code, preventing unintended values from being assigned. Here’s an example:

type Direction = 'up' | 'down' | 'left' | 'right';

A variable created with the above type can only be assigned for the strings up, down, left, and right.

Overall, leveraging custom types in TypeScript empowers you to create expressive, reusable, and type-safe data structures, helping you develop more robust and maintainable applications.

How to Merge Types in TypeScript

Merging types in TypeScript combines multiple type declarations into a single, unified type. This capability allows developers to build complex types from smaller, reusable pieces, enhancing code clarity, reusability, and maintainability.

1. Declaration Merging in Interfaces

TypeScript supports declaration merging, where multiple interface declarations with the same name are automatically combined into a single interface. This lets you augment an existing interface by defining additional properties or methods.

Example:

typescriptCopyEditinterface User {
  id: number;
  name: string;
}

interface User {
  email: string;
}

const user: User = {
  id: 1,
  name: "Alice",
  email: "alice@example.com",
};

How it works:

The User interface is declared twice, each with different properties.

TypeScript automatically merges these declarations into a single interface:

  typescriptCopyEditinterface User {
    id: number;
    name: string;
    email: string;
  }

When creating the user object, all properties from the merged interface must be present. If any property is missing, TypeScript will raise an error.

Declaration merging is particularly useful when working with third-party libraries. You can extend or add new properties to an existing interface without modifying the library's source code.

2. Interface Merging Using the `extends` Keyword

The extends keyword allows one interface to inherit properties and methods from another, creating a new interface that combines the properties of both.

Example:

typescriptCopyEditinterface Person {
  name: string;
  age: number;
}

interface Employee extends Person {
  employeeId: number;
}

const employee: Employee = {
  name: "John",
  age: 30,
  employeeId: 101,
};

How it works:

The Person interface defines two properties: name and age.
The Employee interface uses the extends keyword to inherit the properties from Person.
The Employee interface also adds a new property, employeeId.
The employee object must include all properties from both Person and Employee.

This approach is ideal for hierarchical relationships. For instance, you can define a base interface for shared properties and extend it for specialized types.

3. Type Merging Using the `&` Operator

The & operator, known as the intersection type, allows you to combine multiple types into a single type. The resulting type includes all properties and methods from each type.

Example:

typescriptCopyEdittype Address = {
  city: string;
  country: string;
};

type ContactInfo = {
  email: string;
  phone: string;
};

type EmployeeDetails = Address & ContactInfo;

const employee: EmployeeDetails = {
  city: "New York",
  country: "USA",
  email: "john.doe@example.com",
  phone: "123-456-7890",
};

How it works:

Address and ContactInfo are two separate types.
EmployeeDetails is an intersection type created using Address & ContactInfo.
The employee object must include all properties from both Address and ContactInfo. Missing or incorrectly typed properties will result in a TypeScript error.

Intersection types are helpful when you need to combine unrelated types or create composite types for specific use cases, like API responses that merge different data structures.

When to Use Each of These Approaches

Declaration merging: Use when you want to extend or augment an existing interface, particularly in third-party libraries or shared codebases.
extends keyword: Use for hierarchical relationships where a base interface can be specialized into more specific types.
Intersection types (&): Use when you need to combine multiple unrelated types into a single type for specific use cases.

By understanding these merging techniques and their implications, you can structure your TypeScript code effectively, improving reusability and maintainability while maintaining type safety.

Bundling and Transformations in TypeScript

Not every browser supports the latest JavaScript used by TypeScript. So you can use the TypeScript compiler, or tsc, to convert TypeScript code (.ts files) into conventional JavaScript (.js files) that’s universally compatible with all browsers. tsc translates TypeScript-specific elements like types and classes into JavaScript code that browsers can interpret.

To execute TypeScript files, tsc is your go-to. You can install tsc using npm and then transform your .ts files into .js files. To use tsc, just specify the name of the TypeScript file before the tsc command. For instance, if you have a file named app.ts, you can run it by typing:

tsc app.ts

Webpack or Parcel are frequently employed to deploy TypeScript code on browsers. These tools bundle all JavaScript files, including those from TypeScript, for improved performance and easier website implementation. They also optimize code loading by reducing its size and enhancing browser speed.

Building Better Code with TypeScript

Embracing TypeScript as a JavaScript developer opens up possibilities for writing more robust and maintainable code. By understanding the basics and core concepts outlined in this guide, you can leverage TypeScript's static typing system to catch errors early in development, leading to fewer bugs and smoother code maintenance.

By using TypeScript, JavaScript devs can enhance their code quality and productivity. As you continue to explore and practice with TypeScript, you will discover even more powerful features and functionalities.

Keep pushing your boundaries and dive deeper into the world of TypeScript. 😉

How to Handle Complex Use Cases in Your OpenAPI Specifications – API Documentation Guide

Onyeanuna Prince — Mon, 04 Nov 2024 16:44:16 +0000

When you’re documenting an API reference, there are two main approaches you can follow. You can either use the manual approach of filling in the endpoints via a user interface, or organize a structured document containing all the necessary information about your API.

This structured document is called an OpenAPI specification (OpenAPI Spec or OAS).

An OpenAPI spec is a format for describing APIs. It's a blueprint that outlines everything about how an API works — what endpoints are available, what data you can send or receive, and what responses to expect.

This means that a well-written OAS file means well-written API reference documentation.

When writing this file, there are some parts that can get a bit complicated. For example, you might have to document a single endpoint with different methods or sometimes duplicate endpoints.

I encountered and documented both of those use cases. So, in this article, I'll show you how you can do the same. We'll go through each use case with sample OpenAPI specs, and at the end, I'll leave you with some useful tips for documenting your OpenAPI spec files.

Prerequisites
Setting the Foundation
Use Case 1: Duplicate Endpoints
Use Case 2: How to Document Multiple HTTP Methods
API Documentation Tips
Conclusion

Prerequisites

There are a few things you need to know to follow along with the use cases below. These include:

A basic knowledge of APIs and API documentation: Familiarity with API terminology and structure (for example, endpoints, methods, request/response structure) is essential to understand how an OpenAPI Specification (OAS) document functions.
Familiarity with OpenAPI Specification: Basic understanding of OAS, including its purpose, structure, and so on.
Access to Swagger or other OpenAPI documentation tools: You need tools like the Swagger Editor or RapiDoc, which will allow you to test and view the OpenAPI files visually.

Setting the Foundation

In both programming and in life, if you can determine that something is "complex," this means that there's also a simplistic-regular way it can be as well. And that's the same for an OAS file.

When creating your spec file, you might not always encounter the use cases we'll address shortly. That's why it’s useful to know what a conventional spec file looks like.

An OpenAPI spec is a human and machine-readable file written in JSON or YAML. Below is an example of an OAS file structure in YAML format:

paths:
  /users:
    get:
      summary: Get a list of users
      responses:
        '200':
          description: A list of users.
  /users/{userId}:
    get:
      summary: Get details for a single user
      parameters:
 - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Details of a single user.
  /orders:
    get:
      summary: Get a list of orders
      responses:
        '200':
          description: A list of orders.

Here's a brief breakdown of this OAS file structure:

Paths: The paths section allows you to list each endpoint or URL that you can interact with in this API. Each path, such as /users or /orders, shows what type of data you can get or send to that URL.
Operations: Under each path, there's a method or operation, like GET, which tells us what we can do with that endpoint. In this example, each path uses GET, which means you request information.
Summary: Each operation has a summary — a short description explaining what the endpoint does, like "Get a list of users" or "Get details for a single user."
Parameters: For paths that include placeholders, like /users/{userId}, you'll see a parameters section explaining what details are required.
Responses: Each operation includes a responses section, which lists the possible API responses.

NOTE: This is not a complete OAS file. I omitted some preceding information for the purpose of this explanation.

Now, let’s dive into the more complex scenarios.

Use Case 1: Duplicate Endpoints

During the development of an API, you may create a single endpoint with multiple variations. Depending on the use case, you might want that endpoint to accept multiple data formats or specific parameters.

When you encounter such scenarios and want to document the API reference using an OpenAPI spec, you won't be able to replicate it exactly how it is in the Postman collection (or any other development environment).

If you did try, you'll get this error:

The workaround for this problem is to consolidate these multiple variations under a single path definition by grouping the different requests and responses as examples.

In the example below, you have an API that has an endpoint for managing session registration at a conference. This endpoint has various requests and responses based on registration type (for example, Speaker, Attendee, or VIP).

In a Postman collection, you can have each of these endpoints in a separate folder for easy identification and testing.

But when documenting your spec file, it should look like this:

openapi: 3.0.0
info:
  title: Conference Events API
  description: API to manage event registrations for conferences
  version: 1.0.0
paths:
  /register-session:
    post:
      tags:
        - Registration
      summary: Register for a conference session
      description: Register a user for a specific session based on their role, with details provided for each registration type.
      operationId: registerSession
      requestBody:
        description: Registers a user for a session at the conference. It accepts different formats for attendance, speaker, or VIP registrations.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionRegistration'
            examples:
              Attendee:
                summary: Register as an Attendee
                value:
                  userType: Attendee
                  userId: 789
                  sessionId: 1234
                  preferences:
                    seating: General
                    accessLevel: Basic
              Speaker:
                summary: Register as a Speaker
                value:
                  userType: Speaker
                  userId: 456
                  sessionId: 1234
                  preferences:
                    seating: VIP
                    accessLevel: Full
                    presentationEquipment: Projector
              VIP:
                summary: Register as VIP
                value:
                  userType: VIP
                  userId: 123
                  sessionId: 1234
                  preferences:
                    seating: Front Row
                    accessLevel: Full
                    exclusiveAccess: true
      responses:
        '200':
          description: Successful registration for Attendee, Speaker, or VIP
          content:
            application/json:
              schema:
                type: object
                properties:
                  registrationId:
                    type: string
                  success:
                    type: boolean
              examples:
                Attendee:
                  summary: Response for Attendee registration
                  value:
                    registrationId: att-456def
                    success: true
                Speaker:
                  summary: Response for Speaker registration
                  value:
                    registrationId: spk-123abc
                    success: true
                VIP:
                  summary: Response for VIP registration
                  value:
                    registrationId: vip-789ghi
                    success: true
components:
  schemas:
    SessionRegistration:
      type: object
      properties:
        userType:
          type: string
          description: Type of user registering (e.g., Attendee, Speaker, VIP)
        userId:
          type: integer
          description: Unique ID of the user
        sessionId:
          type: integer
          description: Unique ID of the session to register for
        preferences:
          type: object
          properties:
            seating:
              type: string
              description: Seating preference (e.g., General, VIP, Front Row)
            accessLevel:
              type: string
              description: Access level granted (e.g., Basic, Full)
            presentationEquipment:
              type: string
              description: Required equipment for Speakers (only applicable to Speaker)
            exclusiveAccess:
              type: boolean
              description: Exclusive access for VIP users

In this file, you have a single POST /register-session path that captures all registration types without duplicating endpoints.

Here's a visual representation of this OAS file using the Swagger editor:

Use Case 2: How to Document Multiple HTTP Methods

Another use case you may encounter happens when you have the same endpoint but different HTTP methods.

This usually comes up because each method serves a different purpose, even though they share the same path.

For example, a GET method retrieves information about a resource, like viewing a user's registration details for a conference session.

On the other hand, a PATCH method updates specific fields for that same user registration, like updating their seat preference.

Since both the GET and PATCH methods relate to the same resource (/register-session in our example), the way around this is to group them under the same path. This way, you'll be documenting two separate methods for a single path.

In OpenAPI, each combination of a path and method is called an "operation". Grouping operations that share the same path helps maintain clearer and more structured documents.

Using the conference events API example, this is what your OAS file should look like:

openapi: 3.0.0
info:
  title: Conference Events API
  description: API to manage event registrations for conferences
  version: 1.0.0
paths:
  /register-session:
    get:
      tags:
        - Registration
      summary: Retrieve a registration for a conference session
      description: Fetch details for a specific user's registration, like seat assignment and access level.
      operationId: getSessionRegistration
      parameters:
        - in: query
          name: userId
          schema:
            type: integer
          required: true
          description: The ID of the user whose registration you want to retrieve.
      responses:
        '200':
          description: Registration details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionRegistration'
              example:
                userId: 789
                sessionId: 1234
                preferences:
                  seating: General
                  accessLevel: Basic
                  exclusiveAccess: false

    patch:
      tags:
        - Registration
      summary: Update a registration for a conference session
      description: Update specific fields for a user's session registration, such as seating or access level.
      operationId: updateSessionRegistration
      requestBody:
        description: Allows updating fields for a specific session registration.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSessionPreferences'
            example:
              userId: 789
              preferences:
                seating: VIP
                accessLevel: Full
                exclusiveAccess: true
      responses:
        '200':
          description: Registration updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
              example:
                success: true
                message: "Registration updated successfully."
components:
  schemas:
    SessionRegistration:
      type: object
      properties:
        userId:
          type: integer
          description: Unique ID of the user
        sessionId:
          type: integer
          description: Unique ID of the session
        preferences:
          type: object
          properties:
            seating:
              type: string
              description: Seating preference (e.g., General, VIP, Front Row)
            accessLevel:
              type: string
              description: Access level granted (e.g., Basic, Full)
            exclusiveAccess:
              type: boolean
              description: Exclusive access granted to certain users

    UpdateSessionPreferences:
      type: object
      properties:
        userId:
          type: integer
          description: Unique ID of the user
        preferences:
          type: object
          properties:
            seating:
              type: string
              description: New seating preference (e.g., VIP)
            accessLevel:
              type: string
              description: Updated access level (e.g., Full)
            exclusiveAccess:
              type: boolean
              description: Updated access preference (e.g., true or false)

In this file, you have a single /register-session path with multiple methods. We define just one path, /register-session, and list the GET and PATCH methods under it. This keeps the spec clean, reduces duplication, and shows that these methods relate to the same resource.

Here's a visual representation of this OAS file using the Swagger editor:

API Documentation Tips

While working with OpenAPI specifications, there are some useful tricks and tips that can make your OAS file more readable and maintainable.

Use Markdown in OpenAPI

OpenAPI specifications allow the use of Markdown in the description field. The version of Markdown used in OAS is called CommonMark, the same version used in GitHub.

Markdown formatting allows you to make text more visually engaging and organized. You can add formatting such as headers, lists, code blocks, bold, italics, and so on, which can make your documentation easier to scan and more accessible for readers.

For example, if you need to emphasize certain parts of an endpoint's purpose or highlight important details, Markdown lets you do it naturally.

You can add Markdown directly into any description field in the OpenAPI file, like this:

paths:
  /register-session:
    get:
      description: |
        ## Retrieve Session Registration
       Retrieves the registration details for a specific user.  
       - **Note:** This data includes seat assignment and access level.  
       - Example of JSON response: `{"userId": 789, "sessionId": 1234, "seating": "General"}`
      responses:
        '200':
          description: Registration details retrieved successfully

When deployed to supported documentation platforms like RapiDoc or ReadMe, this will render beautifully with all your Markdown styling intact.

Here's a deployed version of this example in Readme:

Use the `operationId` Field

The operationId field is an optional field in OpenAPI specs that assigns a unique name to each API operation.

It is an identifier that you can use to call specific methods when integrating with SDKs or when linking between parts of your documentation.

By effectively using the operationId, you make it much easier for developers to reference specific actions in the API, which is especially helpful when the API is complex or has multiple endpoints.

Place the operationId inside each HTTP method block to give it a unique identifier. For instance:

paths:
  /register-session:
    get:
      operationId: getSessionRegistration
      description: Retrieve a registration for a conference session
      responses:
        '200':
          description: Successfully retrieved the registration
    patch:
      operationId: updateSessionRegistration
      description: Update a registration for a conference session
      responses:
        '200':
          description: Registration updated successfully

With the operationId, developers can directly refer to getSessionRegistration or updateSessionRegistration as function calls in code or API clients.

Use `$ref` for Reusable Components

The $ref keyword in OpenAPI lets you create and reuse components across your spec file. This technique is especially helpful when you have similar request bodies, responses, or parameters repeated in multiple endpoints.

By defining components in a single place and referencing them as needed, you avoid redundancy, reduce errors, and facilitate updates.

So, instead of updating the same parameter across multiple locations, you update it once in the reusable component, and every endpoint using it gets the update.

To use it, first define the reusable component in the components section of your OpenAPI file, then reference it elsewhere using $ref:

components:
  schemas:
    RegistrationDetails:
      type: object
      properties:
        userId:
          type: integer
        sessionId:
          type: integer
        seating:
          type: string
paths:
  /register-session:
    post:
      summary: Register for a session
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegistrationDetails'
      responses:
        '201':
          description: Successfully registered for the session

In this file, RegistrationDetails is defined once and is referenced using the $ref keyword in the /register-session operation.

Conclusion

In this article, you learned how to resolve some complex use cases you might encounter when documenting your API reference using an OpenAPI specification. We went through what to do when you have a single endpoint with multiple methods or duplicate endpoints.

Creating your API reference without an OpenAPI spec file is a manual approach that can become redundant if you have to replicate it across various platforms. But by relying on the tips from the article, you're sure to create better, more efficient, and more reusable OpenAPI specifications. And these, in turn, will lead to better API documentation.

How to Build a Documentation Site using React and Docusaraus

Chisom Uma — Wed, 09 Oct 2024 16:56:14 +0000

Having a properly designed and comprehensive documentation site is important for any project. But creating good documentation can be challenging, and problems like poor user onboarding experience and increased support tickets can become daily hassles for a team.

This is why documentation tools like Docusaurus are great for helping you create visually stunning documentation sites in abo 5 minutes.

In this tutorial, I'll show you how to build a documentation site using React and Docusaurus.

If you are new to Docusaurus, you are probably wondering, “why React?, why not any other framework like Next.js?”, Don’t worry – I’ll also answer this question in this guide.

Prerequisites
What is Docusaurus?
Getting Started and Installation
- Project structure
How to Start Your Docusaurus Website
How to Create Documentation (Overview)
MDX and React Components
Docusaurus Blog
Custom Pages
Styling in Docusaurus
Deployment
Conclusion

Prerequisites

To follow along with this guide, you should have:

Node.js version 18.0 or above installed
Basic knowledge of React and Markdown
IDE (preferably VSCode)

What is Docusaurus?

Docusaurus was released by the Meta Open Source team in 2017 to help devs build, deploy, and maintain documentation websites easily and quickly. The project’s other goal was to improve the speed of both developers and end users using the PRPL pattern.

Some of its cool features include search and localization, powered by Algolia (search) and Crowdin (language support and internationalization).

Now, let’s talk about why we’re using React for this tutorial. Well, Docusaurus is built on top of React, which makes it easy to customize the website. Also, Docusaurus supports Markdown and MDX (which lets you use React JSX in your markdown content).

As a technical writer myself, I love that this tool supports Markdown, which I'm quite familiar with. It allows me to focus on creating helpful documentation without worrying about converting the text to other text formats.

Getting Started and Installation

Getting started with Docusaraus is pretty straightforward. The first thing you need to do is head over to your terminal and run the command below:

npx create-docusaurus@latest my-website classic

Note: The Docusaurus team recommends the classic template because it is easier to get started with fast. It also contains @docusaurus/preset-classic – which includes standard documentation, a blog, custom pages, and a CSS framework (with dark mode support).

Project structure

After installation, this is what your newly created Docusaurus project structure should look like:

📦my-website
┣ 📂blog
┃ ┣ 📂2021-08-26-welcome
┃ ┃ ┣ 📜docusaurus-plushie-banner.jpeg
┃ ┃ ┗ 📜index.md
┃ ┣ 📜2019-05-28-first-blog-post.md
┃ ┣ 📜2019-05-29-long-blog-post.md
┃ ┣ 📜2021-08-01-mdx-blog-post.mdx
┃ ┣ 📜authors.yml
┃ ┗ 📜tags.yml
┣ 📂docs
┃ ┣ 📂tutorial-basics
┃ ┃ ┣ 📜congratulations.md
┃ ┃ ┣ 📜create-a-blog-post.md
┃ ┃ ┣ 📜create-a-document.md
┃ ┃ ┣ 📜create-a-page.md
┃ ┃ ┣ 📜deploy-your-site.md
┃ ┃ ┣ 📜markdown-features.mdx
┃ ┃ ┗ 📜_category_.json
┃ ┣ 📂tutorial-extras
┃ ┃ ┣ 📂img
┃ ┃ ┃ ┣ 📜docsVersionDropdown.png
┃ ┃ ┃ ┗ 📜localeDropdown.png
┃ ┃ ┣ 📜manage-docs-versions.md
┃ ┃ ┣ 📜translate-your-site.md
┃ ┃ ┗ 📜_category_.json
┃ ┗ 📜intro.md
┣ 📂src
┃ ┣ 📂components
┃ ┃ ┗ 📂HomepageFeatures
┃ ┃ ┃ ┣ 📜index.js
┃ ┃ ┃ ┗ 📜styles.module.css
┃ ┣ 📂css
┃ ┃ ┗ 📜custom.css
┃ ┗ 📂pages
┃ ┃ ┣ 📜index.js
┃ ┃ ┣ 📜index.module.css
┃ ┃ ┗ 📜markdown-page.md
┣ 📂static
┃ ┣ 📂img
┃ ┃ ┣ 📜docusaurus-social-card.jpg
┃ ┃ ┣ 📜docusaurus.png
┃ ┃ ┣ 📜favicon.ico
┃ ┃ ┣ 📜logo.svg
┃ ┃ ┣ 📜undraw_docusaurus_mountain.svg
┃ ┃ ┣ 📜undraw_docusaurus_react.svg
┃ ┃ ┗ 📜undraw_docusaurus_tree.svg
┃ ┗ 📜.nojekyll
┣ 📜.gitignore
┣ 📜babel.config.js
┣ 📜docusaurus.config.js
┣ 📜package.json
┣ 📜README.md
┗ 📜sidebars.js

Now, let’s explore some of the main directories:

blog/: This is where you store your blog posts
docs/: As the name implies, this is where your documentation projects are kept
src/: This directory allows you to customize your website further using React code.
static: Here, you store static files like images, logos, favicons, and so on.

A very important file is the docusaurus.config.js file, which acts as the main configuration file for your website.

How to Start Your Docusaurus Website

To run your website locally, first open a new terminal on your IDE and run the following command below to start the development server:

cd my-website

npm i

npx docusaurus start

After running the above command, the browser compiles the React and Markdown files and starts a local development server at http://localhost:3000/. Docusaurus enables hot reload, so you can see changes made to your React, Markdown, and MDX files automatically – without reloading your entire app.

Here is what the site looks like on your browser:

In the image above, you are first welcomed to an intuitive and easily navigable website. At the top left corner of the website, you will see the “Tutorial” and “Blog” sections.

Tutorial: This is where users can see the live version of your documentation.
Blog: This is where users can see the live version of your blog.

The link to the Docusaurus Open Source GitHub repo and the icon for toggling your website between light and dark modes are at the top-right corner of the site.

Alternatively, you can use docusaurus.new to test Docusaurus quickly in a playground without having to go through the installation process. Here, you have an option to choose between CodeSandbox and StackBlitz.

How to Create Documentation (Overview)

Let’s take a closer look at our docs folder. If we head back to our local site and click on “Tutorial,” we will see some pre-built doc pages, as shown below:

These documentation pages are reflected in the docs folder located in your IDE. When we open the category.json page, we can adjust the name or position of each page. This means you don’t have to name the folders the same as the page name, since the name of the file will be the URL of the page.

To create our new documentation, let’s use the following steps:

Delete all the files in the docs folder. Your browser and terminal will typically display an error after this.

This is because we need at least one page in the docs folder.
Create a new file inside the docs folder, which can be named anything you prefer, but in our case, I named it single-page.md. You should see this change immediately reflected when you go to your local website. This is what you will see in the documentation pages section:

Inside this newly created file, you can create your documentation seamlessly. The image above shows the little Markdown content I created saying “Single Page” in an H1 and “This is a single page” in plain text.

Let’s say you want to create a more organized content structure, but you don’t know how to get started. Here are a few simple steps on how to do that:

Create a new folder inside the docs folder, named “Getting Started”
Create new Markdown files inside the “Getting started” folder, and name them whatever you like. For the sake of this tutorial, let’s name it API-docs.md and Session-replay.md.
Write your documentation in Markdown

This is how the file structure should look like on your IDE:

📦docs
┣ 📂Getting started
┃ ┣ 📜Open-replay.md
┃ ┗ 📜Session-replay.md
┗ 📜single-page.md

Here is a simple GIF to demonstrate how this works on the local documentation website.

Now, let’s try to create a separate page in the doc folder. To do this, let’s create a category.json page in the Getting started folder. Inside the category.json file, we will include the following JSON text:

{
  "label": "Custom Title",
  "position": 2,
  "link": {
    "type": "generated-index",
    "description": "This is a custom description"
  }
}

The link object creates a separate page for the folder.
The type property is set to generated-index, which means it will generate the pages with all the sub-pages.
The description property is a description of the page that will show up beneath the title.

When you check out your local hosted documentation site, you will see that the label has changed, and a separate page has been created for the folder.

In this section, I will show you an example of how headings and tables of content work in Docusaurus.

The first thing I did was create a markdown.md file. Then I pasted a couple of headings in Markdown text format right inside the file, like this:

---
title: Basic Markdown
sidebar_position: 1
---

# Heading 1

## Heading 2

### Heading 3

#### Heading 4

##### Heading 5

###### Heading 6

When we head back to our website, we can see that only headings level 2 and 3 are automatically added, just as shown below:

We can edit to ensure that all the headings show up. To do this, first create a table-of-contents.md, then paste in the following Markdown:

---
title: Table of Contents
sidebar_position: 2
toc_min_heading_level: 2
toc_max_heading_level: 6
---

import TOCInline from '@theme/TOCInline';

<TOCInline toc={toc} minHeadingLevel={2} maxHeadingLevel={6} />

## Heading 2

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed non risus. Suspendisse lectus tortor, dignissim sit amet, adipiscing nec, ultricies sed, dolor.

### Heading 3

Some content here.

#### Heading 4

Some content here.

##### Heading 5

Some content here.

###### Heading 6

Some content here.

## Heading 2

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed non risus. Suspendisse lectus tortor, dignissim sit amet, adipiscing nec, ultricies sed, dolor.

### Heading 3

Some content here.

#### Heading 4

Some content here.

##### Heading 5

Some content here.

###### Heading 6

Some content here.

## Heading 2

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed non risus. Suspendisse lectus tortor, dignissim sit amet, adipiscing nec, ultricies sed, dolor.

### Heading 3

Some content here.

#### Heading 4

Some content here.

##### Heading 5

Some content here.

###### Heading 6

Some content here.

I added a TOC property and set the minimum and maximum heading levels with toc_min_heading_level: 2 and toc_max_heading_level: 6. We also added an inline table of contents by first importing TOCInline from @theme/TOCInline. Then, we created a TOCInline component (which can be put anywhere you want your TOC to show up).

Now, all the headings show up in the table of contents part of the website:

Beautiful right?

MDX and React Components

Now, let’s talk about one of the most exciting features of Docusaurus: MDX and React components.

You might ask – how can Docusaurus use TOC or import in the Markdown file? Well, that’s because Docusaurus uses MDX, which is basically Markdown with JSX.

To demonstrate this, let’s create a new Markdown file inside our Getting started folder titled MDX.md , then we create a separate file inside the src > components folder and name the file Tag.js . Then we paste in the following code:

import React from 'react';

export default function Tag({ children, color }) {
  return (
    <span
      style={{
        backgroundColor: color,
        borderRadius: '4px',
        color: '#fff',
        padding: '0.2rem 0.5rem',
        fontWeight: 'bold',
      }}
    >
      {children}
    span>
  );
}

Here, we first imported the core React library, and then we defined a functional component called Tag, which takes in two props as input: children and color. In our return statement, we included our CSS styles for the span element.

Inside the MDX.md file, paste in the below code:

---
title: MDX
sidebar_position: 3
---

import Tag from '@site/src/components/Tag';

<Tag color="#FF5733">ImportantTag> information: This is an <Tag color="#3399FF">ExcitingTag> example of custom components!

I can write **Markdown** alongside my _JSX_!

Here, we import Tag from our components folder. This is what it looks like:

Note: Because we use MDX, Docusaurus comes with pre-built components like Tabs, alerts, code blocks, and more. Let’s check them out in the following subsections.

Tabs

In this subsection, we’ll talk about tabs as a pre-built component in Docusaurus. Let’s dive right in!

For a start, let’s create a new Markdown file called tabs.md and paste in the following code:

---
title: Tabs in Markdown
sidebar_position: 4
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="book" label="Book" default>
    Dive into the world of knowledge with a captivating book 📚
  TabItem>
  <TabItem value="painting" label="Painting">
    Admire the strokes of artistry on a beautiful painting 🖼️
  TabItem>
  <TabItem value="music" label="Music">
    Let the soothing melodies of music transport you 🎶
  TabItem>
Tabs>

I'm a text that doesn't belong to any tab. So I'm always visible.

We imported Tabs from @theme/Tabs and TabItem from @theme/TabItem. Then, we created a Tabs component, which is the container, and the TabItem component is the tab itself. The value property is the value of the tab, while the label property is the label of the tab. The default property defines which tab is open by default – in this case, the “Book” tab.

This is how it looks:

Each tab is clickable and transitions smoothly.

Alerts or Admonitions

Docusaurus comes with pre-built alerts or admonitions. To create an alert, you simply wrap the text with three colons and follow it with the type of alert you want the reader to have in mind.

Let’s create a new Markdown file called alerts.md and paste in the following Markdown:

---
title: Alerts or Admonitions
sidebar_position: 5
---

:::note

Here's some **information** with _Markdown_ styling.

:::

:::tip

Here's a **helpful tip** with _formatted text_.

:::

:::info

Here's some **useful info** presented in a clear way.

:::

:::caution

Please take **extra caution** with this important note.

:::

:::danger

This is a **dangerous situation** you need to be aware of.

:::

:::note This is a _custom title_

And you can add images as well.

![alt text](https://picsum.photos/600/400)

:::

The various types of alerts, as shown in the Markdown above, are:

note
tip
info
caution
danger

Here’s what it looks like on the website:

Alerts and admonitions are pretty common in documentation sites. So, if you have ever wondered how it’s been done, well, this is it! It’s quite straightforward.

Code blocks

As we already know by now, Docusaurus supports MDX, which allows us to include code blocks in our files. Code blocks are text blocks wrapped around by strings of three backticks. You can add the name of the language after the last of the three backticks.

Let’s create a codeblocks.md file and paste the following JSX code:

---
title: Codeblocks
sidebar_position: 6
---

```jsx title="Codeblock"
function Greeting(props) {
  return Welcome, {props.userName}!;
}

export default Greeting;
```

```jsx title="Highlight Lines"
function HighlightText(highlight) {
  if (highlight) {
    // highlight-next-line
    return 'This text is highlighted!';
  }
  return 'Nothing highlighted';
}

function HighlightMoreText(highlight) {
  // highlight-start
  if (highlight) {
    return 'This range is highlighted!';
  }
  // highlight-end
  return 'Nothing highlighted';
}
```

```jsx title="Line Numbers" showLineNumbers
import React from 'react';

function UserProfile(props) {
  const { username, email, isAdmin } = props;

  return (
    
      User Profile
      Username: {username}
      Email: {email}
      {isAdmin && Admin User}
    
  );
}

export default UserProfile;
```

```jsx title="Line Numbers with Highlight" {4,9-11} showLineNumbers
import React from 'react';

function UserProfile(props) {
  const { username, email, isAdmin } = props;

  return (
    
      User Profile
      Username: {username}
      Email: {email}
      {isAdmin && Admin User}
    
  );
}

export default UserProfile;

This is what the code blocks look like:

You can easily copy the code by hovering your cursor over the code blocks and clicking on the copy icon on the top-right side of the code block.

Note: By default, Docusaurus uses Prism for syntax highlighting.

If you also want to highlight some lines of code, you can do that by adding a comment like this:

    // highlight-next-line
    return 'This text is highlighted!';
  }
  return 'Nothing highlighted';
}

function HighlightMoreText(highlight) {
  // highlight-start
  if (highlight) {
    return 'This range is highlighted!';
  }
  // highlight-end

highlight-next-line: allows you to highlight a single line of code
highlight-start and highlight-end: allows you to highlight a range of lines

Docusaurus Blog

The Docusaurus blog also comes by default with the classic template. If you don’t have a blog, you can add the following lines to your docusaurus.config.js file:

{
  label: 'Blog',
  to: '/blog',
}

Usually, this line should already be in your config file after installing Docusaurus for the first time.

The Docusaurus blog is very simple to understand. Navigate to the blog folder in the project explorer, and you’ll see all the blog posts, which are MDX files. The blog post date should be included on the file name as shown below:

When you open one of the blog posts, you see something like this:

---
slug: long-blog-post
title: Long Blog Post
authors: yangshun
tags: [hello, docusaurus]
---

This is the summary of a very long blog post,

Use a `` comment to limit blog post size in the list view.



Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

slug: You can add a slug to the URL of the blog post
title: Title of the blog post
authors: The authors of the blog post
tags: Tags related to the blog post

In the blog post, we can also use all the Markdown features plus JSX as we have seen before.

Custom Pages

Technically, Docusaurus isn’t just a fancy documentation site generator with a blog. It’s a standard static site generator – which means you can create any page you want.

To see how creating a custom page in Docusaurus works, let’s create an about.js file in the src > pages folder and include the following code:

import React from 'react';
import Layout from '@theme/Layout';
import Head from '@docusaurus/Head';

export default function About() {
  return (
    <Layout>
      <Head>
        <title>Abouttitle>
        <meta name="description" content="This is the about page" />
      Head>

      <div>
        <h1 className="red-text">Abouth1>
        <p>This is the about page.p>
      div>
    Layout>
  );
}

When you go to http://localhost:3000/about, you should see something like this:

We can also add the page to the navbar by going to the docusaurus.config.js file and adding a new item to the navbar array. The item looks like this:

{to: 'about', label: 'About', position: 'left'},

It then appears on the homepage nav menu like this:

You can now style and customize the about.js file any way you’d prefer using React.

Styling in Docusaurus

Let’s look at how you can style your site in Docusaurus. The easiest way is to customize the custom.css file inside the css > custom.css file. This is what the file looks like:

Here, you can change the whole color schema of the site and different styling to this file.

You can read more about this in the Docusaurus styling and layout docs.

SEO in Docusaurus

Docusaurus takes SEO very seriously. By default, Docusaurus automatically adds a description title, canonical URL links, and other useful metadata to each page. This can be configured as shown below:

---
title: Our First Page
sidebar_position: 1

description: A short description of this page
image: ../static/img/docusaurus-social-card.jpg
keywords: [keywords, describing, the main topics]
---

# Single Page

This is a single page.

You can read more about this in the Docusaurus SEO docs.

Deployment

Deployment is pretty easy with Docusaurus. Since it’s a static site, you can deploy it to any static site hosting service. To do this, run the npm run build command on your CLI. This creates a build folder like the one below:

Then, you can upload the contents of the build folder to your hosting service.

Conclusion

In this article, we covered how to build documentation from scratch, how to create, customize, and style pages, and the awesome SEO power of Docusaurus.

Docusaurus is friendly to both developers and technical writers. As a developer, you can focus on customizing the site, while as a technical writer, you can focus on writing the documentation.

I will highly recommend this tool for both startups and established enterprises looking to build stunning documentation sites.

This guide is not exhaustive, but covers everything you need to know about the basics of building a documentation site with React and Docusaurus.

I hope you found it helpful :)

Here’s the link to my GitHub code for follow-up purposes.

And here’s the main Docusaurus documentation if you’d like to dive in deeper.

Technical writing - freeCodeCamp.org

How to Use Documentation as a Marketing Tool

Table of Contents

The Role of Documentation in a User's Journey

How to Build Trust at the Moment of Highest Intent

So, What Actually Builds Trust in Documentation?

Documentation and Marketing: A Partnership

So, how can marketing help documentation?

And...how can good documentation help marketing?

Practical Implications: Treating Docs as Marketing

1. Documentation should ship with product launches

2. Invest in documentation quality and discoverability

3. Create an integrated content experience

4. Measure documentation impact on conversion

Why does all this matter now?

Conclusion

How to Use to Docker with Node.js: A Handbook for Developers

Prerequisites

Table of Contents:

What is a Container?

Where Do Containers Live?

Docker vs Virtual Machines

Docker Installation

Basic Docker Commands

How to Specify a Version of an Image:

How to Stop, Start, and Remove a Container

How to Restart a Container

How to Run Multiple Redis Containers and Understanding Ports

Trying to Run Another Redis Container on the Same Port

What is Port Binding?

Running a Second Redis Container on a Different Host Port

Why Port Binding Exists

How to Explore a Container

docker run vs docker start

Practice with JavaScript

How to Pull the MongoDB Image

How to Pull the Mongo Express Image

Docker Network

How to Run the Mongo Container

How to Run the Mongo Express Container

How to Connect Node.js to MongoDB

Node.js Backend

Frontend

How to Use Docker Compose

Why Use Docker Compose?

How to Build Our Own Docker Image

Running Your Node.js App Container

Troubleshooting Errors

Why This Happens:

The Solution

Why mongodb Works

Rebuild Your Docker Image

Add Your App to Docker Compose

Start All Services

Verify Everything Works

What Changed and Why It Works

How to Manage Your Containers

How to Create a Private Docker Repository

Step 1: Get Your AWS Access Keys

Step 2: Check if AWS CLI is installed

Step 3: Configure AWS CLI with your credentials

Step 4: Test your AWS configuration

Step 5: Login to ECR (Docker Registry)

Understanding Image Naming in Docker Repositories

Step 6: Build, Tag, and Push your image

Assignment: Create and Push a New Version of Your App

Deploying Our Image

Why Must We Use the Full Image URL for ECR?

Deploy Your App Using Docker Compose

Sharing our Private Docker Image

1. Grant IAM Access

2. Install and Configure AWS CLI

3. Authenticate Docker with ECR

4. Pull the Image

5. Run the Container

Docker Volumes

How Docker Volumes Work

Types of Docker Volumes

1. Named Volumes

2. Bind Mounts

`docker run` vs `docker start`

Why `mongodb` Works