Modern browsers make this much easier than before.

Instead of uploading files to a server, we can now process images directly in the browser using JavaScript. This keeps the tool fast, private, and easy to use.

In this tutorial, you’ll build a browser-based Image to PDF converter using JavaScript.

The tool will support uploading multiple images, sorting files, choosing orientation and page size, configuring margins, and merging images into either a single PDF or separate PDF files. Users will also be able to preview and download the generated document directly in the browser.

Everything runs entirely client-side without any backend.

Table of Contents

1. How Image to PDF Conversion Works

2. Project Setup

3. What Library Are We Using?

4. Creating the Upload Interface

5. Reading Uploaded Images

6. Generating the PDF

7. Handling Multiple Images

8. Configuring PDF Settings

9. Renaming and Downloading the PDF

10. Demo: How the Image to PDF Tool Works

11. Important Notes from Real-World Use

12. Common Mistakes to Avoid

13. Conclusion

How Image to PDF Conversion Works

The browser can't directly combine images into a PDF by itself.

Instead, we'll use a JavaScript PDF library that creates pages, inserts images, and exports everything as a downloadable PDF document.

The process starts when users upload one or multiple images into the browser. JavaScript then reads the image data and prepares it for PDF generation. After that, the tool creates PDF pages, inserts the uploaded images into those pages, and finally exports everything as a downloadable PDF document.

Everything happens locally inside the browser.

This means users don’t need to upload private files to a server, which makes the process faster and more privacy-friendly.

Project Setup

This project is intentionally simple.

You only need:

• an HTML file

• a JavaScript file

• a PDF library

No backend or database is required.

What Library Are We Using?

We’ll use the jsPDF library. It allows us to generate PDF files directly in JavaScript.

Add it using a CDN:

<script src="https://cdnjs.cloudflare.com/ajax/libs/jspdf/2.5.1/jspdf.umd.min.js"></script>

Once loaded, we can create and export PDF files directly from the browser.

Creating the Upload Interface

Start with a basic upload area:

<input type="file" id="upload" multiple accept="image/*">

<button onclick="convertToPDF()">
  Convert to PDF
</button>

This allows users to upload multiple image files and generate the PDF.

Here’s what the upload section looks like inside the tool:

You can also expand the interface with additional controls for sorting, page settings, margins, and merge modes.

Reading Uploaded Images

After users select files, we need to read them in JavaScript.

We can use FileReader for this:

const fileInput = document.getElementById("upload");

const files = fileInput.files;

for (const file of files) {
  const reader = new FileReader();

  reader.onload = function (e) {
    const imageData = e.target.result;

    console.log(imageData);
  };

  reader.readAsDataURL(file);
}

This converts uploaded images into readable Base64 data that can later be inserted into the PDF.

Generating the PDF

Now we can create the PDF document.

const { jsPDF } = window.jspdf;

const pdf = new jsPDF();

Once the PDF is created, images can be inserted into pages:

pdf.addImage(imageData, "JPEG", 10, 10, 180, 120);

This inserts the uploaded image into the PDF page at a specific position and size.

Finally, export the document:

pdf.save("images.pdf");

This downloads the generated PDF instantly.

Handling Multiple Images

If users upload multiple files, each image can be added to its own PDF page automatically.

For example:

files.forEach((file, index) => {

  if (index !== 0) {
    pdf.addPage();
  }

});

This creates a new page before inserting the next image into the document.

In some situations, users may also want multiple images on the same page instead of one image per page.

For example:

pdf.addImage(img1, "JPEG", 10, 20, 80, 80);

pdf.addImage(img2, "JPEG", 110, 20, 80, 80);

This allows more flexible layouts for galleries, reports, or grouped documents.

Configuring PDF Settings

Before generating the final PDF, users can customize several layout and output settings.

These settings improve document quality and give users more control over the generated file.

Here’s what the configuration panel looks like inside the tool:

Sorting Images

When multiple images are uploaded, organizing them properly becomes important before generating the PDF.

Users may want to sort images alphabetically, reverse the order, or arrange them based on file size.

For example, images can be sorted alphabetically like this:

files.sort((a, b) => a.name.localeCompare(b.name));

You can also sort files by size:

files.sort((a, b) => a.size - b.size);

Here’s an example of sorting options inside the tool:

This helps users organize documents more efficiently before converting them into a PDF.

Choosing Orientation

Different images work better in different page orientations.

Portrait orientation works well for vertical images, while landscape orientation is better for wider images.

For example:

const pdf = new jsPDF({
  orientation: "portrait"
});

You can also switch to "landscape" when needed.

Here’s an example of orientation options inside the tool:

Selecting Page Size

PDF page size controls the dimensions of the generated document.

For example:

const pdf = new jsPDF({
  unit: "mm",
  format: "a4"
});

This creates an A4-sized PDF document using millimeter units.

Other formats like letter, legal, or custom page sizes can also be supported.

Here’s an example of selecting page size options inside the tool:

Adding Margins

Margins create spacing between the image and the edges of the page.

Without margins, images may touch the borders and appear cramped.

For example:

const margin = 10;

pdf.addImage(imageData, "JPEG", margin, margin, 180, 120);

Here’s an example of margins options inside the tool:

This creates cleaner spacing around the inserted image.

Automatic Image Fitting

One common issue when generating PDFs from images is incorrect sizing.

If images are inserted with fixed dimensions, they may stretch, overflow outside the page, or appear distorted.

Instead, it’s better to calculate image dimensions dynamically.

For example:

const pageWidth = pdf.internal.pageSize.getWidth();

const imgWidth = pageWidth - 20;

const imgHeight = (image.height * imgWidth) / image.width;

pdf.addImage(imageData, "JPEG", 10, 10, imgWidth, imgHeight);

This automatically scales images proportionally while maintaining margins and layout consistency.

Merge Options

One useful feature is allowing different output modes.

For example, users may want to merge all uploaded images into a single PDF document when creating reports, notes, or combined files.

In some cases, users may prefer generating separate PDFs for each image instead of combining everything together. This can be useful when exporting individual documents or scanned pages.

Custom grouping is another helpful option because it allows users to combine selected images into multiple PDFs based on their own arrangement or categories.

These different output modes make the tool much more flexible for different real-world use cases.

A simple selection dropdown works well:

<select id="mergeMode">
  <option>Merge all into Single PDF</option>
  <option>Create Separate PDFs</option>
  <option>Custom Grouping</option>
</select>

Once selected, JavaScript can apply different generation logic based on the chosen mode.

Here’s an example of merge mode options inside the tool:

This makes the tool more flexible for handling different document workflows.

Renaming and Downloading the PDF

After generating the document, users may want to rename the file before downloading.

You can prompt for a filename like this:

const fileName = prompt("Enter PDF name:", "images");

pdf.save(`${fileName}.pdf`);

This gives users more control over the exported file.

Here’s an example of the rename popup inside the tool:

Demo: How the Image to PDF Tool Works

Step 1: Upload Images

Users upload one or multiple image files into the browser-based tool.

The tool supports common formats like JPG, PNG, and WEBP.

Step 2: Configure PDF Settings

Users can customize layout settings before generating the PDF.

This includes:

• sorting images

• orientation

• page size

• margins

• merge mode

These settings help create cleaner PDF output.

Step 3: Generate the PDF

Once settings are configured, users click the convert button.

The browser processes all uploaded images locally and generates the PDF instantly.

Step 4: Rename the Generated File

Before downloading, users can rename the generated PDF.

This improves organization when exporting multiple documents.

Step 5: Download the PDF

Finally, the generated PDF becomes available for download directly in the browser.

The entire process works without uploading files to any server.

Important Notes from Real-World Use

When working with large images, performance and memory usage become important.

Large images can slow down PDF generation and create unnecessarily large output files.

For example, you can limit upload size before processing:

const MAX_SIZE = 10 * 1024 * 1024;

if (file.size > MAX_SIZE) {
  alert("Image is too large.");
  return;
}

Another useful optimization is resizing images before inserting them into the PDF.

For example:

const canvas = document.createElement("canvas");

const ctx = canvas.getContext("2d");

canvas.width = image.width * 0.5;
canvas.height = image.height * 0.5;

ctx.drawImage(image, 0, 0, canvas.width, canvas.height);

const resizedImage = canvas.toDataURL("image/jpeg", 0.7);

This reduces image dimensions and compression quality before generating the PDF.

It also helps reduce memory usage and improves PDF generation speed for large files.

Since everything runs directly inside the browser, uploaded images never leave the user’s device, which improves privacy.

Common Mistakes to Avoid

One common mistake is not validating uploaded files before processing them.

For example, users may upload unsupported formats or attempt to generate a PDF without selecting images.

Always validate input before processing:

if (!fileInput.files.length) {
  alert("Please upload images first.");
  return;
}

Another issue is inserting very large images without resizing them first.

Large images can create oversized PDFs and reduce performance significantly.

Incorrect image positioning is also common.

If dimensions are hardcoded incorrectly, images may overflow outside the page or become distorted.

Using dynamic image sizing and margins helps prevent these layout issues.

Conclusion

In this tutorial, you built a browser-based image to PDF converter using JavaScript.

You learned how to upload images, generate PDF documents, configure layout settings, and export files directly inside the browser.

More importantly, you saw how modern browsers can handle document generation locally without relying on a backend server.

This approach keeps the tool fast, private, and easy to use.

Once you understand this workflow, you can extend it further with features like compression, drag-and-drop sorting, watermarking, batch exports, or advanced PDF editing tools.

You can also try a full working version here:

https://allinonetools.net/image-to-pdf-converter/

And that’s where things start getting really interesting.

Most Django tutorials teach you session-based authentication. That works fine when your frontend and backend live on the same server. But the moment you separate them – say, a React app on Netlify talking to a Django API on PythonAnywhere – then sessions start to break down.

Cookies don't travel well across different domains, and suddenly your login system stops working.

That's where JSON Web Tokens (JWT) come in. JWTs give you a stateless, cookie-free way to authenticate users. They work seamlessly across domains, devices, and platforms. The server doesn't need to remember anything. It just verifies the token's signature and knows exactly who's making the request.

But authentication is only half the problem. Once you know who a user is, you still need to control what they can see. This is where scoping comes in.

Scoping means ensuring that each user can only access their own data. User A should never be able to read, edit, or delete User B's data (notes in our case), even if they somehow guess the right ID.

In this tutorial, you'll build a a personal note-taking API where users can register, log in with JWT tokens, and store notes that only they can access.

Along the way, you'll implement a custom user model, configure SimpleJWT for token-based authentication, and write scoped views that lock each user's data behind their own credentials.

What We'll Cover:

• Prerequisities

• What is JWT and Why Use It Over Session Authentication?

  • How Session Authentication Works

  • How JWT Authentication Works

• Step 1: How to Set Up the Project and Install the Dependecies

  • 1.1 How to Create the Project

  • 1.2 How to Create a Virtual Environment and Install the Required Dependencies

  • 1.3 How to Create the Project and the App

  • 1.4 How to Register the App and Django Rest Framework (DRF)

• Step 2: How to Create a Custom User Model

  • 2.1 How to Define the Custom User Model

  • 2.2 How to Tell Django to Use Your Custom User Model

  • 2.3 How to Run Migrations

• Step 3: How to Define the Note Model

  • 3.2 How to Apply Migration

  • 3.3 How to Register Models in the Admin

• Step 4: How to Create the Serializer

  • 4.1 How to Create UserSerializer

  • 4.2 How to Create NoteSerializer

• Step 5: How to Configure SimpleJWT

  • 5.1 How to Update REST Framework Settings

  • 5.2 How to Add Token URL Endpoints

• Step 6: How to Build the Authentication Logic

• Step 7: How to Implement Scoped Views

  • 7.1 How to Create a NoteViewSet

  • 7.2 Why This Matters: Preventing ID Enumeration Attacks

• Step 8: How to Connect a URL

  • 8.1 How to Create App-level URLs

  • 8.2 How to Verify the Project-Level URLs

• Step 9: How to Test the APIs with Postman

  • 9.1 How to Register a User

  • 9.2 How to Obtain Access and Refresh Tokens

  • 9.3 How to Create a Note

  • 9.4 How to List Your Notes

  • 9.5 How to Demostrate Scoping

• Step 10: How to Handle Token Expiration with Refresh Tokens

• How You Can Improve This Project

• Conclusion

Here's what this tutorial covers:

1. How to set up a custom user model (and why you should always do this)

2. How to configure SimpleJWT for access and refresh token authentication

3. How to build serializers that protect sensitive fields

4. How to scope your API views so users only see their own data

5. How to test the entire flow using Postman

Let's get started

Prerequisities

Before you begin, make sure you're comfortable with the following:

1. Django fundamentals: You should understand how Django projects and apps work, including models, views, URLs, and migrations.

2. Django REST Framework basics: You should be familiar with serializers, viewsets or API views, and how DRF handles requests and responses.

3. Basic command line usage: You'll run commands in your terminal throughout this tutorial.

Tools you'll need installed:

• Python 3.8 or higher

• pip (Python's package manager)

• A code editor like Visual Studio Code

• Postman (or any API testing tool) for testing your endpoints. You'll use this to send requests to your API.

What is JWT and Why Use It Over Session Authentication?

Before you write any code, it's important to understand what problem JWTs solve and why Django's built-in session authentication isn't always enough.

How Session Authentication Work

Django ships with a session-based authentication system. Here's how it works at a high level:

1. A user sends their username and password to the server.

2. The server verifies the credentials and creates a session which is a small record stored in the server's database that says "this user is logged in."

3. The server sends back a session ID as a cookie. The browser stores this cookie automatically.

4. On every subsequent request, the browser sends the cookie back to the server. The server looks up the session ID in its database and says "ah, this is User A. Let them through."

This works perfectly when your frontend and backend live on the same domain. The browser handles cookies automatically, and Django manages sessions in the database without you thinking about it.

But this approach has some limitations.

1. The cross-domain problem: If your React frontend lives at app.example.com and your Django API lives at api.example.com, cookies become tricky. Browsers enforce strict rules about which domains can send and receive cookies.

   You can work around this with CORS (Cross-Origin Resource Sharing) headers and special cookie settings, but it adds complexity and can be fragile.

2. The scalability problem: Every active session is stored in the server's database. If you have 10,000 users logged in at the same time, that's 10,000 session records the server has to look up on every single request. As your application grows, this lookup becomes a bottleneck.

3. The mobile problem: Mobile apps don't handle cookies the same way browsers do. If you're building an API that will serve both a web app and a mobile app, session cookies create extra headaches.

How JWT Authentication Works

JWTs take a fundamentally different approach. Instead of storing session data on the server, they put the authentication information directly into the token itself.

Here's how the flow works:

1. A user sends their username and password to the server.

2. The server verifies the credentials and creates a JWT – a long encoded string that contains information like the user's ID and when the token expires.

3. The server sends this token back to the client. The client stores it (usually in memory or local storage).

4. On every subsequent request, the client includes the token in the request header. The server reads the token, verifies its signature, and says "this is User A. Let them through."

Notice the key difference: the server never stores anything.

It doesn't look up a session in a database. It simply reads the token, checks its cryptographic signature to make sure nobody tampered with it, and extracts the user information. That's why JWTs are called stateless – the server doesn't maintain any state about who is logged in.

This solves the cross-domain problem because tokens are sent in the request header, not as cookies. Headers work the same way regardless of which domain the request comes from.

This solves the scalability problem because the server doesn't store sessions. Verifying a token is a quick cryptographic check, not a database lookup.

This solves the mobile problem because any client that can send HTTP headers can use JWT. Mobile apps, desktop apps, other servers – they all work the same way.

Step 1: How to Set Up the Project and Install the Dependecies

1.1 How to Create the Project

Open your terminal, navigate to where you want your project to live, and run the following commands:

mkdir notes-project

cd notes-project

1.2 How to Create a Virtual Environment and Install the Required Dependencies

You will create a virtual environment here. Type the following command:

python3 -m venv venv

The above command creates a virtual environment inside a folder called venv. The first venv is the command and the second venv represents the name of the folder. You can name the folder anything though venv is usually preferred.

To activate the virtual environment, we need to use the following command:

On macOS/Linux:

source venv/bin/activate

On Windows:

venv\Scripts\activate

You'll know it worked when you see (venv) at the beginning of your terminal prompt. From this point on, any Python packages you install will only exist inside this virtual environment.

With the virutal environment activated, install Django, Django Rest Framework, and Simple JWT Framework using the command:

pip install django djangorestframework djangorestframework-simplejwt 

You can verify everything installed correctly by running:

pip list

You should see all three packages listed along with their dependencies.

1.3 How to Create the Project and the App

Run the following command to create the Django project:

django-admin startproject notes_core .

The dot at the end is important. It tells Django to create the project files in your current directory instead of creating an extra nested folder.

Now let's type this command to create the app:

python manage.py startapp notes

1.4 How to Register the App and Django Rest Framework (DRF)

Open notes_core/settings.py and add rest_framework and notes in the INSTALLED_APPS list:

Django now knows about your new app and the REST framework. Let's move on to the most important architectural decision you'll make for this project.

Step 2: How to Create a Custom User Model

If you've built Django projects before, you might have used Django's default User model. For quick prototypes, that works fine. But for any project you plan to grow or maintain, starting with a custom user model is a best practice you should never skip.

Here's why: Django's default User model uses a username field as the primary identifier. If you later decide you want users to log in with their email address instead, or you need to add a profile picture field, or a phone number, then you're stuck.

Using a custom user model gives you full control over what a "user" means in your app. Instead of being tied to a username, you can design login around something more practical, like email or phone_number for a fitness or mobile-based app. You can also include fields like role (doctor, patient, receptionist in a clinic system) or date of birth directly in the user model, instead of managing a separate profile.

It also helps future-proof your project. If you start with the default model and later decide to switch login from username to email, or add required fields, it becomes difficult and risky to change. Using a custom user model from the beginning avoids this problem and makes it much easier to adapt your authentication system as your app grows.

By creating a custom user model from the start, even if it's identical to the default one, you give yourself the freedom to make changes later without any of that pain.

2.1 How to Define the Custom User Model

Open notes/models/py and add the following code:

from django.contrib.auth.models import AbstractUser
from django.db import models

class CustomUser(AbstractUser):
    pass

You are importing Django’s built-in AbstractUser class.

Think of AbstractUser as a ready-made blueprint for a user. It already includes fields like username, password, email, first name, last name , and authentication logic.

The pass statement means you're not adding any extra fields yet.

But the key point is that this model is yours. So this model behaves exactly like Django’s default user model, but with one big advantage: you now have the flexibility to customize it later.

If three months from now you need to add a phone_number field or switch to email-based login, you just add a field to this class and run a migration.

from django.contrib.auth.models import AbstractUser
from django.db import models

class CustomUser(AbstractUser):
    phone_number = models.CharField(max_length=15)

You can also see all the fields that the CustomUser class has inherited from the AbstractUser class.

To do this we can use the Python shell. Type the following command:

python manage.py shell

When you type this command, make sure that the virtual environment is active:

After this, import the CustomUser model in the shell:

from notes.models import CustomUser

After that, type the following code:

[fields.name for field in CustomUser._meta.get_fields()]

The above statement lists out all the fields in the CustomUser class.

2.2 How to Tell Django to Use Your Custom User Model

Now comes the important bit. Open notes_core/settings.py and add this line:

AUTH_USER_MODEL = 'notes.CustomUser'

This setting tells Django to use your CustomUser model instead of the built-in one for everything authentication-related such as login, permissions, foreign keys, and so on.

There's no strict rule to where you need to add it, but the best practice is to add it near the end of the file.

You can see which user model Django is using by using the method get_user_model().

Open the Python shell again and import the get_user_model() method:

from django.contrib.auth import get_user_model 

Then use get_user_model() and print the output:

user = get_user_model()
print(user)

You should see the name of our model being used:

If you hadn't added the AUTH_USER_MODEL in the settings.py file, then Django would have used the default user model:

Note: You'll need to do this before you run your first migration. If you run migrate before setting AUTH_USER_MODEL, Django creates tables for the default User model, and switching afterward becomes a headache.

2.3 How to Run Migrations

Now create and apply the initial migrations:

python manage.py makemigrations
python manage.py migrate

Django will create the necessary tables for your custom user model along with all the built-in Django tables.

We can again peek under the hood to see the SQL queries that Django used to create the tables especially the CustomUser table.

Type this command:

python manage.py sqlmigrate notes 0001

Here notes is the name of the app and 0001 represents the migration number.

And you should get this output:

Let's also create a superuser so you can access the admin panel later for debugging:

python manage.py createsuperuser

Fill in the username, email (optional), and password when prompted.

Step 3: How to Define the Note Model

Now let's create the data model for the core of your application. First add a new import to use the settings object.

from django.conf import settings

Then add the following code below the CustomUser class:

class Notes(models.Model):
    owner = models.ForeignKey(
        settings.AUTH_USER_MODEL,
        on_delete=models.CASCADE,
        related_name='notes'
    )
    title = models.CharField(max_length=200)
    body = models.TextField()
    created_at = models.DateTimeField(auto_now_add=True)
    def __str__(self):
        return f"{self.title} (by {self.owner.username})"

Here's the complete model.py code:

from django.contrib.auth.models import AbstractUser
from django.db import models
from django.conf import settings

class CustomUser(AbstractUser):
    pass

class Notes(models.Model):
    owner = models.ForeignKey(
        settings.AUTH_USER_MODEL,
        on_delete=models.CASCADE,
        related_name='notes'
    )
    title = models.CharField(max_length=200)
    body = models.TextField()
    created_at = models.DateTimeField(auto_now_add=True)
    def __str__(self):
        return f"{self.title} (by {self.owner.username})"

Let's walk through each field:

1. owner = models.ForeignKey(settings.AUTH_USER_MODEL, ...): Creates a relationship between each note and a user. The ForeignKey field tells Django that each note belogs to exactly one user but a user can have many notes.

   Notice that we use settings.AUTH_USER_MODEL instead of directly importing CustomUser. This is the recommended practice because it keeps your code flexible. If you ever change the user model reference in settings, this foreign key adapts automatically.

   The on_delete=models.CASCADE means that if a user is deleted, all their notes are deleted too.

   The related_name='notes' lets you access a user's notes with user.notes.all().

2. title = models.CharField(max_length=200): Creates a text field for the task name, limited to 200 characters.

3. body = models.TextField(): Holds the actual note content. TextField has no character limit, so users can write as much as they need.

4. created_at = models.DateTimeField(auto_now_add=True): Automatically records the date and time when a task is created. You never need to set this manually.

   The __str__() method gives each note a readable representation. Instead of seeing "Note object (1)" in the admin panel or during debugging, you'll see something like "Meeting Notes (by Solina)."

3.2 How to Apply Migration

Run the migration commands to create the Note table:

python manage.py makemigrations
python manage.py migrate

As before, we can see the exact SQL query Django used to create the notes table:

3.3 How to Register Models in the Admin

Open notes/admin.py and register both models so you can inspect data through the admin panel:

from django.contrib import admin
from .models import CustomUser, Notes

admin.site.register(CustomUser)
admin.site.register(Notes)

This is helpful during development when you want to quickly check whether data is being saved correctly.

Step 4: How to Create the Serializer

In DRF, a serializer is like a bridge between your database and the internet.

Django models store data as Python objects. But when you want to send that data to a frontend application (like React or a mobile app), you can't send Python objects. You need to send a format that everyone understands which is usually JSON.

Serializers perform three main jobs:

1. Serialization: Converting complex Python objects (Models) into Python dictionaries (which can be easily rendered into JSON).

2. Deserialization: Converting JSON data coming from a user back into complex Python objects.

3. Validation: Checking if the incoming data is correct before saving it to the database.

4.1 How to Create UserSerializer

Create a new file called notes/serializers.py and add the following code:

from rest_framework import serializers
from django.contrib.auth import get_user_model

User = get_user_model()
class UserSerializer(serializers.ModelSerializer):
    password = serializers.CharField(write_only=True)

    class Meta:
        model = User
        fields = ['id', 'username', 'email', 'password']

    def create(self, validated_data):
        user = User.objects.create_user(
            username=validated_data['username'],
            email=validated_data.get('email', ''),
            password=validated_data['password']
        )
        return user

Let's break down this serializer.

1. The UserSerializer handles user registration.

2. User = get_user_model() gets the user model that you're using and stores in the variable User. In our case, we're using the CustomUser model

3. class UserSerializer(serializers.ModelSerializer):: Here you've created the UserSerializer class, which inherits ModelSerializer.

   A ModelSerializer is a shortcut that automatically creates a serializers class with fields that are in the model class.

   When we use a ModelSerializer, DRF inspects the model and automatically does these things:

   1. Generates fields from the model so you don't have to
   2. Automatically adds field validations that are present in the model
   3. Implements create() and update() methods. A ModelSerializer knows which model to use and how to update and create it. You can override create() and update() methods if you need customized behaviors. You have overridden the create() method in the above code.

4. password = serializers.CharField(write_only=True): This line is crucial. The write_only=True flag means the password will be accepted during registration but will never appear in any API response. Without this, your API would send back the password (even if hashed) every time user data is returned.

   So users can create accounts, but their passwords are never exposed back.

5. class Meta: Inside the Meta class, you tell the serializer which model to use. In this case, the model to use is User and the fields to be handled.

6. The create() method: This is the most important part. This method runs when we create a new user. Instead of using the default .create() method you have overridden it.

   It's important to understand why we have overridden this method. The default create() method is not suitable for creating users securely.

   By default this method stores the password in plain text format. This is a serious problem because passwords should never be stored in raw form. They need to be hashed so that even if the database is compromised, the passwords are never exposed.

   Django provides a special method called create_user() that automatically handles this by hashing the password and setting up the user properly for authentication.

4.2 How to Create NoteSerializer

After the UserSerializer class, let's create the NoteSerializer class. The NoteSerializer handles the notes data

First of all, you need to add an import to the Notes class. Add the line from .models import Notes at the end of the last import.

Put this code below the UserSerializer class:

class NoteSerializer(serializers.ModelSerializer):
    owner = serializers.ReadOnlyField(source='owner.username')
    class Meta:
        model = Notes
        fields = ['id', 'owner', 'title', 'body', 'created_at']

Now let's break it down:

1. owner = serializers.ReadOnlyField(source='owner.username'): This is the most important line in the code. This makes the owner field read-only. That means the API will display who owns a note (showing their username), but no one can set or change the owner through the API.

   Without this protection, a malicious user could send a POST request with "owner": 5 and assign their note to someone else's account, or worse, modify someone else's notes by reassigning ownership.

   The source='owner.username' part tells DRF to display the owner's username instead of their numeric ID, which makes the API responses more readable.

2. class Meta: ...: As before the Meta class contains the model which the serializer use and the fields that the API will expose.

   Here is the complete code in the serializers.py file

from rest_framework import serializers
from django.contrib.auth import get_user_model
from .models import Notes

User = get_user_model()
class UserSerializer(serializers.ModelSerializer):
    password = serializers.CharField(write_only=True)
    class Meta:
        model = User
        fields = ['id', 'username', 'email', 'password']

    def create(self, validated_data):
        user = User.objects.create_user(
            username=validated_data['username'],
            email=validated_data.get('email', ''),
            password=validated_data['password']
        )
        return user

class NoteSerializer(serializers.ModelSerializer):
    owner = serializers.ReadOnlyField(source='owner.username')
    class Meta:
        model = Notes
        fields = ['id', 'owner', 'title', 'body', 'created_at']

Step 5: How to Configure SimpleJWT

Now let's set up the authentication system. This is where you tell DRF to use JWT for authentication instead of sessions. This step is crucial because without it, DRF will default to session-based auth.

SimpleJWT provides a complete JWT implementation for DRF, so you don't have to build token generation, signing, or verification from scratch.

The access token is what your client sends with every API request. It's short-lived by design. Think of it like a visitor badge at an office building: it gets you through the door, but it expires at the end of the day. If someone steals it, the damage is limited because it stops working soon.

The refresh token is longer-lived and has a single purpose: getting a new access token when the current one expires. The client stores it securely and only sends it to one specific endpoint. Think of it like your employee ID card. You use it to get a new visitor badge each morning, but you don't flash it at every door.

This separation exists for security. If the short-lived access token is compromised (which is more likely since it's sent with every request), the attacker has a narrow window before it expires. The refresh token, which is sent less frequently, has a lower risk of interception.

Let's look at how the access and refresh token work together

1. User logs in, server gives both access token and refresh token

2. User makes requests using the access token

3. Access token expires

4. App sends refresh token to server

5. Server checks it and gives a new access token

6. User continues without logging in again

5.1 How to Update REST Framework Settings

Open notes_core/settings.py and add the following code:

from datetime import timedelta
REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': (
        'rest_framework_simplejwt.authentication.JWTAuthentication',
    ),

    'DEFAULT_PERMISSION_CLASSES': (
        'rest_framework.permissions.IsAuthenticated',
    ),
}

SIMPLE_JWT = {
    'ACCESS_TOKEN_LIFETIME': timedelta(minutes=30),
    'REFRESH_TOKEN_LIFETIME': timedelta(days=1),
}

Let's unpack what each section does.

The DEFAULT_AUTHENTICATION_CLASSES setting tells DRF to use JWT as the authentication method for all API endpoints. Every incoming request will be checked for a valid JWT token in the Authorization header.

The DEFAULT_PERMISSION_CLASSES setting sets IsAuthenticated as the global permission policy. This means every endpoint in your API is locked down by default. Only users with a valid token can access any endpoint.

This is a secure-by-default approach: instead of remembering to protect each view individually, everything is protected, and you explicitly open up the endpoints that need to be public (like the registration endpoint, which you'll handle in the next step).

The SIMPLE_JWT dictionary controls token behavior. The access token lasts 30 minutes. This is the token clients include in every request. If someone intercepts it, the damage is limited to a 30-minute window. The refresh token lasts one day.

When the access token expires, the client can use the refresh token to get a new access token without forcing the user to log in again. The duration of the refresh token is 1 day. This means after 1 day, the user must log in again with their username and password. You'll see exactly how this works later when you test with Postman.

5.2 How to Add Token URL Endpoints

SimpleJWT provides ready-made views for obtaining and refreshing tokens. You just need to wire them up to URLs.

Open notes_core/urls.py and update it with the following code:

from django.contrib import admin
from django.urls import path, include
from rest_framework_simplejwt.views import (
    TokenObtainPairView,
    TokenRefreshView,
)

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/', include('notes.urls')),
    path('api/token/', TokenObtainPairView.as_view(), name='token_obtain_pair'),
    path('api/token/refresh/', TokenRefreshView.as_view(), name='token_refresh'),
]

The token/ endpoint accepts a username and password, and returns an access token and a refresh token.

The token/refresh/ endpoint accepts a refresh token and returns a new access token. You'll see these in action during testing.

Step 6: How to Build the Authentication Logic

Open notes/views.py and add the following:

from rest_framework import generics, permissions
from django.contrib.auth import get_user_model
from .serializers import UserSerializer

User = get_user_model()

class RegisterView(generics.CreateAPIView):
    queryset = User.objects.all()
    serializer_class = UserSerializer
    permission_classes = [permissions.AllowAny]

Now let's walk through this code.

The first section are the imports and after that we have used the the get_user_model() method to get the CustomUser model.

Now the main part is RegisterView class. The class inherits from generics.CreateAPIView which is a built in DRF view designed specifically for handling POST requests that create new objects.

Because of this, you don’t have to manually write the logic for handling POST requests, validating data, or saving to the database. DRF does all of that for you behind the scenes.

Inside the class, queryset = Users.objects.all() defines the set of user objects this view can work with.

The serializer_class = UserSerializer tells the view which serializer to use for validating incoming data and creating the user.

Finally permission_classes = [permissions.AllowAny] overrides the global IsAuthenticated permission you set earlier in the value of DEFAULT_PERMISSION_CLASSES .

This means that anyone can access the registration endpoint, even if they aren't logged in. This makes sense for a registration endpoint because new users won’t have accounts yet.

Every other view in your API will inherit the global IsAuthenticated permission, so only this registration endpoint is open.

Step 7: How to Implement Scoped Views

This is the heart of the tutorial. You've set up authentication so the API knows who is making a request. Now you need to make sure each user can only interact with their own notes.

Think of it this way: authentication is the lock on the front door of an apartment building. It keeps strangers out. But scoping is the lock on each individual apartment. Just because you live in the building doesn't mean you can walk into your neighbor's apartment.

Without scoping, an authenticated user could potentially see every note in the database, or worse, modify notes that belong to someone else. Two method overrides on your viewset prevent this entirely.

7.1 How to Create a NoteViewSet

Now let's create the NoteViewSet. First add these imports to the top of the file. We're importing the viewsets, serializers, and model.

from .models import Note
from .serializers import UserSerializer, NoteSerializer
from rest_framework import generics, viewsets, permissions

Add the following to notes/views.py, below the RegisterView:

class NoteViewSet(viewsets.ModelViewSet):
    serializer_class = NoteSerializer

    def get_queryset(self):
        return Notes.objects.filter(owner=self.request.user).order_by('-created_at')

    def perform_create(self, serializer):
        serializer.save(owner=self.request.user)

Now let's talk about this code in detail.

You've created a new class called NoteViewSet which inherits from the DRF class ModelViewSet. This gives you full CRUD operations, meaning you can list notes and retrieve a single note, as well as create, update, and delete a note.

The next part serializer_class = NoteSerializer tells Django to use the NoteSerializer class to convert between Python objects and JSON.

But the magic is the two methods that you are overriding: get_queryset() and perform_create().

The get_queryset() method controls which notes the API returns. If you didn't override this method, it would return Note.objects.all() (which would give every user access to every note in the database).

But here, you've overridden this method so that it filters notes by the current user.

Next is the perform_create() method, which is called when the note is saved. You've overridden this method so that it saves the notes of the user who's currently logged in. If you hadn't overridden the this method, it would return all the notes regardless of the logged in user.

Notice that you have passed self.request.user parameters in to the filter() function. This is the code that attaches the logged-in user as the owner of the note.

Remember how you made the owner field read-only in the serializer? This is the other half of that security measure.

The user can't set the owner through the API request, and the server automatically sets it to whoever is authenticated. These two pieces work together to make ownership tamper-proof.

7.2 Why This Matters: Preventing ID Enumeration Attacks

Without get_queryset filtering, your API might allow something like this: a user sends a GET request to /api/notes/42/ and sees a note that belongs to someone else, simply because they guessed the ID.

This is called an ID enumeration attack — an attacker cycles through IDs (1, 2, 3, 4...) to discover and access other people's data.

With your scoped get_queryset, even if User B sends a request to /api/notes/42/ and note 42 belongs to User A, the viewset won't find it in User B's filtered queryset. DRF will return a 404 — as far as User B is concerned, that note doesn't exist.

Step 8: How to Connect a URL

Now you need to wire up the views to URL paths so the API knows which view to call for each endpoint.

8.1 How to Create App-level URLs

Create a new file called notes/urls.py and add the following:

from django.urls import path, include
from rest_framework.routers import DefaultRouter
from .views import RegisterView, NoteViewSet

router = DefaultRouter()
router.register(r'notes', NoteViewSet, basename='note')

urlpatterns = [
    path('register/', RegisterView.as_view(), name='register'),
    path('', include(router.urls)),
]

The DefaultRouter automatically generates URL patterns for the NoteViewSet. Since you're using a ModelViewSet, the router creates endpoints for listing all notes, creating a note, retrieving a single note, updating a note, and deleting a note — all from that single router.register call.

The basename='note' parameter is required here because your viewset doesn't have a queryset attribute defined directly on the class (you're using get_queryset instead). DRF uses the basename to generate the URL pattern names like note-list and note-detail.

8.2 How to Verify the Project-Level URLs

Make sure your notes_core/urls.py looks like this (you set this up in Step 5, but let's confirm):

from django.contrib import admin
from django.urls import path, include
from rest_framework_simplejwt.views import (
    TokenObtainPairView,
    TokenRefreshView,
)

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/', include('notes.urls')),
    path('api/token/', TokenObtainPairView.as_view(), name='token_obtain_pair'),
    path('api/token/refresh/', TokenRefreshView.as_view(), name='token_refresh'),
]

Here's the full picture of your API's URL structure:

Start the development server to make sure everything runs without errors:

python manage.py runserver

If the server starts without complaints, your code is wired up correctly.

Step 9: How to Test the APIs with Postman

Building the API is one thing. Proving it works is another. Let's walk through the entire flow using Postman, from registering a user to demonstrating that scoping actually works.

If you haven't used Postman before, it's a tool that lets you send HTTP requests to your API and inspect the responses. You can download it from postman.com/downloads.

Alternatively, you can use curl from the command line or any other API testing tool you're comfortable with.

Make sure your development server is running before proceeding.

9.1 How to Register a User

Open Postman:

Create a new request:

Click Send. You should get a 201 Created response with the user data (without the password, thanks to your write_only=True field) which you wrote in the UserSerializer class.

9.2 How to Obtain Access and Refresh Tokens

Now log in to get your JWTs:

You'll get a response with access and refresh tokens.

Copy the access token. You'll need it for every subsequent request. Also save the refresh token, as you'll use it later.

A JWT is only encoded and not encrypted. The encoding is merely a way to transform the data into a safe, standard string format that can be easily transmitted over the internet.

Any one can peel through the encoding to see the data. This is done using base64url encoding.

We can use the Python library pyjwt to decode JWTs or use any of the online sites to decode. It's important to note that you should use online sites with caution since JWTs may contain sensitive information.

For this demo, we'll use site called jwt.io.

Open the site and paste in the access token that you have just created:

The JWT has three parts: the header, the payload, and the signature.

The header sections tells you how the header is signed. In this case it is signed using the HS256 algorithm.

The payload is where the actual data or claim lives. It contains standard claims such as token types, expiration time ( exp ), issued at time ( iat ), and custom claims.

The signature section is used to verify integrity. You can't decode it to meaningful data. This section ensures that the token wasn't tampered with.

9.3 How to Create a Note

Now use the access token to create a note:

Notice that you don't include an owner field. That's handled automatically by perform_create. You should get a 201 Created response:

You can create a few more notes, so that we have some data to work with.

9.4 How to List Your Notes

Now to fetch all of Priya's notes:

You should see all the notes created, sorted by most recent first.

9.5 How to Demonstrate Scoping

Let's prove that a second user can't view the first user's notes.

First, register the second user.

Send a POST request to http://127.0.0.1/api/register with the following data:

Then get tokens for Sujan by sending a POST request to http://127.0.0.1:8000/api/token/ with Sujan's credentials (username and password) and then copy Sujan's access token.

Now send a GET request to http://127.0.0.1:8000/api/notes/ using Sujan's token in the Authorization header.

The response should be an empty list since this user hasn't created any notes:

More importantly, Priya's notes are completely invisible to him. Even if Sujan tries to access a specific note by ID – say, http://127.0.0.1:8000/api/notes/1/ – he'll get a 404 Not Found response, not a 403 Forbidden.

This is intentional. A 404 Not Found doesn't reveal that the note exists, while a 403 Forbidden would confirm its existence to a potential attacker.

A 403 Forbidden response is like a door with a sign: “Authorized personnel only”. You now know something important is inside. A 404 Not Found response is like a blank wall. You don’t even know a room exists.

Now that you know why we've used the 404 response instead of 403, let's demonstrate this.

First, I'll access Priya's individual note using her credentials and her access token:

Now, I'll change the access token and put Sujan's (new user) access token:

You can see that using the new user's token to access the previous user's note leads to 404 Not Found response.

Step 10: How to Handle Token Expiration with Refresh Tokens

Access tokens are deliberately short-lived (30 minutes in your configuration). This limits the window of damage if a token is stolen.

But you don't want users to re-enter their credentials every 30 minutes. That's what refresh tokens are for.

When Priya's access token expires, her API requests will start returning 401 Unauthorized responses. Instead of logging in again, the client sends the refresh token to get a fresh access token.

Replace your old access token with this new one, and you're good for another 30 minutes. The refresh token itself lasts for one day, so the user only needs to fully log in again once every 24 hours.

In a real application, the frontend client handles this automatically. When an API call returns a 401, the client catches it, sends the refresh token to get a new access token, and retries the original request — all without the user noticing.

Here's what that flow looks like in pseudocode:

1. Client sends request with access token

2. Server responds with 401 (token expired)

3. Client sends refresh token to /api/token/refresh/

4. Server responds with a new access token

5. Client retries the original request with the new access token

6. Server responds with the data

   

If the refresh token itself has expired (after 24 hours in your configuration), step 4 will also return a 401. At that point, the user truly needs to log in again with their username and password. This is the intended behavior: it means even a stolen refresh token has a limited useful life.

How You Can Improve This Project

This API is functional and secure, but there's plenty of room to build on it. Here are some directions you could take.

1. Add search and filtering. Let users search their notes by title or body text. You can use DRF's SearchFilter and django-filter to add query parameters like ?search=meeting to the notes list endpoint.

2. Add categories or tags. Create a Category model and add a foreign key to Note, or use a many-to-many relationship for tags. This would let users organize their notes and filter by category.

3. Add pagination. Once a user has hundreds of notes, returning them all in a single response becomes slow. DRF has built-in pagination classes that let you return notes in pages of 10, 20, or whatever size you choose.

4. Deploy to a production server. The API currently runs on your local machine. You could deploy it to platforms like PythonAnywhere, Railway, or Render to make it accessible from anywhere. You'd need to configure a production database (like PostgreSQL), set a secure SECRET_KEY, and serve the application behind HTTPS.

5. Build a frontend. Connect a React, Next.js, or Vue.js frontend to this API. Store the JWTs in the client and implement the token refresh flow so users stay logged in seamlessly.

6. Add token blacklisting. SimpleJWT supports token blacklisting, which lets you invalidate refresh tokens when a user logs out. Without this, a refresh token remains valid until it expires, even after the user "logs out."

Each of these improvements builds on the patterns you've already learned and will deepen your understanding of Django, DRF, and API design.

Conclusion

You've built a fully functional, secure note-taking API with Django, Django REST Framework, and SimpleJWT. Along the way, you learned some fundamental concepts that apply to any API you'll build in the future.

You started with a custom user model — a small decision at the beginning that saves you from a painful migration later. You configured JWT authentication so your API can serve mobile clients and decoupled frontends that can't rely on session cookies.

You built serializers that protect sensitive data by keeping passwords write-only and ownership read-only. Most importantly, you implemented scoped views that ensure each user's data is completely isolated from everyone else's.

The patterns you practiced here — overriding get_queryset to filter by the current user, overriding perform_create to assign ownership automatically, and using read-only fields to prevent data tampering — are the same patterns you'll use in production APIs handling real user data.

The best way to solidify what you've learned is to keep building. Try adding search and filtering, build a React frontend that consumes this API, or start a completely new project may be a task manager, a journal app, or a bookmarks API using the same JWT and scoping patterns. The core workflow stays the same. Only the models and business logic change.

The gap between "I know Python syntax" and "I can build a working web app" can feel enormous. But it does not have to be.

In this tutorial, you'll build a fitness tracker web application from scratch using Django, one of the most popular Python web frameworks. By the end, you'll have a fully functional app running live on the internet – something you can show to friends, add to your portfolio, or keep building on.

Here's what you'll learn:

• How Django projects and apps are structured

• How to define database models to store workout data

• How to create views that handle user requests

• How to build HTML templates that display your data

• How to connect URLs to views so users can navigate your app

• How to deploy your finished app to PythonAnywhere so anyone can access it

The app itself is straightforward: you can log a workout by entering an activity name, duration, and date. You can then view all your logged workouts on a separate page. It's simple, but it covers the core Django concepts you need to build much bigger things later.

Let's get started.

Table of Contents

• Prerequisites

• What You Are Going Build

• Step 1: How to Set Up Your Django Project

  • 1. 1 How to create a virtual environment

  • 1.2 How to install Django

  • 1.3 How to Create the Project

  • 1.4 How to run the development server

• Step 2: How to Create a Django App

  • 2.1 How to Generate the App

  • 2.2 How to Register the App

• Step 3: How to create a Workout Model

  • 3.1 How to Define the Model

• Step 4: How to Apply Migrations

  • 4.1 How to Generate the Migration

  • 4.2 How to Apply the Migration

• Step 5: How to Register the Model in the Admin Panel

  • 5.2 How to Create a Superuser

  • 5.3 How to Access the Admin Panel

• Step 6: How to Create Views for the App

  • 6.1 How to Create a Form Class

  • 6.2 How to Write Views

• Step 7: How to Create Templates

  • 7.1 How to Set Up the Template Directory

  • 7.2 How to Create the Workout List Template

  • 7.3 How to Create Add Workout Template

• Step 8: How to Connect URLs

  • 8.1 How to Create App Level URLs

  • 8.2 How to Link App URLs to project

• Step 9: How to Test the Application Locally

• Step 10: How to Prepare for Deployment

  • 10.1 How to Update Settings for Production

• Step 11: How to Deploy Your Django App on PythonAnywhere

  • 11.1 How to Create a PythonAnywhere Account

  • 11.2 How to Upload Your Project Files

  • 11.3 How to Set Up a Virtual Environment in PythonAnywhere

  • 11.4 How to Run Migrations and Create a SuperUser on PythonAnywhere

  • 11.4 How to Configure the Web App in Pythonanywhere

  • 11.5 How to Set the Virtual Environment Path

  • 11.6 How to Configure the WSGI file

  • 11.7 How to Set Up Static Files

  • 11.8 How to View Your Live Application

• Common Mistakes and How to Fix Them

• How You Can Improve This Project

• Conclusion

Prerequisites

Before you begin, make sure you are comfortable with the following:

Python fundamentals: You should understand variables, functions, lists, dictionaries, and basic control flow (if/else statements and loops).

Basic command line usage: You'll be running commands in your terminal throughout this tutorial. You should know how to open a terminal, navigate between folders, and run commands. If you're on Windows, you can use Command Prompt or PowerShell. On macOS or Linux, the default Terminal app works well.

Tools you'll need installed:

• Python 3.8 or higher. You can check your version by running python --version or python3 --version in your terminal.  If you don't have Python installed, download it from python.org

• pip. This is Python's package manager. It usually comes bundled with Python. You can verify by running pip --version or pip3 --version. Note the commands python3 and pip3 tell the terminal that you are explicitly using Python Version 3

• A code editor. Visual Studio Code is a great free option, but you can use any editor you're comfortable with.

That's everything. You don't need prior Django experience or web development knowledge. This tutorial will walk you through each step.

What You Are Going Build

The fitness tracker you will build has two main features:

1. A form to log workouts. You will enter the name of an activity (like "Running" or "Push-ups"), how long you did it (in minutes), and the date. When you submit the form, Django saves that workout to a database.

1. A page to view all your workouts. This page displays every workout you have logged, showing the activity, duration, and date in a clean list.

Here's how data flows through the app at a high level:

1. You fill out the workout form in your browser and click submit.

2. Your browser sends that data to Django.

3. Django's view function receives the data, validates it, and saves it to the database.

4. When you visit the workouts page, Django's view function pulls all saved workouts from the database.

5. Django passes that data to an HTML template, which renders it as a page your browser can display.

This request-response cycle is the foundation of how Django works. Once you understand it, you can build almost anything.

Step 1: How to Set Up Your Django Project

Every Django project starts with a few setup steps. You'll create an isolated Python environment, install Django, and generate the initial project structure.

1. 1 How to Create a Virtual Environment

A virtual environment is a self-contained folder that contains its own Python interpreter and installed packages for a specific project. This keeps your project's dependencies separate from other Python projects on your computer. This separation prevents version conflicts and keeps setups consistent.

For example, one project might require an older version of Django, while another needs the latest version, and a virtual environment allows both to work smoothly on the same system.

Without it, global installations can clash, break projects, and make setups hard to reproduce. Over time, the system environment becomes cluttered with unused or incompatible packages making debugging and maintenance more difficult.

Now let's set it up.

Open your terminal, and navigate to where you want your project to live and run the following command

mkdir fitness-tracker
cd fitness-tracker

The first command creates a new folder called fitness-tracker. The second command moves you into that folder.

You'll create the Python virutal environment here.

python3 -m venv venv

The above command creates a virtual environment inside a folder called venv. The first venv is the command and the second venv represents the name of the folder. You can name the folder anything though venv is usually preferred.

By using the ls command, you can see that we've created the virtual environment folder.

To activate the virtual environment, we need to use the following command:

On macOS/Linux:

source venv/bin/activate

On Windows:

venv\Scripts\activate

You'll know it worked when you see (venv) at the beginning of your terminal prompt. From this point on, any Python packages you install will only exist inside this virtual environment.

1.2 How to Install Django

With your virtual environment activated, install Django using pip:

pip install django

This downloads and installs the latest stable version of Django. You can verify the installation by running:

python3 -m django --version

After running both these commands, you should see Django being installed and the version number:

1.3 How to Create the Project

We have finished installing Django. Now let's create a Django project. Django provides a command line utility that generates the boilerplate files that you need. Type the following command:

django-admin startproject fitness_project .

The command creates a folder named fitness-project. Notice the dot at the end of the command. The dot at the end is important. It tells Django to create the project files in your current directory instead of creating an extra nested folder.

Now that we've created our Django project, let's open the project in your favourite text editor and look at folder structure.

You'll notice that the folder already comes with a bunch of files.

1.4 How to Run the Development Server

Now let's make sure everything is working. You'll need to run a server for this. Type the following command:

python manage.py runserver

You can type this command in the terminal with the virtual environment activated or you can use the integrated terminal if you're using VS Code. I'll be using the integrated terminal from this point on.

Open your browser and go to http://127.0.0.1:8000/. You should see Django's default welcome page with a rocket ship graphic confirming that your project is set up correctly.

Press Ctrl + C in your terminal to stop the server when you're ready to move on.

Step 2: How to Create a Django App

In Django, a project is the overall container for your entire web application, while an app is a smaller, self-contained module inside that project that focuses on a specific piece of functionality.

A useful way to picture this is to think of a house. The project is the whole house. Each app is like a room inside that house. One room might be a kitchen, another a bedroom, each designed with a clear purpose. In the same way, a Django app is built to handle one responsibility, such as authentication, payments, or in this case, workout tracking.

Now, here's the important part: why not just put everything into one big project instead of using apps? You technically could, especially for very small projects. But as your application grows, that approach quickly becomes difficult to manage.

By using apps, you naturally separate concerns. It also makes collaboration smoother, since different people can work on different apps without constantly stepping on each other’s code.

Another major benefit is reusability. Since apps are modular, you can take an app from one project and reuse it in another.

For example, if you build a workout tracking app once, you could plug it into a completely different Django project later without rebuilding it from scratch. Later, you might create a completely different project, say a fitness coaching platform or a health dashboard. Instead of rebuilding the tracking feature from scratch, you can reuse the same app.

For this project, you'll create a single app called tracker that handles everything related to logging and displaying workouts.

2.1 How to Generate the App

Make sure you're in the same directory as the manage.py file, then run the following code:

python manage.py startapp tracker

This create a new folder called tracker with the following following structure:

Each file has its own purpose. You'll work with models.py, views.py and admin.py throughout this project.

2.2 How to Register the App

Django doesn't automatically know about your new app. You need to tell it by adding the app to the INSTALLED_APPS list in settings.py file.

Open fitness_project/settings.py and find the INSTALLED_APPS list. Add the name of the app, that is tracker, to the end of the list:

You'll notice that a number of apps have already been installed automatically by Django. This is part of Django’s “batteries-included” philosophy, where many common features are ready to use out of the box.

Here is a short summary of what each of the apps does.

Now Django knows your tracker app exists and will include it when running the project.

Step 3: How to Create a Workout Model

A model in Django is a Python class that defines the structure of your data. Each model maps directly to a table in your database. Each attribute on the model becomes a column in that table.

Think of a model as a blueprint for a spreadsheet. The class name is the name of the spreadsheet, and each field is a column header. Every time you save a new workout, Django creates a new row in that spreadsheet.

3.1 How to Define the Model

Open tracker/models.py and replace its contents with this code:

from django.db import models

class Workout(models.Model):
    activity = models.CharField(max_length=200)
    duration = models.IntegerField(help_text="Duration in minutes")
    date = models.DateField()

    def __str__(self):
        return f"{self.activity} - {self.duration} min on {self.date}"

Let's discuss what each part does:

• activity = models.CharField(max_length=200) creates a text fields that can hold up to 200 characters. This is where you'll store the name of the exercise like "Running" or "Cycling".

• duration = models.IntegerField(help_text="Duration in minutes") creates a whole number field for storing how many minutes the workout lasted. The help_text parameter adds a hint that will appear in forms and the admin panel.

• date = models.DateField() creates a date field for recording when the workout happened.

The __str__() method defines how a Workout object appears when printed or displayed in the admin panel. Instead of seeing something unhelpful like "Workout object (1)," you will see "Running - 30 min on 2025-03-15."

Step 4: How to Apply Migrations

You've defined your model, but Django hasn't created the actual database table yet. To do that, you need to run migrations.

Migrations are Django's way of translating your Python model definitions into database instructions. Migrations are done in two steps.

When you change a model – maybe by adding a field, removing a field, or renaming one – you create a new migration that describes that change. You can do this using the makemigrations command.

Then you apply the migration using the migrate command and Django updates the database to match.

This two-step process of first detecting the change and then applying the change gives you a reliable record of every change to your database structure over time.

4.1 How to Generate the Migration

Run the following command in the integrated terminal:

python manage.py makemigrations

You should see output like this:

Migrations for 'tracker': tracker/migrations/0001_initial.py 
    + Create model Workout

Django inspected your Workout model and created a migration file that describes how to build the corresponding database table. You can find this file at tracker/migrations/0001_initial.py if you want to look at it, but you don't need to edit it.

4.2 How to Apply the Migration

Now tell Django to execute that migration and actually create the table in the database:

python manage.py migrate

You'll see several lines of output as Django applies not just your migration, but also the default migrations for Django's built-in apps (authentication, sessions, and so on).

When it finishes, your database has a table ready to store workouts.

When the migrate command runs, we can see the exact SQL commands that Django used to build and change the database. Though this isn't required for creating the application, it's always good to know what's happening under hood.

Run this command:

python manage.py sqlmigrate tracker 001

And you should get this output:

The 001 you added at the end is the migration number and represents first version of the database schema.

In practice, your workflow usually looks like this: you change your models, run makemigrations to generate the migration files, and then run the migrate command to apply those changes to the database.

Step 5: How to Register the Model in the Admin Panel

Django comes with a powerful admin interface built in. It gives you a graphical way to view, add, edit, and delete records in your database without writing any extra code. This is incredibly useful during development because you can quickly test your models and see your data.

But by default, it doesn’t know:

• Which models you want to manage

• How you want them displayed

So you register models in admin.py to tell Django to include the specific model in the admin interface.

5.1 How to Add Model to Admin

Open tracker/admin.py and add the following code:

from django.contrib import admin
from .models import Workout

admin.site.register(Workout)

This single line tells Django to include the Workout model in the admin interface.

5.2 How to Create a Superuser

To access the admin panel, you need an admin account. Create one by running:

python manage.py createsuperuser

Django will prompt you for a username, email address, and password. Choose something you will remember. The email is optional – you can press Enter to skip it.

5.3 How to Access the Admin Panel

Start the development server:

python manage.py runserver

Then navigate to http://127.0.0.1:8000/admin/ in your browser. Log in with the credentials you just created.

You should see the Django administration dashboard with a "Tracker" section containing your "Workouts" model.

Try clicking "Add" to create a couple of test workouts. This will confirm that your model is working correctly before you build the rest of the app.

Step 6: How to Create Views for the App

A view in Django is a Python function (or class) that receives a web request and returns a web response. That response could be an HTML page, a redirect, a 404 error, or anything else a browser can handle.

Views are where your application logic lives. They decide what data to fetch, what processing to do, and what to show the user.

For this app, you need two views: one to display the form where users add a workout, and one to display the list of all saved workouts.

6.1 How to Create a Form Class

Before writing the views, you need a Django form that handles the workout input.

Django forms are a built-in way to handle user input like login forms, contact forms, or anything that collects data from a user. Instead of manually writing HTML, validating inputs, and handling errors, Django gives you a structured way to do all of that in one place.

Most user inputs are based on the models you’ve created, and Django can automatically generate forms from those models using ModelForms, which speeds things up significantly.

Let's create a new file called forms.py in the tracker folder and add the following code:

from django import forms
from .models import Workout

class WorkoutForm(forms.ModelForm):

    class Meta:
        model = Workout
        fields = ['activity', 'duration', 'date']
        widgets = {
            'date': forms.DateInput(attrs={'type': 'date'}),
        }

In the above code, the ModelForm automatically generates form fields based on the Workout model. The widgets dictionary tells Django to render the date field as an HTML date picker instead of a plain text input.

We can actually see the forms being automatically created by Django. For this we need to enter the shell. In the terminal, type the following command:

python manage.py shell

Now lets import the WorkoutForm class that we just created.

Type the following code:

from tracker.forms import WorkoutForm

Notice that we've given the name of the app as well when we imported the form.

Then create an object of the WorkoutForm class and print it.

from tracker.forms import WorkoutForm
workoutform = WorkoutForm()
print(workoutform) 

You should get the following output:

You can see that all the model fields have been renderd as HTML forms and the date field has been created as a date type that is type="date" instead of plain text.

6.2 How to Write Views

As we've discussed above, our project has two views: one to add a workout and the other to display all the saved workouts.

First, let's create a view to add a workout. In the tracker/views.py file, type the following code:

from django.shortcuts import render, redirect
from .models import Workout

# view to list all workouts
def workout_list(request):
    workouts = Workout.objects.all().order_by('-date')
    return render(request, 'tracker/workout_list.html', {'workouts': workouts})

Let's walk through this view:

• The workout_list view handles the page that displays all workouts.

• It queries the database for every Workout object, orders them by date (most recent first, thanks to the - prefix), and passes that list to a template called workout_list.html.

• The render function combines the template with the data and returns the finished HTML page.

To create the logic to add a workout, first add the Workout form import at the end of the import section. Then add the following code after the workout_list view:

from django.shortcuts import render, redirect
from .models import Workout
from .forms import WorkoutForm

# view to list all the workouts
def workout_list(request):
    workouts = Workout.objects.all().order_by('-date')
    return render(request, 'tracker/workout_list.html', {'workouts': workouts})

# view to add a workout
def add_workout(request):
    if request.method == 'POST':
        form = WorkoutForm(request.POST)
        if form.is_valid():
            form.save()
            return redirect('workout_list')
    else:
        form = WorkoutForm()
    return render(request, 'tracker/add_workout.html', {'form': form})

• The add_workout view handles both displaying the empty form and processing submitted form data.

• When a user first visits the page, the request method is GET, so Django creates a blank form and renders it.

• When the user fills out the form and clicks submit, the request method is POST. Django then validates the submitted data, saves it to the database if everything is correct, and redirects the user to the workout list page.

• If the data isn't valid, Django re-renders the form with error messages.

Here is the complete views code:

from django.shortcuts import render, redirect
from .models import Workout
from .forms import WorkoutForm

# view to list all workouts
def workout_list(request):
    workouts = Workout.objects.all().order_by('-date')
    return render(request, 'tracker/workout_list.html', {'workouts': workouts})

# view to add a workout
def add_workout(request):
    if request.method == 'POST':
        form = WorkoutForm(request.POST)
        if form.is_valid():
            form.save()
            return redirect('workout_list')
    else:
        form = WorkoutForm()
    return render(request, 'tracker/add_workout.html', {'form': form})

Step 7: How to Create Templates

Templates are HTML files that Django fills in with dynamic data. They're the front end of your application: the part users actually see in their browser.

7.1 How to Set Up the Template Directory

Django looks for templates inside a templates folder within each app. Create the following folder structure inside your tracker app.

tracker/templates/tracker

The double tracker folder name might look redundant, but it's a Django convention called template namespacing. It prevents naming conflicts if you have multiple apps with templates that share the same filename.

7.2 How to Create the Workout List Template

Create a file called tracker/templates/tracker/workout_list.html and add the following code:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My Workouts</title>
    <style>
        * {
            margin: 0;
            padding: 0;
            box-sizing: border-box;
        }

        body {
            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
            background-color: #f5f7fa;
            color: #333;
            line-height: 1.6;
            padding: 2rem;
        }

        .container {
            max-width: 700px;
            margin: 0 auto;
        }

        h1 {
            font-size: 1.8rem;
            margin-bottom: 1rem;
            color: #1a1a2e;
        }

        .add-link {
            display: inline-block;
            background-color: #4361ee;
            color: white;
            padding: 0.6rem 1.2rem;
            border-radius: 6px;
            text-decoration: none;
            margin-bottom: 1.5rem;
            font-size: 0.95rem;
        }

        .add-link:hover {
            background-color: #3a56d4;

        }

        .workout-card {
            background: white;
            border-radius: 8px;
            padding: 1rem 1.2rem;
            margin-bottom: 0.8rem;
            box-shadow: 0 1px 3px rgba(0, 0, 0, 0.08);
            display: flex;
            justify-content: space-between;
            align-items: center;

        }

        .workout-activity {
            font-weight: 600;
            font-size: 1.05rem;

        }

        .workout-details {
            color: #666;
            font-size: 0.9rem;

        }

        .empty-state {
            text-align: center;
            padding: 3rem 1rem;
            color: #888;

        }

    </style>
</head>

<body>
    <div class="container">
        <h1>My Workouts</h1>
        <a href="{% url 'add_workout' %}" class="add-link">+ Log a Workout</a>
        {% if workouts %}
            {% for workout in workouts %}
                <div class="workout-card">
                    <div>
                        <div class="workout-activity">{{ workout.activity }}</div>
                        <div class="workout-details">{{ workout.duration }} minutes</div>
                    </div>
                    <div class="workout-details">{{ workout.date }}</div>
                </div>
            {% endfor %}

        {% else %}
            <div class="empty-state">
                <p>No workouts logged yet. Start by adding one!</p>
            </div>
        {% endif %}
    </div>
</body>
</html>

There are a few things worth noting here:

If you look closely at the HTML, you'll spot some weird-looking tags wrapped in curly braces ( {% %} and {{ }} ). Think of them as special instructions for Django.

You use the double curly braces ({{ }}) when you want to output or display a piece of data directly on the page.

On the other hand, you use the brace-and-percent-sign combo ( {% %} ) when you need Django to actually perform an action or apply logic, like running a loop or checking a condition.

They allow us to inject dynamic data straight from our Python backend right into our otherwise static HTML.

Lets look at this code snippet for the workout_list.html

<body>
    <div class="container">
        <h1>My Workouts</h1>
        <a href="{% url 'add_workout' %}" class="add-link">+ Log a Workout</a>
        {% if workouts %}
            {% for workout in workouts %}
                <div class="workout-card">
                    <div>
                        <div class="workout-activity">{{ workout.activity }}</div>
                        <div class="workout-details">{{ workout.duration }} minutes</div>
                    </div>
                    <div class="workout-details">{{ workout.date }}</div>
                </div>
            {% endfor %}

        {% else %}
            <div class="empty-state">
                <p>No workouts logged yet. Start by adding one!</p>
            </div>
        {% endif %}
    </div>
</body>

There are a few things worth noting here.

Right under the main heading, you'll see this line:
<a href="{% url 'add_workout' %}">

Instead of hardcoding a web link like href="/add-workout/", Django uses the {% url %} tag to generate the link dynamically. You pass it the name of the route (in this case, add_workout), and Django automatically figures out the correct URL path.

If you ever change the URL structure in your Python code later, Django updates this link automatically. You never have to hunt through HTML files to fix broken links!

The {% if workouts %} block checks whether there are any workouts to display. If the list is empty, it shows a friendly message instead of a blank page.

The {% for workout in workouts %} loop iterates over every workout in the list and renders a card for each one. The double curly braces {{ workout.activity }} insert the value of each field into the HTML

Inside the loop, you'll notice tags that look like this:

• {{ workout.activity }}

• {{ workout.duration }}

• {{ workout.date }}

As Django loops through each workout object, it uses dot notation to peek inside that specific object and grab its details. It grabs the activity type (like "Running"), the duration ("30"), and the date ("March 30"), and prints that exact text directly onto the webpage for the user to see.

7.3 How to Create Add Workout Template

Create a file called tracker/templates/tracker/add_workout.html and add the following code:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Log a Workout</title>
    <style>
        * {
            margin: 0;
            padding: 0;
            box-sizing: border-box;

        }

        body {
            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
            background-color: #f5f7fa;
            color: #333;
            line-height: 1.6;
            padding: 2rem;
        }

        .container {
            max-width: 500px;
            margin: 0 auto;

        }

        h1 {
            font-size: 1.8rem;
            margin-bottom: 1.5rem;
            color: #1a1a2e;
        }

        .form-group {
            margin-bottom: 1.2rem;
        }

        label {
            display: block;
            margin-bottom: 0.3rem;
            font-weight: 600;
            font-size: 0.95rem;

        }

        input[type="text"],
        input[type="number"],
        input[type="date"] {
            width: 100%;
            padding: 0.6rem 0.8rem;
            border: 1px solid #ddd;
            border-radius: 6px;
            font-size: 1rem;
            transition: border-color 0.2s;
        }

        input:focus {
            outline: none;
            border-color: #4361ee;

        }

        .btn {
            background-color: #4361ee;
            color: white;
            padding: 0.7rem 1.5rem;
            border: none;
            border-radius: 6px;
            font-size: 1rem;
            cursor: pointer;
            margin-right: 0.5rem;
        }

        .btn:hover {
            background-color: #3a56d4;
        }

        .back-link {
            color: #4361ee;
            text-decoration: none;
            font-size: 0.95rem;
        }

        .back-link:hover {
            text-decoration: underline;
        }

        .actions {
            display: flex;
            align-items: center;
            gap: 1rem;
            margin-top: 0.5rem;
        }

        .error-list {
            color: #e74c3c;
            font-size: 0.85rem;
            margin-top: 0.3rem;

        }

    </style>
</head>
<body>
    <div class="container">
       <h1>Log a Workout</h1>
        <form method="post">
            {% csrf_token %}
            <div class="form-group">
                <label for="id_activity">Activity</label>
                {{ form.activity }}
                {% if form.activity.errors %}
                    <div class="error-list">{{ form.activity.errors }}</div>
                {% endif %}
            </div>
            <div class="form-group">
                <label for="id_duration">Duration (minutes)</label>
                {{ form.duration }}
                {% if form.duration.errors %}
                    <div class="error-list">{{ form.duration.errors }}</div>
                {% endif %}
            </div>

            <div class="form-group">
                <label for="id_date">Date</label>
                {{ form.date }}
                {% if form.date.errors %}
                    <div class="error-list">{{ form.date.errors }}</div>
                {% endif %}
            </div>

            <div class="actions">
                <button type="submit" class="btn">Save Workout</button>
                <a href="{% url 'workout_list' %}" class="back-link">Cancel</a>
            </div>
        </form>
    </div>
</body>
</html>

In the previous template, we learned how to display data. Now, we're looking at a form that actually collects data. Handling forms manually in web development can get messy, but Django provides some powerful template tags to do the heavy lifting for us.

Let's look at the Django-specific logic powering this form:

First, right after opening the <form> tag, you'll spot a very important line: {% csrf_token %}. Whenever you submit data to a server using a "POST" method, malicious sites can potentially intercept or forge that request.

By including this {% csrf_token %}, you tell Django to generate a unique, hidden security key for the form. When the user clicks "Save Workout," Django checks this token to guarantee the request is legitimate. If you forget this tag, Django will simply reject your form!

<form method="post">
            {% csrf_token %}
            <div class="form-group">
                <label for="id_activity">Activity</label>
                {{ form.activity }}
                {% if form.activity.errors %}
                    <div class="error-list">{{ form.activity.errors }}</div>
                {% endif %}
            </div>
            <div class="form-group">
                <label for="id_duration">Duration (minutes)</label>
                {{ form.duration }}
                {% if form.duration.errors %}
                    <div class="error-list">{{ form.duration.errors }}</div>
                {% endif %}
            </div>

            <div class="form-group">
                <label for="id_date">Date</label>
                {{ form.date }}
                {% if form.date.errors %}
                    <div class="error-list">{{ form.date.errors }}</div>
                {% endif %}
            </div>

            <div class="actions">
                <button type="submit" class="btn">Save Workout</button>
                <a href="{% url 'workout_list' %}" class="back-link">Cancel</a>
            </div>
        </form>

Now let's talk about automatically generating the form fields. Instead of manually typing out all the HTML <input> tags for the activity, duration, and date, we let Django do it for us using display tags ({{ }}).

Each {{ form.activity }}, {{ form.duration }}, and {{ form.date }} tag renders the corresponding form input. Django handles the HTML attributes, input types, and validation for you based on the model and form definitions.

The error blocks below each field display validation messages if a user submits invalid data, like entering text in the duration field instead of a number. Users make mistakes. They might leave a required field blank or type text into a number field. Fortunately, Django validates the data for you and sends back errors if something goes wrong.

Underneath each input field, we use a logic block that looks like this:
{% if form.activity.errors %}

This code checks a simple condition: Did the user mess up this specific field? If Django found an error with the "activity" input, the code drops into the if block and uses{{ form.activity.errors }} block to print the exact error message (like "This field is required") right below the input box.

You may notice that both templates include inline CSS rather than a separate stylesheet. For a small project like this, inline styles keep things simple and self-contained. In a larger project, you would use Django's static files system to manage CSS separately.

Step 8: How to Connect URLs

You have views and templates, but Django doesn't know when to use them yet. You need to map URLs to views so that visiting a specific address in the browser triggers the right view function.

8.1 How to Create App Level URLs

Create a new file called tracker/urls.py and add the following code:

from django.urls import path
from . import views

urlpatterns = [ 
    path('', views.workout_list, name='workout_list'), 
    path('add/', views.add_workout, name='add_workout'), 
]

Each path function takes three arguments.

The first is the route string that represents a URL pattern (an empty string means the root of the app).

The second is the view function to call when that URL is visited.

The third is a name you can use to reference this URL elsewhere in your code, like in the {% url %} template tags you used earlier.

8.2 How to Link App URLs to project

Now that your app-level URLs are set up, the next step is to connect them to the main project so Django knows where to start routing requests. Think of it like linking a smaller map (your app) to a bigger map (your project), so everything works together smoothly.

Open fitness_project.urls.py and update it to include your app's URLs:

from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', include('tracker.urls')),
]

The include() function tells Django to look at the URL patterns defined in the tracker/urls.py file whenever someone visits your site. The empty string prefix means your tracker app handles requests at the root of the site.

Here's the full picture of how a request flows through the URL system.

When someone visits http://127.0.0.1:8000/add/, Django first checks fitness_project/urls.py. It matches the empty prefix and delegates to tracker/urls.py. There, it matches add/ and calls the add_workout view.

Step 9: How to Test the Application Locally

At this point, your app has everything it needs to work. Let's test it.

Start the development server by running the command:

python manage.py runserver

Open your browser and visit http://127.0.0.1:8000/. You should see the workout list page with the heading "My Workouts" and a button that says "+ Log a Workout."

Click that button. You should see the workout form with fields for activity, duration, and date.

Fill in some test data:

• Activity: Skipping

• Duration: 25

• Date: Pick today's date from the date picker

Click "Save Workout" You should be redirected back to the workout list page, and your new workout should appear as a card.

Try adding a few more workouts with different activities and dates. Make sure they all show up on the list page in the correct order (most recent first).

This is also a good time to experiment. Try submitting the form with missing fields and see how Django handles validation.

Try accessing the admin panel at http://127.0.0.1:8000/admin/ to see your workouts there as well.

If everything works as expected, you're ready to put your app on the internet.

Step 10: How to Prepare for Deployment

Running your app on localhost is great for development, but nobody else can see it. Deployment means putting your app on a server that's accessible from anywhere on the internet.

Before you deploy, you'll need to make a few changes to your project's settings.

10.1 How to Update Settings for Production

Open fitness_project/settings.py and make the following changes.

First, set DEBUG to False.

During development, DEBUG = True shows detailed error pages that help you fix problems. In production, these error pages would expose sensitive information about your code and server to anyone who triggers an error.

Next, update ALLOWED_HOSTS to include PythonAnywhere's domain.

This setting tells Django which domain names are allowed to serve your app. Replace yourusername with the actual PythonAnywhere username you will create in the next step.

ALLOWED_HOSTS = ['yourusername.pythonanywhere.com']

Finally, add a STATIC_ROOT setting so Django knows where to collect your static files (CSS, JavaScript, images) for production:

import os
STATIC_ROOT = os.path.join(BASE_DIR, 'staticfiles')

These are the minimum changes needed for a basic deployment.

💡 For a production app handling real user data, you would also want to set a secure SECRET_KEY, configure a proper database like PostgreSQL, and set up HTTPS. But for a learning project, these changes are enough.

Step 11: How to Deploy Your Django App on PythonAnywhere

PythonAnywhere is a hosting platform designed specifically for Python web applications. It offers a free tier that's perfect for beginner projects, and it handles much of the server configuration that would otherwise be complex to set up on your own.

11.1 How to Create a PythonAnywhere Account

Go to pythonanywhere.com and sign up for a free "Beginner" account. Remember the username you choose, because your app will be available at yourusername.pythonanywhere.com.

Now signup to the website. Fill in the username, email and password and click on the free tier or now.

11.2 How to Upload Your Project Files

After logging in, you have two options for getting your project files onto PythonAnywhere.

Option A: Upload using Git

If your project is in a Git repository, open a Bash console from the PythonAnywhere dashboard by clicking "Consoles" and then "Bash." Then clone your repository:

git clone https://github.com/yourusername/fitness-tracker.git

In this tutorial, we won't be using Git. Instead we'll follow the second option.

Option B: Upload files manually

First go your project folder in your computer and created a compressed version of the project.

IMPORTANT NOTE: When you create the compressed file, make sure to first create a copy of the project somewhere and remove the venv and pycache folder before you compress it.

Navigate to your home directory and click on upload file tab and upload the compressed file.

Now we need to unzip the compressed file. To do this, go to the Consoles tab and click on Bash console.

The bash console should open. Then type the following command in the console to unzip the folder:

unzip fitness-tracker.zip

11.3 How to Set Up a Virtual Environment in PythonAnywhere

Open a Bash console from the PythonAnywhere dashboard. Navigate to your project directory and create a fresh virtual environment:

cd fitness-tracker

Type the following command to install a virtual environment as we've done before and then activate the virtual environment:

python3 -m venv venv

source venv/bin/activate

Now install Django as before using pip install django command:

11.4 How to Run Migrations and Create a SuperUser on PythonAnywhere

While you're still in the Bash console with your virtual environment activated, run the migrations to create the database tables on the server:

python manage.py makemigrations

python manage.py migrate

python manage.py createsuperuser

11.4 How to Configure the Web App in Pythonanywhere

Go to the "Web" tab on the PythonAnywhere dashboard and click "Add a new web app." Follow the setup wizard:

Click "Next" on the domain name step (remember the free tier uses yourusername.pythonanywhere.com).

Select "Manual configuration" (not "Django" – the manual option gives you more control).

Then choose the Python version that matches what you installed. In my case it's 3.13, so I'll choose 3.13

Click on Next button and a WSGI (Web Server Gateway Interface) will be created.

With this we've created the web app:

After you've set up the web app, you have to do two more things:

• Set the virtual environment path

• Configure the WSGI file

11.5 How to Set the Virtual Environment Path

On the Web tab, scroll down to the "Virtualenv" section and enter the path to your virtual enviroment. The path to the file should be like this:

/home/yourusername/fitness-tracker/venv

11.6 How to Configure the WSGI file

Still on the Web tab, scroll to the code section and click on the WSGI configuration file link:

Delete all the contents and replace them with the content below and save the file:

import os
import sys
path = '/home/prabodhtuladhardev/fitness-tracker' #replace with your username
if path not in sys.path:
    sys.path.append(path)

os.environ['DJANGO_SETTINGS_MODULE'] = 'fitness_project.settings'

from django.core.wsgi import get_wsgi_application
application = get_wsgi_application()

11.7 How to Set Up Static Files

Still on the "Web" tab, scroll down to the "Static files" section. Add an entry:

• URL: /static/

• Directory: /home/yourusername/fitness-tracker/staticfiles

Then go back to your Bash console and run the following command:

python manage.py collectstatic

This copies all static files to the staticfiles directory so PythonAnywhere can serve them directly.

Go back to the "Web" tab and click the green "Reload" button at the top. This restarts your app with all the new configuration.

11.8 How to View Your Live Application

Open a new browser tab and visit https://yourusername.pythonanywhere.com. You should see your fitness tracker, live on the internet.

Try adding a workout.

Visit the admin panel at https://yourusername.pythonanywhere.com/admin/.

Everything should work just as it did on your local machine, but now anyone with the link can access it.

This is a meaningful milestone. You've gone from zero to a deployed Django application. Share the link with a friend or post it in a coding community. Seeing your work live on the internet is one of the most motivating experiences in learning to code.

Common Mistakes and How to Fix Them

Even when you follow each step carefully, things can go wrong. Here are the most common issues beginners run into and how to solve them.

"ModuleNotFoundError: No module named 'django'" – This usually means your virtual environment isn't activated. Run source venv/bin/activate (macOS/Linux) or venv\Scripts\activate (Windows) and try again. On PythonAnywhere, make sure the virtualenv path in the "Web" tab points to the correct location.

"DisallowedHost" error – You forgot to add your domain to ALLOWED_HOSTS in settings.py, or there's a typo. Double-check that it matches your PythonAnywhere URL exactly.

Static files not loading in production – Make sure you ran python manage.py collectstatic and that the static file mapping on PythonAnywhere points to the correct staticfiles directory. Also verify that STATIC_ROOT is set in settings.py.

"No such table" or migration errors – You probably forgot to run python manage.py migrate after cloning or uploading your project to PythonAnywhere. Run the migrate command in the Bash console.

Changes not showing up on PythonAnywhere – After making any code changes, you must click the "Reload" button on the "Web" tab. PythonAnywhere does not automatically detect file changes.

How You Can Improve This Project

The fitness tracker you built is intentionally simple. That's a feature, not a limitation. A working simple project is the perfect foundation for learning more.

Here are some ideas for expanding it.

1. Add user authentication: Right now, anyone who visits the site sees the same workout data. Django has a built-in authentication system that lets you add registration, login, and logout. Each user could then have their own private list of workouts.

2. Add the ability to edit and delete workouts. Currently, once a workout is saved, there's no way to change or remove it from the interface (you can do it through the admin panel, but not the main app). Try creating new views and templates for editing and deleting.

3. Add workout categories or tags. Let users categorize their workouts as "Cardio," "Strength," "Flexibility," and so on. This would involve adding a new field to the model or creating a separate Category model with a foreign key relationship.

4. Add charts and progress tracking. Use a JavaScript charting library like Chart.js to display workout trends over time. For example, you could show a bar chart of total minutes exercised per week.

5. Build an API with Django REST Framework. If you want to learn about building APIs, try installing Django REST Framework (DRF) and creating API endpoints for your workouts. This would let you build a mobile app or a separate front end that communicates with your Django back end.

Each of these improvements will teach you something new about Django while building on the foundation you already have.

Conclusion

You've built a fully functional fitness tracker web app with Django and deployed it to the internet. That's no small achievement.

Along the way, you learned how Django projects and apps are structured, how models define the shape of your data, how migrations translate those models into database tables, how views handle the logic of your application, how templates render dynamic HTML, and how URLs tie everything together. You also went through the entire deployment process on PythonAnywhere.

These are the core building blocks of Django development. The patterns you practiced here – defining a model, creating a form, writing a view, building a template, and connecting a URL – are the same patterns you will use in every Django project, no matter how complex.

The best way to solidify what you have learned is to keep building. Try one of the improvements mentioned above, or start a completely new project. A calorie tracker, a habit tracker, an expense tracker, or a personal journal would all use the same Django concepts with slightly different models and views.

Coming from tutorials that talked about "call by value" and "call by reference," I assumed Python must follow one of those two models. It doesn't. Python does something slightly different, and once you understand it, a lot of previously confusing behavior will suddenly click.

In this article, you'll learn:

• What calling by value and calling by reference mean

• How other languages like C handle this

• What Python actually does (passing by object reference)

• How mutable and immutable types affect behavior inside functions

Table of Contents

• Call by Value and Call by Reference Explained

• How It Works in C (with Examples)

• What Python Does Instead

• Mutable vs Immutable Types

• Conclusion

Call by Value and Call by Reference Explained

Before we get to Python, let's quickly define these two terms.

Call by value means a copy of the variable is passed to the function. Whatever you do to it inside the function, the original stays unchanged.

Call by reference means the actual memory location of the variable is passed. Changes inside the function directly affect the original variable.

Many languages support one or both of these models. Python, however, uses neither – at least not in the traditional sense.

How It Works in C (with Examples)

C is a good example of a language that supports both models explicitly.

Here's how you call by value in C. The original variable is unaffected:

#include <stdio.h>

void modify(int *n) {

*n = *n + 10;

printf("Inside function: %d\n", *n); }

int main() {

int x = 5;

modify(&x);

printf("Outside function: %d\n", x);

return 0; }

Output:

Inside function: 15

Outside function: 15 ← original changed!

In C, you explicitly choose the behavior by deciding whether to pass a pointer or a plain value. Python doesn't give you that choice, but what it does instead is actually quite logical.

What Python Does Instead

Python uses a model called passing by object reference (sometimes called passing by assignment).

When you pass a variable to a function in Python, you're passing a reference to the object that variable points to, not a copy of the value, and not the variable itself.

What happens next depends entirely on whether that object is mutable (can be changed in place) or immutable (cannot be changed in place).

Mutable vs Immutable Types

Immutable types in Python include int, float, str, and tuple. These objects cannot be modified in place. When you "change" one inside a function, Python creates a brand new object and the original is left untouched.

def modify_number(n):
     n = n + 10
     print("Inside function:", n)

x = 5

modify_number(x)

print("Outside function:", x)

Output:

Inside function: 15

Outside function: 15 ← original unchanged

Mutable types include list, dict, and set. These can be changed in place. When you modify one inside a function, you're modifying the same object the caller is holding a reference to.

def modify_list(items):

    items.append(99)

    print("Inside function:", items)

my_list = [1, 2, 3]

modify_list(my_list)

print("Outside function:", my_list)

Output:

Inside function: [1, 2, 3, 99]

Outside function: [1, 2, 3, 99] ← original changed!

This is the key insight: Python doesn't decide behavior based on how you pass something, it decides based on what type of object you're passing.

Conclusion

Python doesn't use call by value or call by reference. It passes by object reference, where the function receives a reference to the object, and whether that object can be modified in place determines what happens next.

To recap:

• Immutable types (int, str, tuple): a new object is created inside the function, original stays the same

• Mutable types (list, dict, set): the original object is modified directly

Once this clicked for me, a lot of the "why is Python doing this?" moments started making sense. If you're just getting started with functions in Python, keep this in the back of your mind, it'll save you a lot of debugging headaches.

I’ve tried my hand at a few of them, and the one language that feels like it touches both worlds is Golang – popularly known as Go. Although Go is a high-level language, it has pretty amazing performance that brings it close to the low-level edge.

Go is a fast, statically typed programming language. Types are declared at compile time, and you don’t need to run the code before catching errors. It’s also a general-purpose language that you can use for backend, cloud, servers, and more.

Go has built-in testing support, so you don’t need to install extra testing libraries. Go also has some features of object-oriented languages, but in its own way. It mirrors some OOP concepts, but also uses concepts like interfaces, structs, and so on.

In this tutorial, we're going to be looking at a few basic concepts you need to know when getting started in any programming language. A few of them are generic to many programming languages, but some of them are concepts specific to the Go programming language. We'll take a look at:

• Variables

• Formatting strings

• Arrays and slices

• Loops

• Functions

• Maps

• Structs, and

• Package scope

By the end of the article, you'll be grounded in the pure basics of Go, and we'll run a few examples to see how these work on the command line.

What we'll cover:

1. Prerequisites

2. How to Install Go

3. How to Write Your First Go Program

4. How to Work with Variables and Numbers in Go

5. How to Format Strings in Go

6. How to Work with Arrays and Slices in Go

7. How to Work with Loops in Go

8. How to Work with Functions in Go

9. How to Work with Maps in Go

10. How to Work with Structs in Go

11. Package Scope in Go

12. Conclusion

Prerequisites

To follow along with this tutorial, it’ll be helpful if you know the basics of any programming language, such as variables, data types, and data structures. I’ll assume that you’ve worked with at least one programming language before.

How to Install Go

To install Go, head to golang.org. Depending on what OS you are running, the documentation provides different installation options.

In my case, I’m using WSL (Windows Subsystem for Linux) with Ubuntu, so I’ll install Go inside that environment.

First, update your package list:

sudo apt update
sudo apt upgrade -y

Next, install a tool to download files from the internet. We’ll use wget:

sudo apt install -y wget

Now download the Go binary package:

wget https://dl.google.com/go/go1.24.2.linux-amd64.tar.gz

Extract the archive to /usr/local:

sudo tar -C /usr/local -xzf go1.24.2.linux-amd64.tar.gz

After installing Go, add the Go binary directory to your PATH so the go command is available in the terminal:

export PATH=$PATH:/usr/local/go/bin

You can make this change permanent by adding the line above to your ~/.bashrc or ~/.profile.

To confirm Go was installed successfully, run:

go version

You should see the installed Go version printed in the terminal.

If you use VS Code, you can also install the Go extension for syntax highlighting.

How to Write Your First Go Program

Before we get into writing our first program, we need to establish how Go puts its code together. In Go, every file or code is part of a package.

In this example, we’ll create a file called main.go. The name isn’t special to Go, but it’s a common convention for the file that contains the program’s entry point.

package main

import "fmt"

func main() {
	fmt.Println("Hello, ninjas")
}

This is the most important file in our project. We'll begin by making the code we’ll write in this file part of a package we call main.

The fmt import is a package from the Go standard library. fmt is for formatting strings and outputting to the console. Notice that the Println function starts with a capital letter, because within the fmt package, the method is exported. Variables or methods that are exported in Go should begin with capital letters. The Println prints a line to the console.

The main function serves as the entry point of a Go program. A compiled Go program must contain exactly one main function inside a package main. (A larger codebase can still contain multiple programs, each in its own directory with its own package main.)

So when you run a Go program, the Go toolchain builds all files in the same package together and then starts execution from the main() function. The filename main.go does not determine execution order – it’s simply a common naming convention.

Unlike other custom packages, which are used to bundle application logic into libraries or reusable code, the main package is used to specify that a program is a standalone executable.

To run the code, you can simply type go run main.go, specifying the Go file that we want to execute.

Hello, ninjas

How to Work with Variables and Numbers in Go

How to Declare Variables

A variable is just a store for data. Go does not allow unused local variables. If you declare a variable inside a function and never use it, the compiler will raise an error. This helps prevent cluttered code and unused definitions.

Let’s see how to declare variables in Go by declaring a string

package main

import "fmt"

func main() {

	// strings
	var nameOne string = "emy"

	fmt.Println(nameOne)
}

Because Go is a statically typed language, every variable must have a type at compile time. Here, we have a variable nameOne, it’s type, and then an initial value assigned to it.

But what if we don't want to state the variable type ourselves? Fortunately, Go lets us define variables without a type stated at compile time

// strings
var nameOne string = "emy"
var nameTwo = "blessing"
var nameThree string

For nameTwo, we don’t need to explicitly state the type because Go directly infers it. If you hover above the variable, you can see that Go already tells you the type. The third variable, nameThree, has no value assigned to it just yet. We’ve only just declared it.

If you log the output to the console, you can see nameOne and nameTwo displayed, but you can’t see nameThree. It’s also logged, you just can’t see it because it has no value.

emy blessing 

There’s an even shorter and simpler way to declare variables in Go:

nameFour := "peaches"

Here, Go also infers the variable type based on the value assigned to it. Notice how we also didn’t use the var keyword. You can use this method inside any function, not just in main. Just keep in mind that you can't use this method of declaring variables when reassigning or updating a variable, declaring constants, or declaring safe types.

How to Declare Integers

When it comes to declaring integers, we pretty much use the same technique as above:

var ageOne int = 20
var ageTwo = 30
ageThree := 40

fmt.Println(ageOne, ageTwo, ageThree)

When declaring integers, we can specify the amount of memory or the bit size we want an integer to have. We can declare the integer as int8, int16, or int64.

Each of these memory sizes can hold a specific range of numbers. int8, for example, can only hold integers between -128 and 127. Anything bigger than that would throw an error:

// bits and memory
	var numOne int8 = 25
	var numTwo int8 = -128

	var numThree int8 = 129 // will throw an error

Another type of integer in Go is the unsigned integer, declared with uint. You’ll use this to declare only positive integers – you can’t use it to store negative values.

uint, just like the int type, can also be associated with bit sizes. You could have a uint8, uint16, and so on. But the ranges for these are different. You can check the complete list of bit sizes for the integer type and their ranges on this Go page.

int is specifically used to declare whole integer numbers. To declare decimal numbers, you can use a float. The concept is the same with int, where you can have floats with different bit sizes. But you can only have float32 and float64, where the latter can store bigger numbers than the former.

How to Format Strings in Go

Printing Strings to the Console

We came across the fmt package at the beginning of the article. Let’s go through some of the methods this package exposes.

First, we have the Print() method which logs some output the console. This method is used to log simple strings to the command line when we just want to see the output of something, and don’t really care about the readability.

If we have two simple strings as shown below;

// Print
fmt.Print("Hello, ")
fmt.Print("world!")

// Output: Hello, world!

You can see that the code above is not on separate lines, and this is the downside of the Print function. If we had multiple things to log to the command line, this function would just lump them together and readability could suffer.

But we can enforce a new line with Print() by using the escape character \\n .

fmt.Print("hello! \\n")
fmt.Print("new line \\n")

/*
	hello! 
	new line 
*/

Using escape characters throughout our code can get tiring very quickly. Luckily for us, Go has a function that helps us achieve the perfect separate line formatting we are looking for. We don’t need to use escape characters when we use Println .

fmt.Println("Hello, friends.")
fmt.Println("How are you?")

/*
	Hello, friends.
	How are you?
*/

Format Specifiers

Sometimes, you may want to log a string to the console, but you may also want to have variables within that string. This is called a formatted string, and we can achieve this with the help of format specifiers. These format specifiers are reserved characters that Go uses at runtime to position variables within strings.

Let’s use a concrete example to see the concept better,

name := "Emy"
age := 27

fmt.Printf("my age is %v and my name is %v", age, name)

// Output: my age is Emy and my name is 27

The format specifier %v is the default format specifier that stands for variable. We can see that in the position of the format specifiers, Go has placed the values of the arguments we passed to the Printf (age and name). It's important to note that the order in which we pass these arguments is important.

As we just saw above, the output of this code:

name := "Emy"
age := 27

fmt.Printf("my age is %v and my name is %v", name, age)

Would be my age is Emy and my name is 27. The order in which we pass the arguments is the same way in which the compiler will replace the format specifier within our string.

Something new you might also notice is that we didn't use Print or Println in this code like we did before. When working with formatted directives, Go puts the functions Printf, Sprintf, and Appendf at our disposal.

• Printf directs the output to the console, as we’ve seen.

• With Sprintf, we don't direct the output to the command line, but we can store it in a variable and then use that variable somewhere else in our code.

• It gets a little more complex when working with Appendf, which formats according to a format specifier and appends the result to a byte slice (bytes are a bit out of the scope of this article, so we won’t dwell on them).

Besides the %v format specifier, we can also use %q if we want the embedded variable to have quotes around it.

// strings
	name := "Emy"

	fmt.Printf("my name is %q", name)

// output: my name is "Emy"

This will work for the name variable, but not really for the age because it’s an integer.

name := "Emy"
age := 27

fmt.Printf("my age is %q and my name is %q", name, age)

//Output: my age is '\\\\x1b' and my name is "Emy"

We also have the %T specifier, which is used to output the type of a variable.

If we wanted to get the type of age:

fmt.Printf("This is a variable of type %T", age)

The output of this would be:

This is a variable of type int

You can check out other format specifiers on the official fmt package page.

How to Work with Arrays and Slices in Go

Arrays in Go

Arrays in Go are a little bit of a mouthful. Let’s take a look at how to define an array:

var ages = [3]int{20, 25, 30}

In this code, we have the variable name on the left side as is typical. On the right side, we have [3] to specify the size of the array, the type as int , and the values for the array inside the squiggly braces.

Once we declare an array, we can never change its size. This is kind of a bummer if you ask me, because during coding, you don’t always know the size of an array when you declare it (more on this below when we talk about slices).

Arrays in Go also can’t contain multiple types. The array we declared above can’t also contain a string, for example.

If we log the array to the console alongside its length with fmt.Println(ages, len(ages)), on the console we get:

[20 25 30] 3

Slices in Go

If you need to define an array where you don’t know or don’t want to specify the size during declaration, you can use a slice. Slices are abstractions of arrays, and are more flexible than arrays because they have dynamic sizing.

var scores = []int{100, 50, 60} // we don't specify the size
scores[2] = 25 // to update a value
scores = append(scores, 50) // returns a new scores slice with 50 appended to it  (you cannot do this with arrays)
fmt.Println(scores, len(scores)) // [100 50 60 50] 4

An important part of working with arrays, slices, or any data structures that store data is knowing how to get the elements we want. We may only want to grab data that belongs to a certain range, or data at certain positions, based on certain conditions, and so on.

When it comes to dealing with ranges, say you want to output the slice elements from position 1 (that is, index 0, the first element) right up to the third position (index 2).

rangeOne := scores[0:3] // [100 50 60]

The range scores[0:3] indicates that the code should list the scores from index 0 up to index 3 minus 1. So it doesn’t include the element at index 3.

If you wanted to log from index 2 in the slice right up to the end, for example, you’d write scores[2:] . Similarly, you could log from the beginning of the slice up to and excluding some position (in this case, index 3) like so, scores[:3] .

How to Work with Loops in Go

How to Iterate Loops

Loops in Go are similar to loops in other programming languages. The difference is that Go focuses on the for loop and doesn’t really dwell on while, do-while, or for-each.

x := 0
for x < 5 {
	fmt.Println("the value of x is", x)
	x++
}

The loop above is straightforward and just prints the value of x from 0 to 4.

To create a loop that uses an iterator, you can write this:

for i := 0; i < 5; i++ {
	fmt.Println("value of i is", i)
}
    /*
		value of i is 0
		value of i is 1
		value of i is 2
		value of i is 3
		value of i is 4
	*/

It does pretty much the same thing as the loop above it, but we declared the iterator, it’s range, and we iterate over it in the same expression.

What if you wanted to iterate or loop over a slice, for example? We can also use an iterator to achieve this as we have above.

names := []string{"emy", "ble", "winkii"}

for i := 0; i < len(names); i++ {
		fmt.Println(names[i])
}

How to Use the range Keyword

Another interesting keyword related to iterations is range. Using the range keyword, you can use loops to perform actions on elements in a slice. range provides the index and value of the element in a slice, and allows you to access those within the loop.

for index, value := range names {
		fmt.Printf("the position of %v is %v \\\\n", value, index)
	}

What if you didn’t want to use the index and only the value? Well, range requires that you define an index and a value. So if you rewrite your loop like this:

for index, value := range names {
		fmt.Printf("the value is %v \\\\n", value)
}

Go is going to throw an error because you’re declaring the index but not using it.

Luckily, there’s a way to bypass this, and Go does it neatly using the blank identifier, _. We use this identifier when a method or function expects that you define a return value that you don't need.

for _, value := range names {
		fmt.Printf("the value is %v \\\\n", value)
}

You could apply the same strategy if you wanted only the index, but not the value.

for index, _ := range names {
		fmt.Printf("the index is %v \\\\n", index)
}

How to Work with Functions in Go

A function is a reusable block of code. Functions in Go are mostly created outside the main function. This way, other files can access and use them.

package main

import (
	"fmt"
)

func sayGreeting(n string){
	fmt.Printf("Good morning")
}

func main() {
	sayGreeting("emy")
}

Go also allows you to pass functions as parameters to other functions.

func cycleNames(n []string, f func(string)) {
	for _, value := range n {
		f(value)
	}
}

The function above takes a slice and a function as parameters. The function passed as a parameter in turn takes a string. You could pass a slice of names alongside the greeting function, so that for each name in the slice, you run the greeting function to print a greeting for that name.

func main(){
	cycleNames([]string{"emy", "pearl"}, sayGreeting)
}

When passing the sayGreeting function as a parameter, you don’t invoke it immediately because that’s done within the cycleNames function already. You only pass its reference.

Functions with return Values

Functions may also need to have a return value. So, how does Go handle that? Let’s see a small example:

package main

import "fmt"

func sayHello(name string) string {
	fmt.Printf("Hello %v", name)
	return name
}

func main() {
	sayHello("Emy")
}

// Output: Hello Emy

Just like with variables, we must specify the data type for every function parameter, and also specify the data type of the expected return value. In the example above, our function sayHello takes a string and returns a string.

Functions can also have multiple return values, as we see in the example below:

package main

import "fmt"

func sayHello(name string, age int) (string, int) {
	fmt.Printf("Hello %v, you are %v years old", name, age)
	return name, age
}

func main() {
	sayHello("Emy", 27)
}

Just like the previous example, we have to specify data types for our function parameters and return values.

How to Work with Maps in Go

A map in Go is a built-in, unordered collection of unique key-value pairs, similar to dictionaries in Python or hash tables in other languages. Maps provide fast lookups, insertions, and deletions.

With maps, all the keys must be of the same data type, and so must the values. If one key is a string, then all the other keys must also be strings. The same concept applies for values.

scores := map[string]float64{
		"maths":           20,
		"english":         15,
		"french":          14,
		"spanish":         12,
	}

	fmt.Println(scores)
	fmt.Println(scores["maths"])

	/*
	map[english:15 french:14 maths:20 spanish:12]
	20
	*/

You can also loop through maps to get their keys and corresponding values:

// loops maps
	for key, value := range scores {
		fmt.Println(key, "-", value)
	}

	/*
	french - 14
	spanish - 12
	maths - 20
	english - 15
	*/

When it comes to mutating maps, it's important to note that maps are reference types. Reference types are types whose variables don’t store the actual data, but rather an internal pointer to the actual data. This means that if the same data is assigned to multiple variables, when one instance gets modified, the original gets modified as well.

Let’s understand this with an example;

package main

import "fmt"

func main() {
	scores := map[string]float64{
		"maths":   20,
		"english": 15,
		"french":  14,
		"spanish": 12,
	}

	scores2 := scores

	scores2["maths"] = 15
	fmt.Println(scores)
}

// Output: map[english:15 french:14 maths:15 spanish:12]

If you check out the output, you can see that we modified the math score for scores2, but that modification also affected the original map, scores .

How to Work with Structs in Go

A big downside of using maps is that we can only store one data type for keys and one data type for values. This feels restrictive. We need a data structure that lets us store a collection of data with different data types. This is where structs (or structures) come in.

Let’s look at an example:

type Book struct {
	ID     uint
	Title  string
	Author string
	Year   int
	UserID uint
}

Here we have a Book struct. Structs are defined by specifying the key of the data you want the struct to carry, and the data type associated with that key.

package main

import "fmt"

type Book struct {
	ID     uint
	Title  string
	Author string
	Year   int
    UserID uint
}

func main() {

	var book1 Book

	book1 = Book{1, "Jane Eyre", "Jane Austen", 1990, 6}

	fmt.Println(book1)
}

We initialised the Book struct by providing it with the data we stated in its definition. If you check the output of this (and ignore that Jane Austen didn’t write Jane Eyre, of course):

{1 Jane Eyre Jane Austen 1990 6}

If you look closely, structs resemble classes from the OOP languages. They define properties (just as with methods, properties starting with a capital letter are public and can be exported), and these properties can be used within methods or functions. The difference comes at the level of inheritance, because structs, unlike classes, support only composition and not inheritance.

We can also individually modify the properties of a struct using dot notation, like so:

	var book1 Book

	book1 = Book{1, "Jane Eyre", "Jane Austen", 1990, 6}

	book1.Title = "Things Fall Apart"
	book1.Author = "Chinua Achebe"

	fmt.Println(book1)

If you check the output again, you can see that what you initialised the struct to contain has been modified at the level of the Title and Author.

{1 Things Fall Apart Chinua Achebe 1990 6}

When working with real systems, structs come in very handy when creating models or designing the structure of data you want to store in your database.

Package Scope in Go

Importing Functions Within the Same Package

When coding real applications, it's uncommon to write all our application files in one file. This can get messy very quickly. Normally, we would write a function in one file and then call it from another file.

In this case, you can declare variables and functions in other files and still use them in your entry point file. Say you create another greetings.go file and declared some variable and method in it like this:

// greetings.go
package main

import "fmt"

var points = []int{20, 90, 100, 45, 70}

func sayHello(n string) {
	fmt.Println("Hello", n)
}

Notice that there is no func main() in this file (remember that we can have only one throughout our application).

Now, in your main.go file, you can reference the sayHello() function and points variable you created.

// main.go
func main() {
	sayHello("emy")

	for _, v := range points {
		fmt.Println(v)
	}
}

To run this, you’ll need to have both files running at the same time. That is:

go run main.go greetings.go

You can see that the output is the result of running the sayHello() function and looping over the points slice.

You could also define functions and variables in the main.go file and pass them to the greetings.go file. Remember that all these functions and variables passed between files must be declared outside the main() function.

Importing Functions Across Different Packages

What if your application has, say, 100 files? Will you run all those files simultaneously? No, you won't. Since our Go code can be organised in packages, we can import a function from one package within another package. Let’s rewrite our code above, but using two different packages.

In our greetings.go file, we now have our code under a new package, greetings , and our SayHello function begins with a capital letter so that other files can import and use it.

// greetings.go
package greetings

import "fmt"

var Points = []int{20, 90, 100, 45, 70}

func SayHello(n string) {
	fmt.Println("Hello", n)
}

In our main.go file,

// main.go
package main

import (
	"fmt"
	"greetings"
)

func main() {
	greetings.SayHello("emy")

	for _, v := range points {
		fmt.Println(v)
	}
}

As you can see, we’ve imported the greetings package we declared in another file, and we can access the SayHello() method from it with dot notation.

Conclusion

In this tutorial, you’ve learned some key Go concepts. You’re now familiar with how variables, strings, arrays and slices, loops, functions, maps, structs, and package scope works in Go.

At this point, you should try to take that further by building something a little bigger so you can see just how powerful and amazing Golang is.

The official Tour of Go website is also an amazing resource to reference if you want to explore these concepts a little deeper.

Curious about the hype I saw on Bluesky, I recently joined the npmx Discord server on a whim. My journey from lurker to contributor taught me a lot about OSS and gave me new confidence going into code reviews.

In this article, I’ll walk you through my journey to give you a little insight into the process of getting involved in Open Source.

Here’s what I’ll cover:

• My Struggles with Pull Requests

• My Former View of OSS

  • The Basics of OSS

  • The Dark Side of OSS

• Getting Started with npmx

• The Not So Perfect PR

• Collaboration Over Perfection

• My Current View of OSS

• Tips for PR Authors and Reviewers

• Conclusion

My Struggles with Pull Requests

I’ll admit, I’ve always had a hard time with code reviews. I can be quite the perfectionist. I’ll entertain every nitpick and only hear the criticism.

If reviews go on for days, I easily get overwhelmed. I enjoy pairing and co-working. I want to enjoy Pull Request (PRs), but addressing PR comments takes a lot out of me.

Some of my struggle is a need for accommodations that I rarely get. I also have plenty of lived experience with how hostile code reviews can become (even in a professional setting). Finally, there’s how I was introduced to PR reviews.

Outside of work, I had only ever experienced perfunctory PRs – I’d receive at most one suggestion, but usually just got a “LGTM” (Looks Good to Me) comment. Professionally, I went from no code reviews to incredibly detailed code reviews basically overnight. I still feel like I’m playing catch up.

On the one hand, thinking deeply about every suggestion has made me a better developer. I thrive in collaborative environments with thoughtful code reviews. Developers who have worked with me have told me that they benefit from answering all my “why?” questions.

On the other hand, I demand compliments, gifs, and video calls from my reviewers. I don’t do well with a bombardment of vague comments on my PRs. I’ve spent a lot of time documenting code guidelines and review processes that other people seem to understand and remember much more easily than I do.

Developer communities have helped me navigate all of this. Community is a priceless resource for career changers and new grads. When everyone shares their experience, the uninitiated learn about how things could be and what kinds of things aren’t normal (like very hostile code reviews).

My Former View of OSS

When I’ve talked and written about developer community, I’ve recommended online networking communities, going to meetups, tech conferences, social media, writing, and posting your writing online. The one thing I haven’t written about? OSS.

My first real introduction to OSS was through the online networking group Virtual Coffee. By the end of my first Hacktoberfest, I knew the basics.

The Basics of OSS

• Find a project that interests you.

• Check the Contributing Guide.

• Claim an issue.

• Following the Contributing Guide, make a fork, write the code, and open a PR.

• The maintainer merges it.

• You did it! That’s OSS.

The Dark Side of OSS

Over time, I couldn’t help but see the “dark side” of OSS – maintainers burning out, friction between users and maintainers, corporations suddenly trying to assert control over OSS (for example, Wordpress, Ruby), and the thankless, frustrating job of maintaining a package that everyone uses but no one wants to pay for.

I have to be honest: I had begun to think of open source maintainers as Roz from Monsters Inc. – justifiably fed up with the extra work dumped on them by unappreciative people.

Meeting maintainers in-person didn’t contradict my view. Every single one had a story about burnout and lack of funding. I started to assume that anyone excited about OSS just hadn’t been in it long enough

…so my friends were quite surprised when I suddenly announced that I had joined the OSS project npmx.

Getting Started with npmx

It wasn’t the first mention of the npmx project that interested me. It wasn’t the second. It was a meme. I’ve known Daniel Roe long enough to know that he is brilliant. I like learning from people who are smarter than I am.

I reached out to Patak, and got an invite to the npmx Discord server. I was amazed by what I saw: a rapidly growing, excited, and inclusive community. I realized that I had only ever contributed to communities with at most a handful of people. My view of OSS immediately changed.

This was it. I was finally going to have fun doing PRs.

So I hopped into the npmx GitHub repository and tried to get my bearings. Very quickly, I was overwhelmed. The project moves so fast. I tried to do step 3 – claim a ticket. As far as I could tell, all the tickets were being claimed in Discord before or as they were being written.

Jono kindly welcomed me into his fork for working on the blog page, but I ran into frustrating and weird issues with running the repository (repo) locally and the pre-commit hooks. Multiple people tried to help me debug and were just as stumped as I was.

The next day, Salma arrived. The day after, she was in charge of outreach, and asked me to write a blog. Then life got in the way. I couldn’t keep my promise to context switch into a feature branch in a new repo. I felt like my only contribution was going to be a single line change on the blog page and a blog.

It didn’t help that I wasn’t happy with the blog I had started writing. I gave up on keeping up and lurked in the Discord channels. I chimed in on a few conversations, and offered to help with things like failing accessibility tests.

Four days later, the project was officially two weeks old. The maintainers announced a mandatory week of vacation – community members experienced with burnout had seen the writing on the wall. Vacation would start in 10 days, so that’s basically how long I had to get a contribution in before the alpha release.

The Not So Perfect PR

An hour later, I finally saw it – my chance to contribute code. Alex needed a toggle re-written as a checkbox. It was my time to shine. I commented on the ticket to claim it as soon as it was written. I slapped up a draft PR to show I was working on it. Predictably, my focus was once again pulled away from the repo.

A couple days later, Knowler reviewed my draft PR, and all my PR anxieties came tumbling back. This was going to be The Perfect PR. How dare anyone look at it before I was ready to defend my work. What would they think about my abilities looking at my old copy and pasted portfolio site code that I hadn’t even finished translating from React to Vue? I was legitimately embarrassed someone was looking at my code in that state.

Fueled by embarrassment and productive procrastination, I sprung into action. In what little free time I had, I must have toggled my toggle a thousand times. Three days later, it was finally in a state I was happy with. It was time to open up my PR for review.

A couple dozen comments came in. Overwhelmed, I tried to remember that I had asked for this. I resolved most of the comments and left a comment saying I’d get to the last item, forced colors mode, in the morning. Frustrated with the code for the forced colors and myself for forgetting a few tiny things, I went to play games with friends.

A few hours later, I got a DM from Daniel. He had some code for my PR. I agreed with his reasoning for all the changes and found out an entire tooltip had been added while I was blissfully ignoring the rest of the repo. (I’m confident in my ability to merge or rebase my way out of any situation.)

Splitting my attention between Enshrouded and talking to Daniel, I felt defeated. I knew I finish the forced colors fix the next day, but also adding a tooltip felt daunting. Still, it felt like I needed to do it all.

Collaboration Over Perfection

And then I remembered, this wasn’t work and it wasn’t going to come up on a performance review. I wasn’t alone – Knowler and Daniel were taking the time to help me get this PR merged because they wanted to. I had the opportunity to collaborate with some brilliant people and see how they would write the same thing.

So I pushed through my perfectionism, demanded compliments, and asked Daniel to push his changes. I told him I’d review them in the morning.

Reviewing Daniel’s code, I found that he had forgotten a couple tiny things, just like I had. The code I was frustrated with the night before was legitimately frustrating. Emulating forced colors on a Mac was giving me weird and contradictory results. I needed to test on a Windows machine to finally get it right.

Then, six days after I opened the PR, I finally merged it. I was on top of the world. I had gotten my contribution in before our vacation (and more importantly, I had received multiple compliments). Finally, I knew what to write this blog about.

My Current View of OSS

When you’re looking for a project that interests you, the code isn’t the only thing to evaluate. Early in my career, I learned three rules for evaluating software tools.

1. Check the date of the last update to make sure it’s actively maintained.

2. Look at the documentation. Is it up to date and easy to follow?

3. Check out the community. Do people get fairly quick responses to their questions?

After joining npmx, I’ve discovered that, with a few tweaks, these rules also apply to evaluating an OSS project.

1. Check out the last few tickets and PRs to see how fast the repo moves. If it’s fairly slow, you can probably claim an issue in GitHub easily. If it’s rapid, start by getting to know the community and how they’re assigning tickets.

2. You should always check the repo for a code of conduct, contributing guide, and sufficient documentation. Also evaluate the tickets. Are contributors expected to research solutions on their own or given strict requirements? How do maintainers respond to comments on issues?

3. Check out the community. An active, inclusive community makes contributing a lot more fun.

Now, my view of OSS is much more nuanced. Yes, there are issues with OSS as whole, but there’s a reason people want to fix them. OSS can be collaborative, inspirational, and enjoyable.

Tips for PR Authors and Reviewers

People underestimate the importance of the relationship between PR author and reviewer. A collaborative OSS code review process doesn’t happen in a vacuum. It takes careful cultivation by the PR author, PR reviewer, and project community.

For a long time, I focused on the responsibility of the reviewer to make the PR author comfortable (for example, compliments, gifs). Don’t get me wrong – I think one of the most important parts of a senior developer’s job is to provide constructive, actionable feedback.

But I now understand that the PR author’s sense of agency and desire to learn are just as important.

A sense of agency is a sense of control over actions and consequences. In other words, the PR author needs to feel that they have control over what goes into their PR. Before npmx, I understood this a little bit. I always ask “why?” because I’m not putting my name on code that I don’t understand and agree with. I have counseled my own junior developer that it’s his job to get PRs he’s authored reviewed and merged.

After experiencing an in-depth code review outside of work, I finally understand that a PR is a process. Reviews exist to get consensus, so “perfect” is far more subjective than I originally thought. There’s a reason you get a conversation, not a grade.

Maybe I’ll even ignore some nitpicks in the future.

A desire to learn makes remaining open to a reviewer’s suggestions and requests a lot easier. During my first npmx PR, it was only when my desire to learn outweighed my desire to prove something that I started having fun.

Conclusion

Today, March 3rd, 2026, is the alpha release of npmx, and I am very proud to be a contributor and member of the community.

I look forward to learning about OSS from Patak, fancy, smart code from Daniel, outreach from Salma, and accessibility from Knowler. I know I’ll learn many things outside of that list, too. I’m grateful I’m not the smartest person in the room and that I finally get to have fun with Pull Requests.

By the end of this guide, you'll have built a working chatroom that supports unlimited concurrent users chatting in real-time, message persistence that survives server crashes, session management so users can reconnect after network interruptions, private messaging between users, and graceful handling of slow or disconnected clients.

More importantly, you'll understand the fundamental concepts behind distributed systems. You'll learn concurrent programming with goroutines and channels, TCP socket programming for network communication, write-ahead logging for data durability, state management with mutexes, and how to design systems that degrade gracefully under failure. These concepts power everything from databases to message queues to web servers.

Table of Contents

1. What is a Distributed Chatroom?

2. What You'll Learn

3. Prerequisites

4. Tutorial Overview

5. Architecture Overview

6. Core Concepts You Need to Know

7. How to Set Up the Project Structure

8. How to Define Core Data Types

9. How to Initialize the Server

10. How to Build the Event Loop

11. How to Handle Client Connections

12. How to Implement Message Broadcasting

13. How to Add Persistence with WAL and Snapshots

14. How to Implement Session Management

15. How to Build the Command System

16. How to Create the Client

17. How to Test Your Chatroom

18. How to Deploy Your Server

19. Enhancements You Can Add

20. Conclusion

The complete source code for this project is available on GitHub if you'd like to reference it while following along.

What is a Distributed Chatroom?

A chatroom is a server that lets multiple users connect simultaneously and exchange messages in real-time. When we say "production-grade," we mean it includes features you'd expect in a real application: it persists data so messages aren't lost when the server restarts, it handles network failures gracefully, and it can support many concurrent users without slowing down.

The "distributed" aspect refers to how the system manages multiple clients connecting from different locations, all trying to send and receive messages at the same time. This introduces interesting challenges: how do you ensure everyone sees messages in the same order? How do you handle clients with slow internet connections? What happens when someone disconnects unexpectedly?

These aren't just theoretical problems. Every networked application deals with concurrency, state management, and failure handling. Whether you're building a chat app, a multiplayer game, a collaborative editor, or a trading platform, you'll face similar challenges. The patterns you'll learn here apply broadly across distributed systems.

Chat applications are excellent learning projects because they combine several challenging problems in one place. You need to manage concurrent connections safely, broadcast messages to multiple clients without blocking, handle unreliable networks, persist data durably, and ensure the system recovers gracefully from crashes. Each of these topics could be its own tutorial, but here you'll see how they work together in a real application.

What You'll Learn

This tutorial demonstrates several important concepts that are fundamental to building distributed systems. Here's what you'll learn:

1. TCP Socket Programming in Go

You'll learn how to accept incoming TCP connections, read and write data over network sockets, and handle connection failures gracefully. These skills are essential for any networked application, from web servers to database clients.

2. Concurrent Programming with Goroutines and Channels

Go's concurrency model is one of its strongest features. You'll see how to use goroutines to handle multiple clients simultaneously without blocking. You'll use channels to coordinate between goroutines safely, avoiding the common pitfalls of shared memory concurrency like race conditions and deadlocks.

3. State Management in Distributed Systems

Managing shared state across concurrent operations is tricky. You'll learn when to use mutexes versus channels, how to design lock granularity to avoid bottlenecks, and how to ensure data consistency when multiple goroutines access the same data.

4. Write-Ahead Logging (WAL) for Durability

Databases use WAL to ensure data isn't lost during crashes. You'll implement the same pattern, learning how to balance durability with performance. You'll see why fsync is critical, understand the trade-offs of different persistence strategies, and learn how to recover state after unexpected shutdowns.

5. Session Management and Reconnection

Networks are unreliable. Users disconnect, WiFi drops, mobile connections switch towers. You'll build a token-based session system that lets users reconnect seamlessly, preserving their chat history and identity without requiring passwords or complex authentication.

6. Graceful Degradation and Fault Tolerance

Perfect reliability is impossible, so you need to design for partial failures. You'll learn how to prevent slow clients from affecting fast ones, how to continue operating when persistence fails, and how to clean up resources properly when things go wrong.

Prerequisites

To get the most out of this tutorial, you should have some foundational knowledge. You don't need to be an expert, but you should be comfortable with the basics.

• Go basics (goroutines, channels, interfaces)

• TCP/IP networking fundamentals

• Basic concurrency concepts

• File I/O operations

Tutorial Overview

This tutorial takes you through building a production-ready chatroom step by step.

You'll start by exploring the overall architecture to understand how components fit together. Then you'll learn about core concepts like concurrency models and persistence strategies.

Next, you'll set up your project structure and define the core data types that represent clients, messages, and the chatroom. Then you'll implement the server initialization and event loop, which is where all coordination happens.

After that, you'll build the networking layer to handle client connections, implement message broadcasting so messages reach all users, and add persistence using write-ahead logging and snapshots.

You'll then implement session management for reconnection, build a command system for user actions, and create a simple client application to test your server.

Finally, you’ll learn how to test and deploy your chatroom, and review key lessons from building a distributed system.

By the end, you'll have a complete, working chatroom and understand how distributed systems handle concurrency, persistence, and failure recovery.

Architecture Overview

The system follows a client-server architecture with internal components that work together to provide a robust chat experience.

High-Level Architecture

Component Breakdown

1. Network Layer

• TCP Listener: Accepts incoming connections on port 9000

• Connection Handler: Manages individual client connections with dedicated goroutines

• Protocol: Simple newline-delimited text protocol

2. Client Management

Each client connection spawns two goroutines:

• Read Goroutine: Receives messages from client

• Write Goroutine: Sends messages to client (non-blocking with buffered channels)

3. ChatRoom Core

This is the heart of the system – a single goroutine running an event loop:

for {
    select {
        case client := <-cr.join:
            // Handle new client
        case client := <-cr.leave:
            // Handle disconnection
        case message := <-cr.broadcast:
            // Broadcast to all clients
        case client := <-cr.listUsers:
            // Send user list
        case dm := <-cr.directMessage:
            // Handle private message
    }
}

4. State Management

We have three synchronized data structures:

• clients map[*Client]bool: Active connections (mutex-protected)

• sessions map[string]*SessionInfo: User sessions for reconnection

• messages []Message: In-memory message history

5. Persistence Layer

Two-tier approach:

• Write-Ahead Log (WAL): Immediate append-only log for durability

• Snapshots: Periodic full state dumps for faster recovery

6. Session Management

This enables reconnection with token-based authentication:

• Generates unique tokens per user

• 1-hour session timeout

• Preserves chat history for returning users

Message Flow

Here's how a message travels through the system:

User Input → Client Read → Server Receive → Broadcast Channel 
    → ChatRoom Loop → Persist to WAL → Fan-out to All Clients
    → Client Write Goroutines → TCP Send → User Display

The broadcast channel acts as a synchronization point, ensuring total message ordering.

Core Concepts You Need to Know

Understanding the Concurrency Model

This chatroom uses Go's CSP (Communicating Sequential Processes) model. This is a fundamentally different approach to concurrency than you might be used to from other languages.

In traditional concurrent programming, you protect shared memory with locks (mutexes). Multiple threads access the same data structure, and you use locks to ensure only one thread modifies it at a time. This works, but it's error-prone. Forget a lock, and you have a race condition. Hold locks too long, and you have deadlocks.

Go encourages a different approach: instead of communicating by sharing memory, you share memory by communicating. You pass data between goroutines through channels. Only one goroutine owns the data at a time, eliminating many concurrency bugs by design.

Channels provide several advantages. They eliminate most race conditions by design, because if only one goroutine owns the data at a time, there's no race to access it. They provide natural flow control since channels can block when full (back pressure) or block when empty (waiting for data). They make it easier to reason about message flow because you can trace how data moves through your system by following the channels. And they offer better composability since you can combine channels with select statements to coordinate multiple operations.

That said, we’ll still use mutexes in this project. Channels aren't always the right tool. We’ll use mutexes when multiple goroutines need quick, frequent access to shared data structures like maps. And we’ll use channels when we want to coordinate behavior or transfer ownership of data.

Here's how the chatroom uses channels to coordinate everything:

type ChatRoom struct {
    join          chan *Client        // New connections
    leave         chan *Client        // Disconnections
    broadcast     chan string         // Messages to all
    listUsers     chan *Client        // User list requests
    directMessage chan DirectMessage  // Private messages

    // Shared state (mutex-protected)
    clients    map[*Client]bool
    mu         sync.Mutex

    // Message history (separate mutex)
    messages   []Message
    messageMu  sync.Mutex
}

Notice that we have five channels for different types of events. The main event loop receives from all these channels using a select statement. This means all state changes happen sequentially in one place, making the system much easier to reason about.

We could have used one channel that accepts different message types, but separate channels make the code clearer. When you send to chatRoom.join, it's obvious what you're doing. When you send to chatRoom.broadcast, same thing.

The mutexes protect data that many goroutines read frequently. The clients map needs to be accessed every time we broadcast a message. Using a mutex for quick read access is more efficient than passing the entire map through a channel.

Understanding the Persistence Strategy

When your server crashes (and it will eventually), you need to recover the chat history. Users expect their messages to be there when the server restarts. But persistence is expensive: writing to disk is thousands of times slower than writing to memory. So you need a strategy that balances durability with performance.

We’ll use a two-tier approach that's similar to what real databases use: WAL (Write-ahead log) and snapshots.

The WAL is your primary durability mechanism. Here's how it works: every message is immediately appended to a file called messages.wal. This file is append-only, which means we only write to the end. Append-only writes are fast because the disk doesn't need to seek to different locations.

Each message is written as a single line of JSON. After writing each message, we call fsync. This tells the operating system to actually write the data to the physical disk right now, not just buffer it in memory. Without fsync, the OS might lose your data if the power fails before it gets around to writing.

The WAL is append-only and never modified. This makes it very reliable. If the server crashes mid-write, the worst case is one corrupted line at the end, which we can detect and skip during recovery.

The problem with a write-ahead log is that it grows forever. If you have a million messages, you need to replay a million log entries every time you restart the server. That's slow.

Snapshots solve this problem. Every 5 minutes, if there are more than 100 new messages, we write the entire message history to a separate file called snapshot.json. This is the complete state of the chat at that moment.

After creating a snapshot, we truncate (empty) the WAL. New messages continue to append to the WAL, but now we only need to replay messages since the last snapshot.

When the server starts, it first loads the snapshot file (if it exists). This gives us the state from the last snapshot, which might be 100,000 messages. Loading this takes about 100ms. Then it replays all entries from the WAL. This gives us messages written since the last snapshot, which might be only 50 messages. Replaying this takes milliseconds. Finally, it resumes normal operation.

Total recovery time is a few hundred milliseconds instead of several minutes.

This two-tier system gives us the best of both worlds: fast writes during normal operation with the append-only WAL, fast recovery after crashes with snapshot plus small WAL replay, guaranteed durability through fsync after every message, and bounded recovery time because the WAL never grows too large.

The trade-off is that snapshots use more disk space temporarily since you have both the snapshot and the WAL. But disk space is cheap, and correctness is expensive.

Now that you understand the key concepts behind the chatroom's design, it's time to start building. You'll begin by setting up your project structure and creating the necessary directories and files.

How to Set Up the Project Structure

First, create the directory structure for your project. You will create their files as we walk through the tutorial:

mkdir -p chatroom-with-broadcast/cmd/server
mkdir -p chatroom-with-broadcast/cmd/client
mkdir -p chatroom-with-broadcast/internal/chatroom
mkdir -p chatroom-with-broadcast/pkg/token
mkdir -p chatroom-with-broadcast/chatdata
cd chatroom-with-broadcast

Then initialize the Go module.

Note that you’ll need Go 1.23.2 or later installed on your machine. Earlier versions might work, but the code examples assume features available in Go 1.23 and above. This version includes improvements to the standard library that make concurrent programming more efficient.

go mod init github.com/yourusername/chatroom

Your go.mod file should look like this:

module github.com/yourusername/chatroom

go 1.23.2

With your project structure in place, you're ready to start writing code. The first step is defining the data types that will represent the core components of your chatroom: messages, clients, and the chatroom itself.

How to Define Core Data Types

Create a new file internal/chatroom/types.go to define your core data structures. These types form the foundation of your chatroom, so it's important to understand what each one represents and why it's designed the way it is.

package chatroom

import (
    "net"
    "os"
    "sync"
    "time"
)

// Message represents a single chat message with metadata
type Message struct {
    ID        int       `json:"id"`
    From      string    `json:"from"`
    Content   string    `json:"content"`
    Timestamp time.Time `json:"timestamp"`
    Channel   string    `json:"channel"` // "global" or "private:username"
}

// Client represents a connected user
type Client struct {
    conn         net.Conn      // TCP connection
    username     string        // Display name
    outgoing     chan string   // Buffered channel for writes
    lastActive   time.Time     // For idle detection
    messagesSent int           // Statistics
    messagesRecv int
    isSlowClient bool          // Testing flag

    reconnectToken string
    mu             sync.Mutex   // Protects stats fields
}

// ChatRoom is the central coordinator
type ChatRoom struct {
    // Communication channels
    join          chan *Client
    leave         chan *Client
    broadcast     chan string
    listUsers     chan *Client
    directMessage chan DirectMessage

    // State
    clients       map[*Client]bool
    mu            sync.Mutex
    totalMessages int
    startTime     time.Time

    // Message history
    messages      []Message
    messageMu     sync.Mutex
    nextMessageID int

    // Persistence
    walFile       *os.File
    walMu         sync.Mutex
    dataDir       string

    // Sessions
    sessions      map[string]*SessionInfo
    sessionsMu    sync.Mutex
}

// SessionInfo tracks reconnection data
type SessionInfo struct {
    Username       string
    ReconnectToken string
    LastSeen       time.Time
    CreatedAt      time.Time
}

// DirectMessage represents a private message
type DirectMessage struct {
    toClient *Client
    message  string
}

Understanding the Message Type

The Message struct stores everything we need to know about a chat message. The ID field uniquely identifies each message and ensures messages stay in order. The Timestamp lets us show when messages were sent, which is important for chat history.

The Channel field is interesting. Right now, we only use "global" for public messages, but this design lets us add private channels or chat rooms later without changing the data structure. Good data structures anticipate future needs.

Understanding the Client Type

Each connected user is represented by a Client struct. The conn field is their TCP connection – this is how we send and receive data.

The outgoing channel is crucial for performance. Notice it's a chan string, which means it's a channel of strings. We'll make this a buffered channel (size 10). This buffer means we can queue up 10 messages for this client without blocking. If a client is slow to read, we can keep sending to other clients.

Without this buffer, one slow client would block the entire broadcast. With the buffer, slow clients just miss messages if they can't keep up, which is much better than slowing everyone down.

The lastActive timestamp helps us detect idle users. If someone hasn't sent a message in 5 minutes, we can disconnect them to free up resources.

The mu mutex protects the statistics fields. Multiple goroutines will update messagesSent and messagesRecv, so we need a mutex to prevent race conditions.

Understanding the ChatRoom Type

This is the heart of the system. Notice that we have two kinds of fields: channels and protected state.

The five channels (join, leave, broadcast, listUsers, directMessage) are how different parts of the system communicate with the main event loop. When a new client connects, we send them to the join channel. When someone sends a message, it goes to the broadcast channel.

These channels are unbuffered (capacity 0) because we want synchronization. When you send to an unbuffered channel, you block until someone receives. This ensures the event loop processes events in order.

The protected state (maps and slices) needs mutexes because multiple goroutines access it. Notice that we use separate mutexes for different data. The mu mutex protects the clients map. The messageMu mutex protects the messages slice. The sessionsMu mutex protects the sessions map.

Why separate mutexes? Performance. If we used one mutex for everything, broadcasting a message would lock all the data, preventing new clients from joining. Separate mutexes mean different operations can happen concurrently.

The WAL file (walFile) also has its own mutex (walMu) because writing to disk is slow. We don't want to hold the main mutex while waiting for disk I/O.

With your data types defined, the next step is creating a function to initialize the server. This function will set up all your data structures, restore any persisted state from previous runs, and start background workers.

How to Initialize the Server

Server initialization is critical because you need to set up all your data structures in the right order. If you restore state after opening the WAL, you might replay messages twice. If you start accepting connections before loading history, users won't see old messages.

Create a file internal/chatroom/run.go to bootstrap the server:

package chatroom

import (
    "fmt"
    "net"
    "time"
)

func NewChatRoom(dataDir string) (*ChatRoom, error) {
    cr := &ChatRoom{
        clients:       make(map[*Client]bool),
        join:          make(chan *Client),
        leave:         make(chan *Client),
        broadcast:     make(chan string),
        listUsers:     make(chan *Client),
        directMessage: make(chan DirectMessage),
        sessions:      make(map[string]*SessionInfo),
        messages:      make([]Message, 0),
        startTime:     time.Now(),
        dataDir:       dataDir,
    }

    // Restore from snapshot if available
    if err := cr.loadSnapshot(); err != nil {
        fmt.Printf("Failed to load snapshot: %v\n", err)
    }

    // Initialize WAL for new messages
    if err := cr.initializePersistence(); err != nil {
        return nil, err
    }

    // Start background snapshot worker
    go cr.periodicSnapshots()

    return cr, nil
}

func (cr *ChatRoom) periodicSnapshots() {
    ticker := time.NewTicker(5 * time.Minute)
    defer ticker.Stop()

    for range ticker.C {
        cr.messageMu.Lock()
        messageCount := len(cr.messages)
        cr.messageMu.Unlock()

        if messageCount > 100 {
            if err := cr.createSnapshot(); err != nil {
                fmt.Printf("Snapshot failed: %v\n", err)
            }
        }
    }
}

Let's break down what happens during initialization:

1. Creating Data Structures

We start by creating all the maps and channels. The make function initializes these properly. For maps, this creates an empty map ready to use. For channels, this creates an unbuffered channel (capacity 0).

Notice we create the messages slice with initial capacity 0 but room to grow: make([]Message, 0). This is more efficient than starting with nil because the slice is ready to append immediately without allocation.

2. Loading the Snapshot

Before we accept any connections, we try to load a snapshot from disk. This restores the chat history from the last time the server ran. If the snapshot doesn't exist (first run) or fails to load (corrupted file), we just continue with an empty history.

This step must happen before initializing the WAL. If we opened the WAL first, we might replay messages that are already in the snapshot, creating duplicates.

3. Initializing the WAL

The initializePersistence() function opens the WAL file in append mode. It also replays any entries in the WAL that happened after the last snapshot. This ensures we don't lose any messages that were written to the WAL but not yet included in a snapshot.

If this step fails, we return an error and refuse to start. Why? Because if we can't write to the WAL, we can't guarantee durability. It's better to refuse to start than to lie to users by accepting messages we can't persist.

4. Starting Background Workers

The periodicSnapshots() function runs in a separate goroutine. It wakes up every 5 minutes and checks if we need to create a snapshot. Notice the defer ticker.Stop() – this is important. If we forget to stop the ticker, it leaks a goroutine and wastes resources.

The goroutine acquires the messageMu lock just to read the message count, then releases it immediately. We don't hold the lock during the snapshot creation because that's slow and would block message broadcasting.

Why 5 Minutes and 100 Messages?

These are tunable parameters. 5 minutes means recovery never needs to replay more than 5 minutes of messages. 100 messages means we don't create snapshots too frequently during quiet periods.

In a production system, you might make these configurable. A high-traffic chat might want shorter intervals. A low-traffic chat might want longer intervals to reduce disk I/O.

Now that your server is initialized with all the necessary data structures and background workers, you need to build the core coordination mechanism. The event loop is where all state changes happen in your chatroom. It's the heartbeat that keeps everything synchronized.

How to Build the Event Loop

The event loop is the heart of your chatroom. Every client connection, message, and disconnection flows through this single point. This might seem like it could be a bottleneck, but it's actually what makes the system simple and safe.

The Run() method is the server's heartbeat. This is where all the magic happens. Every event in the system flows through this loop. Add this to run.go:

func (cr *ChatRoom) Run() {
    fmt.Println("ChatRoom heartbeat started...")
    go cr.cleanupInactiveClients()

    for {
        select {
        case client := <-cr.join:
            cr.handleJoin(client)

        case client := <-cr.leave:
            cr.handleLeave(client)

        case message := <-cr.broadcast:
            cr.handleBroadcast(message)

        case client := <-cr.listUsers:
            cr.sendUserList(client)

        case dm := <-cr.directMessage:
            cr.handleDirectMessage(dm)
        }
    }
}

Understanding the Select Statement

The select statement is one of Go's most powerful concurrency features. It's like a switch statement for channels. The select waits until one of its cases can proceed, then it executes that case.

Here's what happens: The loop blocks on the select statement, waiting for data on any of the five channels. When data arrives on any channel, that case executes. After the case completes, the loop goes back to waiting.

For example, when a new client connects, code elsewhere in your program sends that client to cr.join. The select receives it and executes cr.handleJoin(client). Once that finishes, the loop goes back to waiting.

Why Use a Single Event Loop?

This might seem like a bottleneck. You have one goroutine processing all events sequentially. Why not process events in parallel?

The answer is consistency. Here's what you gain from sequential processing:

1. No Race Conditions on State

Only one goroutine modifies the clients map, the messages slice, and the sessions map. You never need to worry about two operations interfering with each other. When you add a client in handleJoin, you know for certain that no other code is simultaneously removing clients or broadcasting messages.

This is incredibly powerful. Most bugs in concurrent systems come from unexpected interleaving of operations. By processing events sequentially, you eliminate an entire class of bugs.

2. Total Ordering of Events

Messages are broadcast in the order they arrive. This seems obvious, but it's important. If Alice sends "Hello" and then Bob sends "Hi", you can guarantee everyone sees them in that order. With parallel processing, you'd need additional synchronization to maintain ordering.

3. Simple State Transitions

You can reason about your system state as a series of transitions. "After this join event, the client is in the map. After this leave event, the client is removed." You don't need to worry about concurrent state changes making your reasoning invalid.

4. Easy to Debug

When something goes wrong, you can add logging to the event loop and see exactly what sequence of events led to the problem. With parallel processing, the order of events depends on thread scheduling, making bugs hard to reproduce.

Is This Actually a Bottleneck?

You might worry that sequential processing limits performance. In practice, it's fine for this workload. Here's why:

The handlers are fast. They do simple things like adding to a map, removing from a map, or forwarding a message to channels. These operations take microseconds. The event loop can process thousands of events per second.

The slow operations (writing to disk, sending to client connections) happen in other goroutines. The event loop doesn't wait for them. It just sends data to a channel or adds work to a queue, then immediately moves to the next event.

If you needed higher throughput, you could shard your chat into multiple rooms, each with its own event loop. But for a single chatroom, sequential processing is both simpler and fast enough.

Understanding the Cleanup Worker

Notice the line go cr.cleanupInactiveClients() before the loop. This starts a background goroutine that periodically checks for idle clients.

Why not include this in the event loop? Because it's time-based, not event-based. The cleanup worker wakes up every 30 seconds and sends disconnect events for idle clients. These events flow through the normal event loop, maintaining our single-threaded state mutation property.

Now add the runServer() function and shutdown handler:

import (
    "os"
    "os/signal"
    "syscall"
)

func runServer() {
    chatRoom, err := NewChatRoom("./chatdata")
    if err != nil {
        fmt.Printf("Failed to initialize: %v\n", err)
        return
    }
    defer chatRoom.shutdown()

    // Set up signal handling for graceful shutdown
    sigChan := make(chan os.Signal, 1)
    signal.Notify(sigChan, syscall.SIGINT, syscall.SIGTERM)

    go func() {
        <-sigChan
        fmt.Println("\nReceived shutdown signal")
        chatRoom.shutdown()
        os.Exit(0)
    }()

    go chatRoom.Run()

    listener, err := net.Listen("tcp", ":9000")
    if err != nil {
        fmt.Println("Error starting server:", err)
        return
    }
    defer listener.Close()

    fmt.Println("Server started on :9000")

    for {
        conn, err := listener.Accept()
        if err != nil {
            fmt.Println("Error accepting connection:", err)
            continue
        }
        fmt.Println("New connection from:", conn.RemoteAddr())
        go handleClient(conn, chatRoom)
    }
}

func (cr *ChatRoom) shutdown() {
    fmt.Println("\nShutting down...")
    if err := cr.createSnapshot(); err != nil {
        fmt.Printf("Final snapshot failed: %v\n", err)
    }
    if cr.walFile != nil {
        cr.walFile.Close()
    }
    fmt.Println("Shutdown complete")
}

The runServer() function ties everything together:

1. Create the chatroom with NewChatRoom()

2. Defer the shutdown function so it runs when the function exits

3. Start the event loop in a separate goroutine with go chatRoom.Run()

4. Listen for TCP connections on port 9000

5. For each connection, spawn a goroutine with go handleClient()

The defer statement is important. No matter how the function exits (normal return, panic, error), the shutdown function runs. This ensures we create a final snapshot and close the WAL file cleanly.

The signal handling goroutine listens for SIGINT (Ctrl+C) or SIGTERM (system shutdown). When it receives one, it calls shutdown() and exits gracefully. This means when you press Ctrl+C, the server saves its state before stopping.

With your event loop running and listening for connections, the next step is handling what happens when a client actually connects. This involves reading their username, creating a session, and setting up the communication channels.

How to Handle Client Connections

When a client connects to your server, several things need to happen: you need to establish the TCP connection, prompt for a username, create a Client object to represent them, start goroutines to read and write messages, and handle both normal disconnections and unexpected failures.

Create a file internal/chatroom/io.go for managing client connections. When a client connects, handleClient() manages the entire lifecycle:

package chatroom

import (
    "bufio"
    "fmt"
    "math/rand"
    "net"
    "strings"
    "time"
)

func handleClient(conn net.Conn, chatRoom *ChatRoom) {
    defer func() {
        if r := recover(); r != nil {
            fmt.Printf("Panic in handleClient: %v\n", r)
        }
        conn.Close()
    }()

    // Set initial timeout for username entry
    conn.SetReadDeadline(time.Now().Add(30 * time.Second))

    reader := bufio.NewReader(conn)

    // Prompt for username or reconnection
    conn.Write([]byte("Enter username (or 'reconnect:<username>:<token>'): \n"))

    input, err := reader.ReadString('\n')
    if err != nil {
        fmt.Println("Failed to read username:", err)
        return
    }
    input = strings.TrimSpace(input)

    var username string
    var reconnectToken string
    var isReconnecting bool

    // Parse reconnection attempt
    if strings.HasPrefix(input, "reconnect:") {
        parts := strings.Split(input, ":")
        if len(parts) == 3 {
            username = parts[1]
            reconnectToken = parts[2]
            isReconnecting = true
        } else {
            conn.Write([]byte("Invalid format. Use: reconnect:<username>:<token>\n"))
            return
        }
    } else {
        username = input
    }

    // Generate guest name if empty
    if username == "" {
        username = fmt.Sprintf("Guest%d", rand.Intn(1000))
    }

    // Validate reconnection or check for duplicate
    if isReconnecting {
        if chatRoom.validateReconnectToken(username, reconnectToken) {
            fmt.Printf("%s reconnected successfully\n", username)
            conn.Write([]byte(fmt.Sprintf("Welcome back, %s!\n", username)))
        } else {
            conn.Write([]byte("Invalid token or session expired.\n"))
            return
        }
    } else {
        // Prevent duplicate logins
        if chatRoom.isUsernameConnected(username) {
            conn.Write([]byte("Username already connected. Use reconnect if you lost connection.\n"))
            return
        }

        // Create or retrieve session
        chatRoom.sessionsMu.Lock()
        existingSession := chatRoom.sessions[username]
        chatRoom.sessionsMu.Unlock()

        if existingSession != nil {
            token := existingSession.ReconnectToken
            msg := fmt.Sprintf("Tip: Save this token: %s\n", token)
            msg += fmt.Sprintf("To reconnect: reconnect:%s:%s\n", username, token)
            conn.Write([]byte(msg))
        } else {
            session := chatRoom.createSession(username)
            token := session.ReconnectToken
            msg := fmt.Sprintf("Your token: %s\n", token)
            msg += fmt.Sprintf("To reconnect: reconnect:%s:%s\n", username, token)
            conn.Write([]byte(msg))
        }
    }

    // Create client object
    client := &Client{
        conn:           conn,
        username:       username,
        outgoing:       make(chan string, 10), // Buffered
        lastActive:     time.Now(),
        reconnectToken: reconnectToken,
        isSlowClient:   rand.Float64() < 0.1, // 10% chance for testing
    }

    // Clear timeout for normal operation
    conn.SetReadDeadline(time.Time{})

    // Notify chatroom
    chatRoom.join <- client

    // Send welcome message
    welcomeMsg := buildWelcomeMessage(username)
    conn.Write([]byte(welcomeMsg))

    // Start read/write loops
    go readMessages(client, chatRoom)
    writeMessages(client) // Blocks until disconnect

    // Update session on disconnect
    chatRoom.updateSessionActivity(username)
    chatRoom.leave <- client
}

func buildWelcomeMessage(username string) string {
    msg := fmt.Sprintf("Welcome, %s!\n", username)
    msg += "Commands:\n"
    msg += "  /users - List all users\n"
    msg += "  /history [N] - Show last N messages\n"
    msg += "  /msg <user> <msg> - Private message\n"
    msg += "  /token - Show your reconnect token\n"
    msg += "  /stats - Show your stats\n"
    msg += "  /quit - Leave\n"
    return msg
}

The initial 30-second timeout prevents connection exhaustion by disconnecting clients who don't enter a username quickly. The buffered outgoing channel prevents slow clients from blocking the broadcaster. Token-based reconnection lets users resume their session without complex authentication. The dual goroutine design means reading and writing happen independently, so a slow write doesn't block incoming messages.

How to Read Messages from Clients

Add the readMessages() goroutine to handles all incoming data:

func readMessages(client *Client, chatRoom *ChatRoom) {
    defer func() {
        if r := recover(); r != nil {
            fmt.Printf("Panic in readMessages for %s: %v\n", client.username, r)
        }
    }()

    reader := bufio.NewReader(client.conn)

    for {
        // Set 5-minute idle timeout
        client.conn.SetReadDeadline(time.Now().Add(5 * time.Minute))

        message, err := reader.ReadString('\n')
        if err != nil {
            if netErr, ok := err.(net.Error); ok && netErr.Timeout() {
                fmt.Printf("%s timed out\n", client.username)
            } else {
                fmt.Printf("%s disconnected: %v\n", client.username, err)
            }
            return
        }

        client.markActive() // Update activity timestamp

        message = strings.TrimSpace(message)
        if message == "" {
            continue
        }

        client.mu.Lock()
        client.messagesRecv++
        client.mu.Unlock()

        // Process commands vs. regular messages
        if strings.HasPrefix(message, "/") {
            handleCommand(client, chatRoom, message)
            continue
        }

        // Regular message - format and broadcast
        formatted := fmt.Sprintf("[%s]: %s\n", client.username, message)
        chatRoom.broadcast <- formatted
    }
}

5 minutes of idle time triggers auto-disconnect. This prevents zombie connections from consuming resources.

How to Write Messages to Clients

Add the writeMessages() function to drain the client's outgoing channel:

func writeMessages(client *Client) {
    defer func() {
        if r := recover(); r != nil {
            fmt.Printf("Panic in writeMessages for %s: %v\n", client.username, r)
        }
    }()

    writer := bufio.NewWriter(client.conn)

    for message := range client.outgoing {
        // Simulate slow client (testing mode)
        if client.isSlowClient {
            time.Sleep(time.Duration(rand.Intn(500)) * time.Millisecond)
        }

        _, err := writer.WriteString(message)
        if err != nil {
            fmt.Printf("Write error for %s: %v\n", client.username, err)
            return
        }

        err = writer.Flush()
        if err != nil {
            fmt.Printf("Flush error for %s: %v\n", client.username, err)
            return
        }
    }
}

Real-world clients have varying network speeds. A client with a slow internet connection shouldn't block message delivery to other users. This is a fundamental challenge in any system that broadcasts to multiple recipients.

To handle this, we use two techniques. First, the outgoing channel is buffered with a size of 10. This means the system can queue up 10 messages for a client without blocking. If a client temporarily slows down (maybe they're loading a large webpage in another tab), the buffer absorbs the slowdown.

Second, when broadcasting messages (which you'll see in the next section), we use non-blocking sends. If a client's buffer is full because they're consistently too slow, we skip sending to them rather than blocking everyone else. The slow client misses some messages, but everyone else continues normally. This is called graceful degradation: the system continues working even when parts of it have problems.

With client connections handled, the next step is implementing the core feature of any chat system: broadcasting messages to all connected users. Broadcasting means taking one message and sending it to many recipients efficiently and safely.

How to Implement Message Broadcasting

Broadcasting is the heart of a chat application. When one user sends a message, it needs to reach everyone else instantly. But this is trickier than it sounds because you need to persist the message for durability, send it to clients at different speeds without blocking, and maintain message ordering across all clients.

Create internal/chatroom/handlers.go to handle events.

The handleBroadcast() method is where messages reach all users:

package chatroom

import (
    "fmt"
    "strings"
    "time"
)

func (cr *ChatRoom) handleBroadcast(message string) {
    // Parse message metadata
    parts := strings.SplitN(message, ": ", 2)
    from := "system"
    actualContent := message

    if len(parts) == 2 {
        from = strings.Trim(parts[0], "[]")
        actualContent = parts[1]
    }

    // Create persistent message record
    cr.messageMu.Lock()
    msg := Message{
        ID:        cr.nextMessageID,
        From:      from,
        Content:   actualContent,
        Timestamp: time.Now(),
        Channel:   "global",
    }
    cr.nextMessageID++
    cr.messages = append(cr.messages, msg)
    cr.messageMu.Unlock()

    // Persist to WAL
    if err := cr.persistMessage(msg); err != nil {
        fmt.Printf("Failed to persist: %v\n", err)
        // Continue anyway - availability over consistency
    }

    // Collect current clients
    cr.mu.Lock()
    clients := make([]*Client, 0, len(cr.clients))
    for client := range cr.clients {
        clients = append(clients, client)
    }
    cr.totalMessages++
    cr.mu.Unlock()

    fmt.Printf("Broadcasting to %d clients: %s", len(clients), message)

    // Fan-out to all clients
    for _, client := range clients {
        select {
        case client.outgoing <- message:
            client.mu.Lock()
            client.messagesSent++
            client.mu.Unlock()
        default:
            fmt.Printf("Skipped %s (channel full)\n", client.username)
        }
    }
}

Consistency Trade-off:

If a WAL write fails, you still broadcast the message. Why? Because availability is more important than perfect consistency for a chat application. Users get their messages immediately, and you can handle WAL repair manually if needed.

How to Handle Join and Leave Events

Add these handlers to handlers.go:

func (cr *ChatRoom) handleJoin(client *Client) {
    cr.mu.Lock()
    cr.clients[client] = true
    cr.mu.Unlock()

    client.markActive()

    fmt.Printf("%s joined (total: %d)\n", client.username, len(cr.clients))

    cr.sendHistory(client, 10)

    announcement := fmt.Sprintf("*** %s joined the chat ***\n", client.username)
    cr.handleBroadcast(announcement)
}

func (cr *ChatRoom) handleLeave(client *Client) {
    cr.mu.Lock()
    if !cr.clients[client] {
        cr.mu.Unlock()
        return
    }
    delete(cr.clients, client)
    cr.mu.Unlock()

    fmt.Printf("%s left (total: %d)\n", client.username, len(cr.clients))

    // Close channel safely
    select {
    case <-client.outgoing:
        // Already closed
    default:
        close(client.outgoing)
    }

    announcement := fmt.Sprintf("*** %s left the chat ***\n", client.username)
    cr.handleBroadcast(announcement)
}

The handleJoin function adds the client to the active clients map, marks them as active for idle tracking, sends them the last 10 messages so they can see recent conversation, and broadcasts an announcement so everyone knows they joined.

The handleLeave function removes the client from the map, closes their outgoing channel safely (the select checks if it's already closed to avoid a panic), and broadcasts a departure announcement.

How to Send User Lists and History

Add these helper functions to handlers.go:

func (cr *ChatRoom) sendHistory(client *Client, count int) {
    cr.messageMu.Lock()
    defer cr.messageMu.Unlock()

    start := len(cr.messages) - count
    if start < 0 {
        start = 0
    }

    historyMsg := "Recent messages:\n"
    for i := start; i < len(cr.messages); i++ {
        msg := cr.messages[i]
        historyMsg += fmt.Sprintf(" [%s]: %s\n", msg.From, msg.Content)
    }

    select {
    case client.outgoing <- historyMsg:
    default:
    }
}

func (cr *ChatRoom) sendUserList(client *Client) {
    cr.mu.Lock()
    defer cr.mu.Unlock()

    list := "Users online:\n"
    for c := range cr.clients {
        status := ""
        if c.isInactive(1 * time.Minute) {
            status = " (idle)"
        }
        list += fmt.Sprintf("  - %s%s\n", c.username, status)
    }

    list += fmt.Sprintf("\nTotal messages: %d\n", cr.totalMessages)
    list += fmt.Sprintf("Uptime: %s\n", time.Since(cr.startTime).Round(time.Second))

    select {
    case client.outgoing <- list:
    default:
    }
}

func (cr *ChatRoom) handleDirectMessage(dm DirectMessage) {
    select {
    case dm.toClient.outgoing <- dm.message:
        dm.toClient.mu.Lock()
        dm.toClient.messagesSent++
        dm.toClient.mu.Unlock()
    default:
        fmt.Printf("Couldn't deliver DM to %s\n", dm.toClient.username)
    }
}

func (cr *ChatRoom) findClientByUsername(username string) *Client {
    cr.mu.Lock()
    defer cr.mu.Unlock()

    for client := range cr.clients {
        if client.username == username {
            return client
        }
    }
    return nil
}

func (c *Client) markActive() {
    c.mu.Lock()
    defer c.mu.Unlock()
    c.lastActive = time.Now()
}

func (c *Client) isInactive(timeout time.Duration) bool {
    c.mu.Lock()
    defer c.mu.Unlock()
    return time.Since(c.lastActive) > timeout
}

You now have a working chat system where clients can connect and exchange messages.

But there's a critical problem: if the server crashes or restarts, all messages are lost. The next step is adding persistence so messages survive failures.

How to Add Persistence with WAL and Snapshots

Persistence ensures your chat history survives server crashes and restarts. Without it, users would lose all their conversations every time the server goes down.

You'll implement this using two complementary mechanisms: a write-ahead log for immediate durability and snapshots for fast recovery.

Create internal/chatroom/persistence.go to handle data durability.

The WAL ensures messages survive crashes:

package chatroom

import (
    "bufio"
    "encoding/json"
    "fmt"
    "io"
    "os"
    "path/filepath"
)

func (cr *ChatRoom) initializePersistence() error {
    if err := os.MkdirAll(cr.dataDir, 0755); err != nil {
        return fmt.Errorf("create data dir: %w", err)
    }

    walPath := filepath.Join(cr.dataDir, "messages.wal")

    if err := cr.recoverFromWAL(walPath); err != nil {
        fmt.Printf("Recovery failed: %v\n", err)
    }

    file, err := os.OpenFile(walPath, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
    if err != nil {
        return fmt.Errorf("open wal: %w", err)
    }

    cr.walFile = file
    fmt.Printf("WAL initialized: %s\n", walPath)
    return nil
}

func (cr *ChatRoom) recoverFromWAL(walPath string) error {
    file, err := os.Open(walPath)
    if err != nil {
        if os.IsNotExist(err) {
            fmt.Println("No WAL found (fresh start)")
            return nil
        }
        return err
    }
    defer file.Close()

    scanner := bufio.NewScanner(file)
    recovered := 0

    for scanner.Scan() {
        line := scanner.Text()
        if line == "" {
            continue
        }

        var msg Message
        if err := json.Unmarshal([]byte(line), &msg); err != nil {
            fmt.Printf("Skipping corrupt line: %s\n", line)
            continue
        }

        cr.messages = append(cr.messages, msg)

        if msg.ID >= cr.nextMessageID {
            cr.nextMessageID = msg.ID + 1
        }
        recovered++
    }

    fmt.Printf("Recovered %d messages\n", recovered)
    return nil
}

func (cr *ChatRoom) persistMessage(msg Message) error {
    cr.walMu.Lock()
    defer cr.walMu.Unlock()

    data, err := json.Marshal(msg)
    if err != nil {
        return err
    }

    _, err = cr.walFile.Write(append(data, '\n'))
    if err != nil {
        return err
    }

    return cr.walFile.Sync()
}

Each line is a JSON-encoded message:

{"id":1,"from":"Alice","content":"Hello world","timestamp":"2024-02-06T10:00:00Z","channel":"global"}
{"id":2,"from":"Bob","content":"Hi Alice!","timestamp":"2024-02-06T10:00:05Z","channel":"global"}

The Sync() call is critical for durability. Without it, the OS might buffer writes in memory, losing them on a crash. The trade-off is that Sync() is expensive (about 1-10ms per call). Production systems might batch multiple messages to improve throughput.

How to Create and Load Snapshots

Add snapshot functionality to persistence.go:

func (cr *ChatRoom) createSnapshot() error {
    snapshotPath := filepath.Join(cr.dataDir, "snapshot.json")
    tempPath := snapshotPath + ".tmp"

    file, err := os.Create(tempPath)
    if err != nil {
        return err
    }
    defer file.Close()

    cr.messageMu.Lock()
    data, err := json.MarshalIndent(cr.messages, "", "  ")
    cr.messageMu.Unlock()

    if err != nil {
        return err
    }

    if _, err := file.Write(data); err != nil {
        return err
    }

    if err := file.Sync(); err != nil {
        return err
    }

    file.Close()

    if err := os.Rename(tempPath, snapshotPath); err != nil {
        return err
    }

    fmt.Printf("Snapshot created (%d messages)\n", len(cr.messages))
    return cr.truncateWAL()
}

func (cr *ChatRoom) truncateWAL() error {
    cr.walMu.Lock()
    defer cr.walMu.Unlock()

    if cr.walFile != nil {
        cr.walFile.Close()
    }

    walPath := filepath.Join(cr.dataDir, "messages.wal")
    file, err := os.OpenFile(walPath, os.O_TRUNC|os.O_CREATE|os.O_WRONLY, 0644)
    if err != nil {
        return err
    }
    cr.walFile = file
    fmt.Println("WAL truncated")
    return nil
}

func (cr *ChatRoom) loadSnapshot() error {
    snapshotPath := filepath.Join(cr.dataDir, "snapshot.json")
    file, err := os.Open(snapshotPath)
    if err != nil {
        if os.IsNotExist(err) {
            return nil
        }
        return err
    }
    defer file.Close()

    data, err := io.ReadAll(file)
    if err != nil {
        return err
    }

    cr.messageMu.Lock()
    err = json.Unmarshal(data, &cr.messages)
    cr.messageMu.Unlock()

    if err != nil {
        return err
    }

    for _, msg := range cr.messages {
        if msg.ID >= cr.nextMessageID {
            cr.nextMessageID = msg.ID + 1
        }
    }

    fmt.Printf("Loaded %d messages from snapshot\n", len(cr.messages))
    return nil
}

Writing to .tmp then renaming ensures you never have a half-written snapshot. Even if power fails mid-write, the old snapshot remains valid.

Recovery Flow

When the server starts, it first loads the snapshot if it exists, which might contain 100K messages and takes about 100ms. Then it replays WAL entries written since the snapshot, which might be only recent messages. Total recovery time is seconds instead of minutes.

With persistence in place, your messages are safe. But network connections are unreliable. Users get disconnected when their WiFi drops, their phone switches towers, or their laptop goes to sleep. The next step is implementing session management so users can reconnect without losing their identity or chat history.

How to Implement Session Management

Session management lets users reconnect to your server after network interruptions without needing to create a new account or re-enter credentials. You'll implement this using cryptographically secure tokens that persist across connections.

Create internal/chatroom/session.go for reconnection handling.

package chatroom

import (
    "fmt"
    "time"

    "github.com/yourusername/chatroom/pkg/token"
)

func (cr *ChatRoom) createSession(username string) *SessionInfo {
    cr.sessionsMu.Lock()
    defer cr.sessionsMu.Unlock()

    tok := token.GenerateToken()

    session := &SessionInfo{
        Username:       username,
        ReconnectToken: tok,
        LastSeen:       time.Now(),
        CreatedAt:      time.Now(),
    }

    cr.sessions[username] = session

    fmt.Printf("Created session for %s (token: %s...)\n", username, tok[:8])

    return session
}

func (cr *ChatRoom) validateReconnectToken(username, token string) bool {
    cr.sessionsMu.Lock()
    defer cr.sessionsMu.Unlock()

    session, exists := cr.sessions[username]
    if !exists {
        return false
    }

    if session.ReconnectToken != token {
        return false
    }

    if time.Since(session.LastSeen) > 1*time.Hour {
        delete(cr.sessions, username)
        return false
    }

    session.LastSeen = time.Now()

    return true
}

func (cr *ChatRoom) updateSessionActivity(username string) {
    cr.sessionsMu.Lock()
    defer cr.sessionsMu.Unlock()

    if session, exists := cr.sessions[username]; exists {
        session.LastSeen = time.Now()
    }
}

func (cr *ChatRoom) isUsernameConnected(username string) bool {
    cr.mu.Lock()
    defer cr.mu.Unlock()

    for client := range cr.clients {
        if client.username == username {
            return true
        }
    }

    return false
}

func (cr *ChatRoom) cleanupInactiveClients() {
    ticker := time.NewTicker(30 * time.Second)
    defer ticker.Stop()

    for range ticker.C {
        cr.mu.Lock()
        var toRemove []*Client

        for client := range cr.clients {
            if client.isInactive(5 * time.Minute) {
                fmt.Printf("Removing inactive: %s\n", client.username)
                toRemove = append(toRemove, client)
            }
        }
        cr.mu.Unlock()

        for _, client := range toRemove {
            cr.leave <- client
        }
    }
}

How to Generate Secure Tokens

Create pkg/token/token.go for token generation:

package token

import (
    "crypto/rand"
    "encoding/hex"
)

// GenerateToken returns a secure random 16-byte hex token
func GenerateToken() string {
    b := make([]byte, 16)
    _, _ = rand.Read(b)
    return hex.EncodeToString(b)
}

Tokens here are transmitted in plaintext over TCP. For production use, you should use TLS encryption to protect tokens in transit, hash tokens before storage so a database breach doesn't expose them, and implement rate limiting on reconnection attempts to prevent brute force attacks.

Your chatroom now supports basic messaging and reconnection. But users need ways to interact with the system beyond just sending messages. The command system provides features like listing users, viewing history, and sending private messages.

How to Build the Command System

Commands are messages that start with a forward slash and perform special actions instead of being broadcast to everyone. This is a pattern used by many chat applications like Slack and Discord. You'll implement several useful commands that enhance the user experience.

Add command handling to io.go:

func handleCommand(client *Client, chatRoom *ChatRoom, command string) {
    parts := strings.Fields(command)
    if len(parts) == 0 {
        return
    }

    switch parts[0] {
    case "/users":
        chatRoom.listUsers <- client

    case "/stats":
        client.mu.Lock()
        stats := fmt.Sprintf("Your Stats:\n")
        stats += fmt.Sprintf("  Messages sent: %d\n", client.messagesSent)
        stats += fmt.Sprintf("  Messages received: %d\n", client.messagesRecv)
        stats += fmt.Sprintf("  Last active: %s ago\n", 
            time.Since(client.lastActive).Round(time.Second))
        client.mu.Unlock()

        select {
        case client.outgoing <- stats:
        default:
        }

    case "/msg":
        if len(parts) < 3 {
            select {
            case client.outgoing <- "Usage: /msg <username> <message>\n":
            default:
            }
            return
        }

        targetUsername := parts[1]
        messageText := strings.Join(parts[2:], " ")

        targetClient := chatRoom.findClientByUsername(targetUsername)
        if targetClient == nil {
            select {
            case client.outgoing <- fmt.Sprintf("User '%s' not found\n", targetUsername):
            default:
            }
            return
        }

        privateMsg := fmt.Sprintf("[From %s]: %s\n", client.username, messageText)
        select {
        case targetClient.outgoing <- privateMsg:
        default:
            select {
            case client.outgoing <- fmt.Sprintf("%s's inbox is full\n", targetUsername):
            default:
            }
            return
        }

        select {
        case client.outgoing <- fmt.Sprintf("Message sent to %s\n", targetUsername):
        default:
        }

    case "/history":
        count := 20
        if len(parts) > 1 {
            fmt.Sscanf(parts[1], "%d", &count)
        }
        if count > 100 {
            count = 100
        }
        cr.sendHistory(client, count)

    case "/token":
        chatRoom.sessionsMu.Lock()
        session := chatRoom.sessions[client.username]
        chatRoom.sessionsMu.Unlock()

        if session != nil {
            msg := fmt.Sprintf("Your reconnect token:\n")
            msg += fmt.Sprintf("   reconnect:%s:%s\n", client.username, session.ReconnectToken)
            select {
            case client.outgoing <- msg:
            default:
            }
        }

    case "/quit":
        announcement := fmt.Sprintf("%s left the chat\n", client.username)
        chatRoom.broadcast <- announcement

        select {
        case client.outgoing <- "Goodbye!\n":
        default:
        }

        time.Sleep(100 * time.Millisecond)
        client.conn.Close()

    default:
        select {
        case client.outgoing <- fmt.Sprintf("Unknown: %s\n", parts[0]):
        default:
        }
    }
}

Your server is now complete with all the core features: connection handling, message broadcasting, persistence, session management, and commands. But to actually use your chatroom, you need a client application. The client is much simpler than the server because it just needs to connect and relay messages.

How to Create the Client

The client application provides the user interface for your chatroom. It connects to the server, displays incoming messages, and sends outgoing messages typed by the user. While the server is complex with many concurrent components, the client is straightforward

Create internal/chatroom/client.go for the client implementation.

package chatroom

import (
    "bufio"
    "fmt"
    "net"
    "os"
    "strings"
)

func StartClient() {
    conn, err := net.Dial("tcp", ":9000")
    if err != nil {
        fmt.Println("Error connecting:", err)
        return
    }
    defer conn.Close()

    fmt.Println("Connected to chat server")

    // Background goroutine: read from server
    go func() {
        reader := bufio.NewReader(conn)
        for {
            message, err := reader.ReadString('\n')
            if err != nil {
                fmt.Println("Disconnected from server.")
                os.Exit(0)
            }
            // Clear current prompt line and print message
            fmt.Print("\r" + message)
            fmt.Print(">> ")
        }
    }()

    // Main goroutine: read from stdin
    inputReader := bufio.NewReader(os.Stdin)
    fmt.Println("Welcome to the chat server!")

    for {
        fmt.Print(">> ")
        message, _ := inputReader.ReadString('\n')
        message = strings.TrimSpace(message)

        if message == "" {
            continue
        }

        conn.Write([]byte(message + "\n"))
    }
}

How the Client Works:

The client uses two goroutines to handle communication simultaneously. The main goroutine reads from stdin (your keyboard) and sends messages to the server. When you type a message and press Enter, it gets sent over the TCP connection immediately.

The background goroutine continuously reads from the server. Whenever a message arrives, it prints it to your screen. The \r (carriage return) clears the current >> prompt before printing the message, so new messages don't appear on the same line as your input. After printing the message, it reprints the prompt so you can continue typing.

This dual-goroutine design means you can receive messages while typing. If someone sends a message while you're in the middle of typing yours, their message appears immediately and your prompt reappears below it.

The defer conn.Close() ensures the connection is properly closed when the function exits. If the server disconnects, the read goroutine gets an error and calls os.Exit(0) to terminate the entire client program gracefully.

How to Create Entry Points

Create cmd/server/main.go:

package main

import (
    "fmt"
    "os"

    "github.com/yourusername/chatroom/internal/chatroom"
)

func main() {
    fmt.Println("Starting server from cmd/server...")
    chatroom.StartServer()
    os.Exit(0)
}

Create cmd/client/main.go:

package main

import (
    "fmt"
    "github.com/yourusername/chatroom/internal/chatroom"
)

func main() {
    fmt.Println("Starting client from cmd/client...")
    chatroom.StartClient()
}

Add a wrapper function in internal/chatroom/server.go:

package chatroom

func StartServer() {
    runServer()
}

With all your entry points created, your chatroom is complete and ready to test. The next step is learning how to test your implementation to ensure everything works correctly.

How to Test Your Chatroom

Testing a concurrent system like a chatroom requires a different approach than testing typical sequential code. You need to verify that goroutines coordinate correctly, messages arrive in the right order, and the system handles edge cases like disconnections.

How to Write Unit Tests

Unit tests verify individual components in isolation. For your chatroom, the most important test is verifying that messages broadcast correctly to all connected clients.

Create internal/chatroom/chatroom_test.go:

package chatroom

import (
    "testing"
    "strings"
    "time"
)

func TestBroadcast(t *testing.T) {
    cr, _ := NewChatRoom("./testdata")
    defer cr.shutdown()

    go cr.Run()

    // Create mock clients
    client1 := &Client{
        username: "Alice",
        outgoing: make(chan string, 10),
    }
    client2 := &Client{
        username: "Bob",
        outgoing: make(chan string, 10),
    }

    // Join clients
    cr.join <- client1
    cr.join <- client2
    time.Sleep(100 * time.Millisecond)

    // Broadcast message
    cr.broadcast <- "[Alice]: Hello!"

    // Verify both receive it
    select {
    case msg := <-client1.outgoing:
        if !strings.Contains(msg, "Hello!") {
            t.Fatal("Client1 didn't receive correct message")
        }
    case <-time.After(1 * time.Second):
        t.Fatal("Client1 didn't receive message")
    }

    select {
    case msg := <-client2.outgoing:
        if !strings.Contains(msg, "Hello!") {
            t.Fatal("Client2 didn't receive correct message")
        }
    case <-time.After(1 * time.Second):
        t.Fatal("Client2 didn't receive message")
    }
}

Understanding the Test:

This test creates a chatroom instance and starts its event loop with go cr.Run(). Then it creates two mock clients. Notice these aren't real TCP connections – they're just Client structs with outgoing channels. This lets you test the broadcast logic without needing actual network connections.

The test sends both clients to the join channel, waits 100 milliseconds for them to be processed, then broadcasts a message. The select statements with timeout are crucial. They try to receive from each client's outgoing channel, but if nothing arrives within 1 second, the test fails. This prevents the test from hanging forever if something goes wrong.

The time.Sleep(100 * time.Millisecond) gives the event loop time to process the join events before broadcasting. In a real system, you'd use channels to synchronize, but for tests, a small sleep is acceptable.

Run tests with:

go test ./internal/chatroom -v

The -v flag shows verbose output, printing each test as it runs. You'll see whether the broadcast test passes and how long it took. Below is the output showing that the test passed:

How to Do Integration Testing

Integration tests verify the entire system working together – the real server, real clients, and real network connections. Unlike unit tests that mock components, integration tests exercise the full stack.

Test the full client-server flow:

# Terminal 1: Start server
go run cmd/server/main.go

# Terminal 2: Client 1
go run cmd/client/main.go
# Enter username: Alice

# Terminal 3: Client 2  
go run cmd/client/main.go
# Enter username: Bob

# Terminal 4: Client 3  
go run cmd/client/main.go
# Enter username: John

# Test messaging between clients

What to Test:

Once you have the server running and multiple clients connected, you can verify all the features you built. Here's what a complete test session looks like:

1. Basic Messaging: Send a message from Alice and verify Bob and John both receive it. You should see the message appear in all client windows with the sender's username in brackets. Try sending from each client to verify the broadcast works in all directions.

2. Join and Leave Announcements: When a new client connects, all existing clients should see a "joined the chat" announcement. When someone disconnects (either with /quit or by closing their terminal), everyone should see a "left the chat" message. This confirms your join and leave handlers work correctly.

3. Private Messaging: Use /msg Bob this is a private message from Alice's client. The message should appear only in Bob's window, not in John's or Alice's. Try sending private messages between different pairs of users to verify the routing works correctly. The sender should receive a confirmation that the message was sent.

4. User List: Run /users from any client. You should see a list of all connected users. If someone has been idle for over a minute, they should show an "(idle)" status. The command should also display total message count and server uptime.

5. Chat History: New clients should automatically receive the last 10 messages when they join. You can also use /history 20 to request the last 20 messages. This verifies your message persistence is working.

6. Session Reconnection: From one client, use /token to get your reconnection token. It will look something like reconnect:Alice:338f04ca.... Copy this token, disconnect the client with Ctrl+C, start a new client, and paste the reconnection string when prompted. You should rejoin the chat with your previous identity, and other users won't see duplicate join announcements.

7. Statistics: Use /stats to see how many messages you've sent and received, and when you were last active. This verifies the client-side statistics tracking works.

8. Error Handling: Try connecting with a username that's already in use – you should be rejected. Try sending a private message to a non-existent user – you should get an error. Try using an invalid reconnection token – you should be denied. These tests verify your validation logic works.

Look at the server terminal to see the server's perspective. You'll see connection logs, broadcast confirmations, and any errors. When clients disconnect, you should see their sessions being updated. When the server creates snapshots, you'll see those logged, too.

Integration testing catches problems that unit tests miss, like network timeouts, message ordering issues across multiple clients, or problems with how the WAL file is created and locked. The screenshot below shows a successful integration test with three clients (Alice, Bob, and John) all communicating successfully, with private messages, public broadcasts, and proper join/leave handling.

How to Deploy Your Server

Deploying your chatroom means running it on a server that stays up 24/7, automatically restarts if it crashes, and starts when the server boots. There are several approaches depending on your infrastructure.

How to Use Systemd

Systemd is the standard init system on most Linux distributions. It manages services, handles restarts, and ensures your chatroom starts on boot.

Create /etc/systemd/system/chatroom.service:

[Unit]
Description=Chatroom Server
After=network.target

[Service]
Type=simple
User=chatroom
WorkingDirectory=/opt/chatroom
ExecStart=/opt/chatroom/server
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

Understanding the Configuration:

The [Unit] section describes the service and its dependencies. After=network.target ensures the network is up before starting your chatroom.

The [Service] section defines how to run your server. Type=simple means systemd should just run the command and consider it started. User=chatroom runs the server as a dedicated user (not root) for security. WorkingDirectory sets where the server runs, which is important because your WAL and snapshot files are created relative to this directory.

Restart=on-failure tells systemd to automatically restart your server if it crashes. RestartSec=5s waits 5 seconds before restarting, preventing rapid restart loops if there's a persistent problem.

The [Install] section makes your service start at boot when you enable it.

Deploying Your Server:

First, build your server binary:

go build -o server cmd/server/main.go

Then copy it to the deployment location:

sudo mkdir -p /opt/chatroom
sudo cp server /opt/chatroom/
sudo mkdir -p /opt/chatroom/chatdata

Create a dedicated user for running the service:

sudo useradd -r -s /bin/false chatroom
sudo chown -R chatroom:chatroom /opt/chatroom

Enable and start the service:

sudo systemctl enable chatroom
sudo systemctl start chatroom

Check that it's running:

sudo systemctl status chatroom

You can view logs with:

sudo journalctl -u chatroom -f

The -f flag follows the logs in real-time, similar to tail -f.

How to Use Docker

Docker packages your application with all its dependencies, making it easy to deploy anywhere that runs Docker.

Create a Dockerfile:

FROM golang:1.23-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN go build -o server cmd/server/main.go

FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /app/server .
COPY --from=builder /app/chatdata ./chatdata
EXPOSE 9000
CMD ["./server"]

Understanding the Dockerfile:

This uses a multi-stage build. The first stage (builder) uses the full Go image to compile your server. The second stage uses a minimal Alpine Linux image and copies only the compiled binary. This keeps the final image small (about 20MB instead of 800MB).

EXPOSE 9000 documents which port the container uses. CMD ["./server"] specifies what command runs when the container starts.

Build and Run:

docker build -t chatroom .
docker run -p 9000:9000 -v $(pwd)/chatdata:/root/chatdata chatroom

The -p 9000:9000 maps port 9000 in the container to port 9000 on your host, making the chatroom accessible. The -v $(pwd)/chatdata:/root/chatdata mounts your local chatdata directory into the container, so messages persist even if you stop and remove the container.

Running in Production:

For production, you'd typically use Docker Compose or Kubernetes. Here's a simple docker-compose.yml:

version: '3.8'
services:
  chatroom:
    build: .
    ports:
      - "9000:9000"
    volumes:
      - ./chatdata:/root/chatdata
    restart: unless-stopped

Run with:

docker-compose up -d

The restart: unless-stopped policy ensures your container restarts automatically if it crashes or if the Docker daemon restarts

Enhancements You Could Add

1. Multi-Room Support

You could add the concept of channels/rooms like this:

type ChatRoom struct {
    rooms map[string]*Room
}

type Room struct {
    name    string
    clients map[*Client]bool
    history []Message
}

2. User Authentication

You could replace simple usernames with proper authentication for added security:

type User struct {
    ID           int
    Username     string
    PasswordHash string
    Email        string
    CreatedAt    time.Time
}

3. File Sharing

You could allow users to upload files:

type FileMessage struct {
    Message
    FileName string
    FileSize int64
    FileURL  string
}

4. WebSocket Support

You could add HTTP/WebSocket endpoint for web clients.

5. Horizontal Scaling

For massive scale, you could shard across multiple servers using Redis pub/sub or NATS for inter-server communication.

Conclusion

You've now built a production-ready distributed chatroom from scratch. This project demonstrates important distributed systems concepts including concurrency patterns, network programming, state management, persistence, and fault tolerance.

Additional resources:

• Go Concurrency: "Concurrency in Go" by Katherine Cox-Buday

• Distributed Systems: "Designing Data-Intensive Applications" by Martin Kleppmann

• Networking: "Unix Network Programming" by Stevens

The full source code is available on GitHub. Feel free to open issues or contribute improvements.

As always, I hope you enjoyed this guide and learned something. If you want to stay connected or see more hands-on DevOps content, you can follow me on LinkedIn.

Polars is an open-source library, originally written in Rust, which makes data wrangling easier in Python. The syntax of Polars is very similar to Pandas, so if you’ve worked with Pandas or the PySpark library before, using Polars should be a breeze.

Polars excels at giving fast results. It’s also memory efficient and helps you optimize your code using parallelism. It also lets you convert data from and to various libraries like NumPy, Pandas, and others.

In this tutorial, we’ll be learning about the Polars Library from absolute scratch, from installing and importing the library on the system, to manipulating data in a dataset with the help of this library.

First, we’ll look at Polars basic functions. We’ll be also writing some practical code, which will help you apply what you’ve learned. Finally, we’ll be working with an example dataset to solidify some more key Polars concepts. Let’s dive in.

Table of Contents

• Prerequisites

• Installing and Importing the Polars Library

• What is a Series?

• What is a DataFrame?

• How to Read CSV Files with Polars

• Some other Important Functions

• Summary

Prerequisites

Even though this tutorial is beginner-friendly, having some basic knowledge of the following areas will help you understand this article better:

• Basic Python syntax

• Data structures

• Ability to import libraries and knowledge of using functions and methods

• Basics of NumPy and Pandas will come in handy (not necessary).

Now, that you’re aware of the prior requirements to follow along, let’s get started with our tutorial.

Installing and Importing the Polars Library

To install the Polars library, you can use the following command in your terminal:

pip install polars

Now, this works if you already have the pip package manager on your system. If you’re on a conda environment, you can work with this:

conda install -c conda-forge polars

But I strongly recommend using the pip package manager to avoid various inconveniences.

Let’s import Polars in our program. We’ll follow the same process as we use for importing other libraries in Python:

import polars as pl # pl is a conventional alias

While creating a Polars object with the data, it’s important to know the size of our data. Polars has the capacity to have 2³² rows in the DataFrame. To load more data, use the following command to install the Polars library:

pip install polars[rt64]

If you want to use the Polars library right away without actually installing it on your system, using a Google Colab notebook is the best option. When using a Google Colab Notebook, you can directly import and start using Polars in your program. I’ll be using Google Colab Notebook for this tutorial.

What is a Series?

A series is a fundamental element of a DataFrame. It’s a 1-dimensional data-structure that you can correlate with a ‘list’ in Python or a ‘1-D array’ in NumPy. But the difference between a series and a 1-D array is that the former is labeled while the later is not. Many series come together to form a DataFrame.

We can create a series with homogenous data as well as heterogenous data.

Creating a Series with Homogenous Data

In a series, the datatype of all the elements should be the same. If it’s not, an error is thrown.

The syntax to define a Polars series is as follows:

var_name = pl.Series(“column_name”, [values])

The following code shows an example of a homogenous series definition in Python:

import polars as pl
series_homo = pl.Series("Numbers", ['One', 'Two', 'Three', 'Four', 'Five'])
print(series_homo)

Output:

shape: (5,)
Series: 'Numbers' [str]
[
    "One"
    "Two"
    "Three"
    "Four"
    "Five"
]

In the above code, we first imported the Polars library using the pl alias to start using it throughout the code. Using aliases is a matter of choice, but pl is a conventional one (like np for NumPy and pd for Pandas). The benefit of using conventional aliases is that when you hand over the code to someone else, it’s easy for them to follow along.

Next, we used the pl.Series() function to create a Polars series object. As its first parameter, we passed the label for our series (Numbers in this case). Then we passed the values to be stores in the form of a list. Remember that the list of values that we pass acts as a single argument. Finally, we printed our series.

We can see that the output tells us about the dimensions of the the Polars object as well as the datatype of the series. The shape (rows, columns) tells us about the the number of rows and columns present in the Polars object.

We can find the data-type of a homogenous series explicitly by using the dtype method.

print(series_homo.dtype)

Output:

String

Creating a Series with Heterogenous Data

Heterogenous data means that the data-type of all the elements is not the same. The syntax to define a series with heterogenous data is as follows:

var_name = pl.Series(“Column_name”, [values], strict=False)

So you’re probably wondering, based on what I said above: how can we have a series with heterogenous data? Well, one thing to note is that a series is always homogenous irrespective of the data that is fed to it. I’ll explain below - first let’s look at this code:

import polars as pl

series_hetero = pl.Series("Numbers", [1, "Two", 3, "Four"], strict=False)
print(series_hetero)

Output:

shape: (4,)
Series: 'Numbers' [str]
[
    "1"
    "Two"
    "3"
    "Four"
]

Here, we created a series object using the pl.Series() function, labelled it, and passed the values that we want in our series.

But you’ll notice that we have provided heterogenous data (data that doesn’t have the same datatype) to the function. Usually, this throws an error. But as we have set the strict parameter as False, the function now becomes lenient with the schema of the series. (The schema is just the expected data-type of the values that are to be recorded in the series.)

If no particular schema is defined for a series that’s fed heterogenous data, pl.Series() sets the schema to pl.Utf8 (string datatype). You can see this automatic fixing of the schema in the above example. This prevents the program from bugging, as a string datatype can comprehend characters – numbers as well as symbols.

Also, we can see that datatype of all elements is the same (pl.Utf8). This means that the series is homogenous, even though we put heterogenous data in it.

If we define a schema for the series, then the Polars library converts all the records – which show a different datatype than the defined schema – to null objects. This should be clear in the following example:

import polars as pl
# defined the schema as Integer bit 32
series = pl.Series("ints", [1, -2, 3, 4, 5, 'Thirteen', 'Fourteen'], dtype=pl.Int32, strict=False)
print(series)

Output:

shape: (7,)
Series: 'ints' [i32]
[
    1
    -2
    3
    4
    5
    null
    null
]

Here, we can see that the last two entities were ‘String’, but since we set the schema as ‘Integer’, they were reflected as null records.

So as you can see, the leniency of the program depends on whether you set the strict parameter to True of False. If we set it as True, we enforce the schema to the data strictly. Upon failing to obey the schema, the program raises an exception. On the other hand, if we set the strict parameter as False, the series still preserves its homogenous nature by turning schema-disobeying elements to null.

Now that you understand how series work, we’re ready to move on to DataFrames.

What is a DataFrame?

A DataFrame is a two-dimensional data structure that you can use to store large numbers of related parameters of the collected data. It’s also useful for analyzing that data. A DataFrame is nothing more than the collection of many series, each labelled differently to store different aspects of data.

Here’s the syntax to create a Polars DataFrame object:

var_name = pl.DataFrame({key: value pairs}, schema)

The following example shows you how to define a DataFrame object in Python:

import polars as pl
import numpy as np

schema = {"Number": pl.UInt32, "Natural Log": None, "Log Base 10": None}

df = pl.DataFrame(
    {
        "Number" : np.arange(1, 11),
        "Natural Log" : [np.log(x) for x in range(1,11)],
        'Log Base 10' : [np.log10(x) for x in range(1,11)]
        },
    schema=schema
    )
print(df)

Output:

shape: (10, 3)
┌────────┬─────────────┬─────────────┐
│ Number ┆ Natural Log ┆ Log Base 10 │
│ ---    ┆ ---         ┆ ---         │
│ u32    ┆ f64         ┆ f64         │
╞════════╪═════════════╪═════════════╡
│ 1      ┆ 0.0         ┆ 0.0         │
│ 2      ┆ 0.693147    ┆ 0.30103     │
│ 3      ┆ 1.098612    ┆ 0.477121    │
│ 4      ┆ 1.386294    ┆ 0.60206     │
│ 5      ┆ 1.609438    ┆ 0.69897     │
│ 6      ┆ 1.791759    ┆ 0.778151    │
│ 7      ┆ 1.94591     ┆ 0.845098    │
│ 8      ┆ 2.079442    ┆ 0.90309     │
│ 9      ┆ 2.197225    ┆ 0.954243    │
│ 10     ┆ 2.302585    ┆ 1.0         │
└────────┴─────────────┴─────────────┘

Above, we created a Polars DataFrame object with the pl.DataFrame() function. In the function, we created a dictionary as an argument for passing the values of the DataFrame.

In the dictionary, each key-value pair represents a series. Each key represents the label of the series, whereas its value represent the values of the series. The values are passed in the form of a list as each key can map to only one value.

Then we defined the schema for the DataFrame. Again, the schema is a dictionary, where each key-value pair corresponds to the schema of the series. In the schema, every key represents the label of the series (to map the schema to the correct series) and its value represents the schema.

In the output, we can see that we got a nice table representing our data. The labels are neatly separated from the data and below them, their schema is also represented.

What is a Schema?

A schema refers to the definition of the datatype of the series. We fix a particular datatype to the homogenous series to avoid getting in mixed-data.

For example, in the above code, we set the datatype of the column Number to Unsigned Integer - 32 bit (pl.UInt32) as we don’t want to put negative integers in our NumPy logarithm function.

Now, if we want to hide the datatype (that’s written below each label), we can use the following function:

pl.Config.set_tbl_hide_column_data_types(active=True)

The Head, Tail, and Glimpse Functions

The head(), tail() and glimpse() functions are used to have a quick look at the data by reviewing certain records (rows). These are useful especially for large datasets for taking a look at the data, for example to see which columns are present, what type of data is present in each column, and so on.

The head() function prints the given number of rows (passed as the argument of the head() function) from the top of the DataFrame. If no argument is passed, it prints the first five rows of the DataFrame.

import polars as pl
import numpy as np

schema = {"Number": pl.UInt32, "Natural Log": None, "Log Base 10": None}

df = pl.DataFrame(
    {
        "Number" : np.arange(1, 11),
        "Natural Log" : [np.log(x) for x in range(1,11)],
        'Log Base 10' : [np.log10(x) for x in range(1,11)]
        },
    schema=schema
    )
pl.Config.set_tbl_hide_column_data_types(active=True)
print(df.head(3))

Output:

shape: (3, 3)
┌────────┬─────────────┬─────────────┐
│ Number ┆ Natural Log ┆ Log Base 10 │
╞════════╪═════════════╪═════════════╡
│ 1      ┆ 0.0         ┆ 0.0         │
│ 2      ┆ 0.693147    ┆ 0.30103     │
│ 3      ┆ 1.098612    ┆ 0.477121    │
└────────┴─────────────┴─────────────┘

In this example, we have the used the same DataFrame that we just created. Then we used the head() function to output the first three rows of the DataFrame. Also, you may now notice that the schema representation under column names has disappeared. This is because we used pl.Config.set_tbl_hide_column_data_types(active=True).

The glimpse() function presents the data briefly and in a horizontal manner (rows are represented as columns and columns are represented as rows) for better readability.

import polars as pl
import numpy as np

schema = {"Number": pl.UInt32, "Natural Log": None, "Log Base 10": None}

df = pl.DataFrame(
    {
        "Number" : np.arange(1, 11),
        "Natural Log" : [np.log(x) for x in range(1,11)],
        'Log Base 10' : [np.log10(x) for x in range(1,11)]
        },
    schema=schema
    )
pl.Config.set_tbl_hide_column_data_types(active=True)
print(df.glimpse())

Output:

Rows: 10
Columns: 3
$ Number      <u32> 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
$ Natural Log <f64> 0.0, 0.6931471805599453, 1.0986122886681098, 1.3862943611198906, 1.6094379124341003, 1.791759469228055, 1.9459101490553132, 2.0794415416798357, 2.1972245773362196, 2.302585092994046
$ Log Base 10 <f64> 0.0, 0.3010299956639812, 0.47712125471966244, 0.6020599913279624, 0.6989700043360189, 0.7781512503836436, 0.8450980400142568, 0.9030899869919435, 0.9542425094393249, 1.0

None

Here, we used the glimpse() function on our previously created DataFrame df. We can see the output as our transposed DataFrame. Also, None is returned. This is because, by default, glimpse() sets its return_as_string parameter to None. To change it to string, we can set the return_as_string parameter to True. The following example shows how to do it:

import polars as pl
import numpy as np

schema = {"Number": pl.UInt32, "Natural Log": None, "Log Base 10": None}

df = pl.DataFrame(
    {
        "Number" : np.arange(1, 11),
        "Natural Log" : [np.log(x) for x in range(1,11)],
        'Log Base 10' : [np.log10(x) for x in range(1,11)]
        },
    schema=schema
    )
pl.Config.set_tbl_hide_column_data_types(active=True)
print(f'Returned as String: \n{df.glimpse(return_as_string=True)}')

Output:

Returned as String: 
Rows: 10
Columns: 3
$ Number      <u32> 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
$ Natural Log <f64> 0.0, 0.6931471805599453, 1.0986122886681098, 1.3862943611198906, 1.6094379124341003, 1.791759469228055, 1.9459101490553132, 2.0794415416798357, 2.1972245773362196, 2.302585092994046
$ Log Base 10 <f64> 0.0, 0.3010299956639812, 0.47712125471966244, 0.6020599913279624, 0.6989700043360189, 0.7781512503836436, 0.8450980400142568, 0.9030899869919435, 0.9542425094393249, 1.0

In the above code, we can see that the DataFrame is returned as a string and None is not returned.

Finally, the tail() function outputs the given number of rows (passed as the argument of the tail() function) from the bottom of the dataset. When no argument is passed, it outputs the last 5 rows by default.

This is useful for checking if our data was completely loaded. Checking the first few records using the head() function and the last few records with the tail() function ensures that the data is correctly and totally loaded.

Also, we can check if there are any empty records at the end of the dataset. Having empty records at the end of the dataset can be fatal in some cases. For example, if you have to train an ML model on a dataset and you split the dataset statically into testing and training datasets, the empty rows at the end are going to cause an issue. So, checking our data beforehand is a best practice, and these functions help us do it.

import polars as pl
import numpy as np

schema = {"Number": pl.UInt32, "Natural Log": None, "Log Base 10": None}

df = pl.DataFrame(
    {
        "Number" : np.arange(1, 11),
        "Natural Log" : [np.log(x) for x in range(1,11)],
        'Log Base 10' : [np.log10(x) for x in range(1,11)]
        },
    schema=schema
    )
pl.Config.set_tbl_hide_column_data_types(active=True)
print(df.tail(3))

Output:

shape: (3, 3)
┌────────┬─────────────┬─────────────┐
│ Number ┆ Natural Log ┆ Log Base 10 │
╞════════╪═════════════╪═════════════╡
│ 8      ┆ 2.079442    ┆ 0.90309     │
│ 9      ┆ 2.197225    ┆ 0.954243    │
│ 10     ┆ 2.302585    ┆ 1.0         │
└────────┴─────────────┴─────────────┘

In the above code, we used the tail() function on the dataset (that we created earlier) and passed ‘3’ as our argument. Thus our program returned the last three rows of the dataset.

The Sample Function

The sample() function returns a given number of random rows in random order based on their occurrence in the DataFrame. This helps to avoid biased sampling of data.

import polars as pl
import numpy as np

schema = {"Number": pl.UInt32, "Natural Log": None, "Log Base 10": None}

df = pl.DataFrame(
    {
        "Number" : np.arange(1, 11),
        "Natural Log" : [np.log(x) for x in range(1,11)],
        'Log Base 10' : [np.log10(x) for x in range(1,11)]
        },
    schema=schema
    )
pl.Config.set_tbl_hide_column_data_types(active=True)
print(df.sample(3))

Output:

shape: (3, 3)
┌────────┬─────────────┬─────────────┐
│ Number ┆ Natural Log ┆ Log Base 10 │
╞════════╪═════════════╪═════════════╡
│ 6      ┆ 1.791759    ┆ 0.778151    │
│ 5      ┆ 1.609438    ┆ 0.69897     │
│ 10     ┆ 2.302585    ┆ 1.0         │
└────────┴─────────────┴─────────────┘

We can see in the output that we got random rows of the data in a random order of their occurrence in the dataset (row 5 comes before row 6 in the DataFrame, yet by sampling we got row 5 after row 6.) Sampling is a good practice as it helps avoid overfitting in ML in some cases and gives us a general idea about the entire dataset.

Concatenating Two DataFrames

In a nutshell, ‘concatenating’ simply means ‘linking’. Adding or linking one dataset to another – basically, stacking one on top of another – is concatenating the two datasets.

For example, in the previous DataFrame, we had numbers from 1 to 10 and their logarithms. Now, if we want to make it 1 to 20, we have to concatenate a different dataset containing numbers 11 to 20 to the former dataset.

The following code shows how this works:

import polars as pl
import numpy as np

schema = {"Number": pl.UInt32, "Natural Log": None, "Log Base 10": None}

df = pl.DataFrame(
    {
        "Number" : np.arange(1, 11),
        "Natural Log" : [np.log(x) for x in range(1,11)],
        'Log Base 10' : [np.log10(x) for x in range(1,11)]
        },
    schema=schema
    )
pl.Config.set_tbl_hide_column_data_types(active=True)

# new dataset created for concatenation
df1 = pl.DataFrame({
    "Number" : [x for x in range(11, 21)],
    "Log Base 10" : [np.log10(x) for x in range(11,21)],
    "Natural Log" : [np.log(x) for x in range(11, 21)]
}, schema=schema)

print(pl.concat([df, df1], how='vertical')) # concatenating the two datasets

Output:

shape: (20, 3)
┌────────┬─────────────┬─────────────┐
│ Number ┆ Natural Log ┆ Log Base 10 │
╞════════╪═════════════╪═════════════╡
│ 1      ┆ 0.0         ┆ 0.0         │
│ 2      ┆ 0.693147    ┆ 0.30103     │
│ 3      ┆ 1.098612    ┆ 0.477121    │
│ 4      ┆ 1.386294    ┆ 0.60206     │
│ 5      ┆ 1.609438    ┆ 0.69897     │
│ …      ┆ …           ┆ …           │
│ 16     ┆ 2.772589    ┆ 1.20412     │
│ 17     ┆ 2.833213    ┆ 1.230449    │
│ 18     ┆ 2.890372    ┆ 1.255273    │
│ 19     ┆ 2.944439    ┆ 1.278754    │
│ 20     ┆ 2.995732    ┆ 1.30103     │
└────────┴─────────────┴─────────────┘

In this code, we first created the DataFrame df. Then we created another DataFrame df1. Next, we used pl.concat() to concatenate the DataFrames.

The first argument that we passed is the list of the DataFrames that are to be linked. The how parameter defines the manner of concatenation. ‘Vertical’ in this context means that we are linking DataFrames vertically (adding more rows).

The important thing to note here is that schema incompatibility may raise an exception. If the DataFrames that are to be concatenated have different schemas, there will be a schema incompatibility problem. So it’s better to keep the schemas of both the datasets (that are to be concatenated) the same.

Here, we introduced a variable named schema containing the schema parameter of the DataFrame and we applied it to both the DataFrames to avoid schema incompatibility.

Also, concatenation occurs in the order of the passed arguments. For example, in the above code, df appears prior to df1, thus in the linked DataFrame, df appears first and then df1. If we had changed the sequence of values, the concatenated DataFrame would start from df1 and then df.

The following code explains that:

import polars as pl
import numpy as np

schema = {"Number": pl.UInt32, "Natural Log": None, "Log Base 10": None}

df = pl.DataFrame(
    {
        "Number" : np.arange(1, 11),
        "Natural Log" : [np.log(x) for x in range(1,11)],
        'Log Base 10' : [np.log10(x) for x in range(1,11)]
        },
    schema=schema
    )
pl.Config.set_tbl_hide_column_data_types(active=True)

# new dataset created for concatenation
df1 = pl.DataFrame({
    "Number" : [x for x in range(11, 21)],
    "Log Base 10" : [np.log10(x) for x in range(11,21)],
    "Natural Log" : [np.log(x) for x in range(11, 21)]
}, schema=schema)

print(pl.concat([df1, df], how='vertical')) # sequence changed from [df,df1] to [df1, df]

Output:

shape: (20, 3)
┌────────┬─────────────┬─────────────┐
│ Number ┆ Natural Log ┆ Log Base 10 │
╞════════╪═════════════╪═════════════╡
│ 11     ┆ 2.397895    ┆ 1.041393    │
│ 12     ┆ 2.484907    ┆ 1.079181    │
│ 13     ┆ 2.564949    ┆ 1.113943    │
│ 14     ┆ 2.639057    ┆ 1.146128    │
│ 15     ┆ 2.70805     ┆ 1.176091    │
│ …      ┆ …           ┆ …           │
│ 6      ┆ 1.791759    ┆ 0.778151    │
│ 7      ┆ 1.94591     ┆ 0.845098    │
│ 8      ┆ 2.079442    ┆ 0.90309     │
│ 9      ┆ 2.197225    ┆ 0.954243    │
│ 10     ┆ 2.302585    ┆ 1.0         │
└────────┴─────────────┴─────────────┘

Here, we can see that the df1 appears first and then df appears (unlike the previous example). Thus, the sequence of the values matters.

How to Join Two DataFrames

Joining datasets and concatenating datasets are two different concepts. While concatenating means ‘linking’ two separate datasets, joining refers to combining datasets based on a shared column (a key).
The computer matches rows from both datasets where the key values are the same.

In the above dataset ‘df’, we’ll add a new column by joining the dataset ‘df’ with another DataFrame.

# new dataframe
new_col = pl.DataFrame({
    "Number" : [x for x in range(1, 11)],
    "Log Base 2" : [np.log2(x) for x in range(1, 11)]
})

new_data = df.join(new_col, on="Number", how="left") # Both have one column same to map values

print(new_data.head())

Output:

shape: (5, 4)
┌────────┬─────────────┬─────────────┬────────────┐
│ Number ┆ Natural Log ┆ Log Base 10 ┆ Log Base 2 │
╞════════╪═════════════╪═════════════╪════════════╡
│ 1      ┆ 0.0         ┆ 0.0         ┆ 0.0        │
│ 2      ┆ 0.693147    ┆ 0.30103     ┆ 1.0        │
│ 3      ┆ 1.098612    ┆ 0.477121    ┆ 1.584963   │
│ 4      ┆ 1.386294    ┆ 0.60206     ┆ 2.0        │
│ 5      ┆ 1.609438    ┆ 0.69897     ┆ 2.321928   │
└────────┴─────────────┴─────────────┴────────────┘

In this example, we used the join function on df and passed new_col as its argument. This is why the columns of the df function occur prior to the column of the new_col dataset. The parameter on should be given a column name on the basis of which the two datasets are to be joined.

Here, we first mapped the elements of the column Number and its corresponding rows and joined the DataFrames accordingly.

If we used the join() function on the new_col DataFrame, the columns of df would appear later than the column in new_col. The following code will make it clear:

# new dataframe
new_col = pl.DataFrame({
    "Number" : [x for x in range(1, 11)],
    "Log Base 2" : [np.log2(x) for x in range(1, 11)]
})

new_data = new_col.join(df, on="Number", how="left") # passed df as argument

print(new_data.head())

Output:

shape: (5, 4)
┌────────┬────────────┬─────────────┬─────────────┐
│ Number ┆ Log Base 2 ┆ Natural Log ┆ Log Base 10 │
╞════════╪════════════╪═════════════╪═════════════╡
│ 1      ┆ 0.0        ┆ 0.0         ┆ 0.0         │
│ 2      ┆ 1.0        ┆ 0.693147    ┆ 0.30103     │
│ 3      ┆ 1.584963   ┆ 1.098612    ┆ 0.477121    │
│ 4      ┆ 2.0        ┆ 1.386294    ┆ 0.60206     │
│ 5      ┆ 2.321928   ┆ 1.609438    ┆ 0.69897     │
└────────┴────────────┴─────────────┴─────────────┘

You can notice that the column ‘Log Base 2’ appears prior to other columns (unlike in the previous example). Thus this change is significant.

How to Use the with_columns() Function

The with_columns() function enables us to make changes to the column and print it as a new column with existing columns from the original dataset. This is similar to the join() function.

The following example will make it clear:

import polars as pl
import numpy as np

df = pl.DataFrame(
    {
        "Number" : np.arange(1, 11),
        "Natural Log" : [np.log(x) for x in range(1,11)],
        'Log Base 10' : [np.log10(x) for x in range(1,11)]
        },
    schema=schema
    )
new_data = df.with_columns((np.log2(pl.col("Number"))).alias("Log Base 2"))

print(new_data.head())

Output:

shape: (5, 4)
┌────────┬─────────────┬─────────────┬────────────┐
│ Number ┆ Natural Log ┆ Log Base 10 ┆ Log Base 2 │
╞════════╪═════════════╪═════════════╪════════════╡
│ 1      ┆ 0.0         ┆ 0.0         ┆ 0.0        │
│ 2      ┆ 0.693147    ┆ 0.30103     ┆ 1.0        │
│ 3      ┆ 1.098612    ┆ 0.477121    ┆ 1.584963   │
│ 4      ┆ 1.386294    ┆ 0.60206     ┆ 2.0        │
│ 5      ┆ 1.609438    ┆ 0.69897     ┆ 2.321928   │
└────────┴─────────────┴─────────────┴────────────┘

In this example, we have a DataFrame df. To add a column to it , we use the with_columns() function. In this function, we selected column named ‘Number’ using the pl.col() function and put it inside the np.log2() to get the log base 2 value for every record. Finally, to label the new column, we used the alias() function, with the label passed to it as an argument.

Now that we know about the basics of DataFrames, let’s look at how we can work with CSV files.

How to Read CSV Files with Polars

Reading CSV files with Polars is extremely similar to how it works in Pandas. For this tutorial, I’ll be using the Titanic Dataset. Here’s the link to the dataset so you can download it. In this part of the tutorial, we’ll be mainly talking about column selection (useful in feature selection) and filtering the data.

Here’s the syntax for reading a CSV file:

var_name = pl.read_csv(“path_dataset“)

Example code:

import polars as pl

data = pl.read_csv("/titanic_dataset.csv")
print(data.head())

Output:

shape: (5, 12)
┌─────────────┬──────────┬────────┬─────────────────────┬───┬─────────┬─────────┬───────┬──────────┐
│ PassengerId ┆ Survived ┆ Pclass ┆ Name                ┆ … ┆ Ticket  ┆ Fare    ┆ Cabin ┆ Embarked │
╞═════════════╪══════════╪════════╪═════════════════════╪═══╪═════════╪═════════╪═══════╪══════════╡
│ 892         ┆ 0        ┆ 3      ┆ Kelly, Mr. James    ┆ … ┆ 330911  ┆ 7.8292  ┆ null  ┆ Q        │
│ 893         ┆ 1        ┆ 3      ┆ Wilkes, Mrs. James  ┆ … ┆ 363272  ┆ 7.0     ┆ null  ┆ S        │
│             ┆          ┆        ┆ (Ellen Need…        ┆   ┆         ┆         ┆       ┆          │
│ 894         ┆ 0        ┆ 2      ┆ Myles, Mr. Thomas   ┆ … ┆ 240276  ┆ 9.6875  ┆ null  ┆ Q        │
│             ┆          ┆        ┆ Francis             ┆   ┆         ┆         ┆       ┆          │
│ 895         ┆ 0        ┆ 3      ┆ Wirz, Mr. Albert    ┆ … ┆ 315154  ┆ 8.6625  ┆ null  ┆ S        │
│ 896         ┆ 1        ┆ 3      ┆ Hirvonen, Mrs.      ┆ … ┆ 3101298 ┆ 12.2875 ┆ null  ┆ S        │
│             ┆          ┆        ┆ Alexander (Helg…    ┆   ┆         ┆         ┆       ┆          │
└─────────────┴──────────┴────────┴─────────────────────┴───┴─────────┴─────────┴───────┴──────────┘

We can get the statistical analysis of the data by using the describe() function.

print(data.describe())

Output:

shape: (9, 13)
┌────────────┬─────────────┬──────────┬──────────┬───┬─────────────┬───────────┬───────┬──────────┐
│ statistic  ┆ PassengerId ┆ Survived ┆ Pclass   ┆ … ┆ Ticket      ┆ Fare      ┆ Cabin ┆ Embarked │
╞════════════╪═════════════╪══════════╪══════════╪═══╪═════════════╪═══════════╪═══════╪══════════╡
│ count      ┆ 418.0       ┆ 418.0    ┆ 418.0    ┆ … ┆ 418         ┆ 417.0     ┆ 91    ┆ 418      │
│ null_count ┆ 0.0         ┆ 0.0      ┆ 0.0      ┆ … ┆ 0           ┆ 1.0       ┆ 327   ┆ 0        │
│ mean       ┆ 1100.5      ┆ 0.363636 ┆ 2.26555  ┆ … ┆ null        ┆ 35.627188 ┆ null  ┆ null     │
│ std        ┆ 120.810458  ┆ 0.481622 ┆ 0.841838 ┆ … ┆ null        ┆ 55.907576 ┆ null  ┆ null     │
│ min        ┆ 892.0       ┆ 0.0      ┆ 1.0      ┆ … ┆ 110469      ┆ 0.0       ┆ A11   ┆ C        │
│ 25%        ┆ 996.0       ┆ 0.0      ┆ 1.0      ┆ … ┆ null        ┆ 7.8958    ┆ null  ┆ null     │
│ 50%        ┆ 1101.0      ┆ 0.0      ┆ 3.0      ┆ … ┆ null        ┆ 14.4542   ┆ null  ┆ null     │
│ 75%        ┆ 1205.0      ┆ 1.0      ┆ 3.0      ┆ … ┆ null        ┆ 31.5      ┆ null  ┆ null     │
│ max        ┆ 1309.0      ┆ 1.0      ┆ 3.0      ┆ … ┆ W.E.P. 5734 ┆ 512.3292  ┆ G6    ┆ S        │
└────────────┴─────────────┴──────────┴──────────┴───┴─────────────┴───────────┴───────┴──────────┘

How to Select Columns from the Dataset

Now we’re going to learn how to select certain columns from the dataset and transform those columns into a new DataFrame. This can be useful if we want to train an ML model based on only certain columns and not the entire dataset (that is, using feature selection).

Let’s first look at the code below:

new_df = data.select(
    pl.col("Survived"),
    pl.col("Name"),
    pl.col("Age"),
    pl.col("Sex")
)

print(new_df.head())

Output:

shape: (5, 4)
┌──────────┬─────────────────────────────────┬──────┬────────┐
│ Survived ┆ Name                            ┆ Age  ┆ Sex    │
╞══════════╪═════════════════════════════════╪══════╪════════╡
│ 0        ┆ Kelly, Mr. James                ┆ 34.5 ┆ male   │
│ 1        ┆ Wilkes, Mrs. James (Ellen Need… ┆ 47.0 ┆ female │
│ 0        ┆ Myles, Mr. Thomas Francis       ┆ 62.0 ┆ male   │
│ 0        ┆ Wirz, Mr. Albert                ┆ 27.0 ┆ male   │
│ 1        ┆ Hirvonen, Mrs. Alexander (Helg… ┆ 22.0 ┆ female │
└──────────┴─────────────────────────────────┴──────┴────────┘

In the code above, we selected four columns using the select() and pl.col() functions from the Titanic Dataset and transformed them into a new DataFrame called new_df.

Now, we can filter this data however we want. Let’s make a new DataFrame by filtering out only surviving passengers from the dataset:

survived_data = data.select(
    pl.col("Survived"),
    pl.col("Name"),
    pl.col("Age"),
    pl.col("Sex")
).filter(pl.col("Survived")==1)

print(survived_data.head())

Output:

shape: (5, 4)
┌──────────┬─────────────────────────────────┬──────┬────────┐
│ Survived ┆ Name                            ┆ Age  ┆ Sex    │
╞══════════╪═════════════════════════════════╪══════╪════════╡
│ 1        ┆ Wilkes, Mrs. James (Ellen Need… ┆ 47.0 ┆ female │
│ 1        ┆ Hirvonen, Mrs. Alexander (Helg… ┆ 22.0 ┆ female │
│ 1        ┆ Connolly, Miss. Kate            ┆ 30.0 ┆ female │
│ 1        ┆ Abrahim, Mrs. Joseph (Sophie H… ┆ 18.0 ┆ female │
│ 1        ┆ Snyder, Mrs. John Pillsbury (N… ┆ 23.0 ┆ female │
└──────────┴─────────────────────────────────┴──────┴────────┘

In the above code, we used the filter() function. This function helps us gather data that applies to our given condition. In the above example, we added the condition that, “Every element in the column named ‘Survived’ should be equal to 1”. Hence, we got our required data.

Some Other Important Functions

How to Print the Names of the Columns of a Dataset

You can print the names of a column using the columns method. The following code shows how to use the columns method:

print(data.columns) # data --> Titanic Dataset

Output:

['PassengerId', 'Survived', 'Pclass', 'Name', 'Sex', 'Age', 'SibSp', 'Parch', 'Ticket', 'Fare', 'Cabin', 'Embarked']

How to Index a Dataset

Indexing a dataset means adding an index column to the existing dataset. It can prove useful in keeping track of the rows of the dataset.

We can index the dataset using the with_row_index() function. Inside this function, we can pass the argument to name this new index column. If we don’t pass any argument, the index column name is set as ‘index’ by default.

data = pl.read_csv("/titanic_dataset.csv").with_row_index('#') # naming the index column as '#'
print(data.head())

Output:

shape: (5, 13)
┌─────┬─────────────┬──────────┬────────┬───┬─────────┬─────────┬───────┬──────────┐
│ #   ┆ PassengerId ┆ Survived ┆ Pclass ┆ … ┆ Ticket  ┆ Fare    ┆ Cabin ┆ Embarked │
│ --- ┆ ---         ┆ ---      ┆ ---    ┆   ┆ ---     ┆ ---     ┆ ---   ┆ ---      │
│ u32 ┆ i64         ┆ i64      ┆ i64    ┆   ┆ str     ┆ f64     ┆ str   ┆ str      │
╞═════╪═════════════╪══════════╪════════╪═══╪═════════╪═════════╪═══════╪══════════╡
│ 0   ┆ 892         ┆ 0        ┆ 3      ┆ … ┆ 330911  ┆ 7.8292  ┆ null  ┆ Q        │
│ 1   ┆ 893         ┆ 1        ┆ 3      ┆ … ┆ 363272  ┆ 7.0     ┆ null  ┆ S        │
│ 2   ┆ 894         ┆ 0        ┆ 2      ┆ … ┆ 240276  ┆ 9.6875  ┆ null  ┆ Q        │
│ 3   ┆ 895         ┆ 0        ┆ 3      ┆ … ┆ 315154  ┆ 8.6625  ┆ null  ┆ S        │
│ 4   ┆ 896         ┆ 1        ┆ 3      ┆ … ┆ 3101298 ┆ 12.2875 ┆ null  ┆ S        │
└─────┴─────────────┴──────────┴────────┴───┴─────────┴─────────┴───────┴──────────┘

How to Rename Columns in the Dataset

Lastly, to rename columns in the Dataset, we use the rename() function.

data = pl.read_csv("/titanic_dataset.csv").with_row_index('#').rename({'PassengerId':'renamed_col'})
print(data.head())

Output:

shape: (5, 13)
┌─────┬─────────────┬──────────┬────────┬───┬─────────┬─────────┬───────┬──────────┐
│ #   ┆ renamed_col ┆ Survived ┆ Pclass ┆ … ┆ Ticket  ┆ Fare    ┆ Cabin ┆ Embarked │
│ --- ┆ ---         ┆ ---      ┆ ---    ┆   ┆ ---     ┆ ---     ┆ ---   ┆ ---      │
│ u32 ┆ i64         ┆ i64      ┆ i64    ┆   ┆ str     ┆ f64     ┆ str   ┆ str      │
╞═════╪═════════════╪══════════╪════════╪═══╪═════════╪═════════╪═══════╪══════════╡
│ 0   ┆ 892         ┆ 0        ┆ 3      ┆ … ┆ 330911  ┆ 7.8292  ┆ null  ┆ Q        │
│ 1   ┆ 893         ┆ 1        ┆ 3      ┆ … ┆ 363272  ┆ 7.0     ┆ null  ┆ S        │
│ 2   ┆ 894         ┆ 0        ┆ 2      ┆ … ┆ 240276  ┆ 9.6875  ┆ null  ┆ Q        │
│ 3   ┆ 895         ┆ 0        ┆ 3      ┆ … ┆ 315154  ┆ 8.6625  ┆ null  ┆ S        │
│ 4   ┆ 896         ┆ 1        ┆ 3      ┆ … ┆ 3101298 ┆ 12.2875 ┆ null  ┆ S        │
└─────┴─────────────┴──────────┴────────┴───┴─────────┴─────────┴───────┴──────────┘

In the above example, we renamed the column named ‘PassengerId’ to ‘renamed_col’.

Summary

Now you know how to work with the Polars Python library to analyze your data more effectively.

In this article, you learned:

• What Polars is and how to install it

• How to define series and DataFrames in Polars

• Different functions to deal with DataFrames.

• How to read and work with CSV files in Polars

Thanks for Reading, and happy data wrangling!

Bragging on social media about a clever script is one thing, but pushing a vibe coded app to prod comes with many security risks.

With so many AI dev tools out there now, code reviews become more critical than ever.

This article will explore what vibe coding means and how code reviews should adapt in the era of AI.

Table of Contents:

1. What is Vibe Coding?

2. How to Implement Vibe Coding in Practice

3. Why isn’t Vibe Coded Output Production Ready?

   • Context gaps are the first crack.

   • Those gaps lead directly to integration blind spots.

   • The most serious risk is security by omission.

   • Testing and correctness evidence are thin.

   • Operability lags behind.

4. Guidelines for AI Code Reviews

   • Code Review Process in Vibe Coding

5. Checklist for Reviewing AI Generated Code

6. How to Work Effectively with AI Tools

7. Conclusion

What is Vibe Coding?

In early 2025, AI researcher Andrej Karpathy popularized the term vibe coding to describe a new way of development in which you “fully give in to the vibes” and let AI write code while you focus on high level intent.

A developer expresses their desired functionality in plain language, and an AI system (like an LLM) generates the source code to implement it.

This code-by-prompt approach allows even beginners to produce working code without deep knowledge of programming languages. Karpathy joked that with advanced IDE agents (like Cursor’s Composer mode), “I barely even touch the keyboard... I ‘Accept All’ always, I don’t read the diffs anymore... and it mostly works”.

So, vibe coding is coding by vibe and trusting AI to handle the heavy lifting.

How to Implement Vibe Coding in Practice

In practice, vibe coding usually involves using AI assistants and adapting your workflow to a more interactive, prompt-driven style.

Here’s an overview of how you can “vibe code” a project:

Step 1: Choose an AI assistant

Select a development env that supports AI code generation. Popular choices include Cursor and GitHub Copilot.

Step 2: Define your requirements

Instead of writing boilerplate code, describe what you want to build. Provide AI with a specific prompt detailing functionality. The more context and detail you give, the better AI can fulfill your intent.

For example, when I ran an SEO inspection for my website, DevTools Academy, I used this prompt in Cursor:

“Now, act as a senior product engineer and UX strategist. Evaluate and improve https://www.devtoolsacademy.com with a practical, no-fluff lens.

Scope:

• UX

• SEO and technical SEO

• Positioning and messaging

• Copywriting and information architecture

• What to add to stand out in the developer tools space.”

This prompt works well because it gives the AI a clear role, a defined scope, and a specific intent. AI knows it’s not just fixing SEO but also reviewing how the site communicates value to devs. That combination of clarity and context produces actionable insights instead of surface-level suggestions.

Below is a screenshot of that audit in progress and showing how I reviewed code, metadata, and UX recommendations side by side.

You can checkout the full code on my open source blog here and check out closed PRs. This will help you learn how I use all these coding agents on a production ready app.

Step 3: Review the code

AI will produce initial code based on your prompt. Think of this as a prototype – it’s not perfect. Run the code and see how it behaves.

Let’s look at an example: here, CodeRabbit is reviewing one of my pull requests on GitHub. I had pushed a small fix to sort blog posts correctly and make sure the RSS feed reflects the latest publish date. Within seconds, CodeRabbit analyzed the diff, understood the intent behind my change, and explained exactly what the new code does.

It pointed out that the fix now sorts posts before mapping them, uses the sorted data for both items and the lastBuildDate, and ensures proper chronological order throughout the feed.

It’s like having a senior reviewer who not only checks syntax but also validates logic and confirms that your reasoning holds up.

This is just a reminder to expect imperfections. Vibe coding embraces a “code first, refine later” mindset. This means you get a working version quickly, then iteratively improve it. You might go through a few cycles of prompt -> code -> test -> tweak.

Step 4: Validate, debug, polish

Once AI generated code meets your expectations, do a final review.

Throughout the process, the core idea is that you collaborate with the AI. The AI agent serves as a coding assistant, making real-time suggestions, automating tedious boilerplate, and even generating entire modules on your behalf.

Why Isn’t Vibe Coded Output Production Ready?

Vibe coding moves fast: you describe intent, the AI produces something that runs, and you’re off to the next prompt. What’s missing is the slow, unglamorous work that usually turns a draft into shippable software, like shared context, architectural alignment, verification, and documentation.

AI generates plausible code based on patterns it has seen. But it doesn’t understand your team’s history, your system’s constraints, or the implicit rules that keep everything coherent over time.

That mismatch shows up the moment a “works on my machine” demo meets a real codebase.

Let’s explore the common pitfalls of vibe-coded code, so you’ll know what to watch for. Then, in the checklist section below, I’ll outline practical strategies to address or prevent each issue.

Context gaps are the first crack.

AI only sees what you show it, so it’s easy for it to make the right local choice and the wrong global one: duplicating logic that already exists, choosing defaults that conflict with prior decisions, or introducing functions that don’t respect domain boundaries.

The result is code that looks reasonable in isolation but collides with existing assumptions and conventions once integrated.

Those gaps lead directly to integration blind spots.

Drafts often ignore the lived details of your environment – shared utilities, cross-cutting concerns, configuration, deployment hooks, and operational policies. Interfaces may line up at a glance and still fail at runtime because the draft doesn’t fit how your system composes modules, handles errors, or manages state across services.

The most serious risk is security by omission.

AI rarely includes robust input validation, clear authentication and authorization paths, or rate limiting unless you spell it out. Secrets handling and logging tend to be superficial or missing. That leaves common exposure points like request handlers, job processors, and webhook endpoints without the checks that prevent injection, SSRF, mass assignment, or data exfiltration.

Even when the surface looks tidy, the absence of explicit security controls means you’re trusting defaults you didn’t choose.

Testing and correctness evidence are thin.

Quality suffers in quieter ways, too. Beyond “it runs,” there’s little to demonstrate behavior across edge cases or to guard against regressions.

Performance and scalability remain unknowns: extra network calls, N+1 patterns, and quadratic loops sneak in because nobody measured them. Dependencies and environments drift as versions aren’t pinned, infrastructure isn’t declared, and configuration lives only in the author’s head, making behavior differ across machines and CI.

Operability lags behind.

A lack of metrics, missing health/readiness probes, and no runbook make failures harder to detect and slower to recover from. Add in data quality and compliance concerns (PII handling, encoding assumptions, transitive license obligations), and you have code that demos well but isn’t ready for production’s reliability, security, and audit demands.

In short, vibe-coded output accelerates drafting but skips the shared understanding and evidence that make software safe to ship.

Until those gaps are closed, it’s a prototype, not a release.

Guidelines for AI Code Reviews

Your team should keep pre-AI engineering standards as the bar, including security, tests, readability, maintainability, performance, and docs. AI should change how fast you gather the evidence for those standards, not how much evidence you require. In other words, use AI to accelerate the path to your existing bar, never to lower it.

Using AI, you can generate code at speed. But if reviews take the same amount of time (or more time), you lose some of the benefit. The goal isn’t to relax standards, it’s to shorten the time to prove you met them. That means layering in automation (tests, static analysis, secret scans, SCA) and AI-assisted review to catch obvious issues quickly so human reviewers can focus on intent, architecture, and risk.

Well-used assistants can help here. For example, tools like CodeRabbit, GitHub Copilot PR Reviewer, Claude Code, Cursor’s Bugbot, Graphite’s AI Review, and Greptile can highlight potential bugs, security gaps, style deviations, and mismatched intent, and summarize diffs for faster context. Treat these as accelerators for your existing process, not as replacements for judgment.

Code Review Process in Vibe Coding

The fundamentals of good code reviews haven’t changed – and in fact, they’re more critical now.

Below are some key principles to maintain speed without sacrificing quality.

1. Trust, but verify.

A reviewer usually assumes the author understands the system. With vibe-coded output, the “author” may be an AI with limited context. If something looks odd or unnecessary, question it. Run the code, add/execute tests, or ask the developer/AI for clarification on intent and constraints.

2. Don’t let reviews become a bottleneck.

Vibe coding generates code quickly. If human review takes as long as hand-writing the change, you’ve erased the gain.

Combat this by front-loading automation: run unit/integration tests, static analysis (lint/SAST), secret scans, SCA, and basic perf checks in CI to clear the noise. Then reviewers spend their time on design trade-offs, boundary cases, and risk. The balance is: high standards, faster evidence.

3. Use AI code reviews wisely

AI can help review code just as it helps generate it. Modern “pair reviewer” tools scan a PR and surface likely bugs, security issues, missing tests, or style violations in minutes plus give natural-language summaries of the change.

Tools you can consider include CodeRabbit, GitHub Copilot PR Reviewer, Claude Code, Cursor Bugbot, Graphite, and Greptile. Many integrate with the CLI/IDE and GitHub/GitLab to leave actionable comments.

Think of them as fast first-pass reviewers that increase coverage and consistency across PRs.

4. Human judgment is still irreplaceable.

Even the best AI reviewer is an assistant. Keep humans accountable for correctness, security posture, architectural fit, and user impact. A healthy pattern is AI first-pass > human second-pass that inspects invariants, failure modes, and long-term maintainability.

5. Maintain a high bar for quality.

It’s tempting to accept “it runs” when an AI wrote it. Don’t. Stakeholders still expect software to be robust, secure, and maintainable. Keep DRY, readability, and testability standards. Insist on input validation, authZ checks where relevant, and sensible logging/metrics. If you can’t provide evidence that you met the bar, you haven’t met it.

6. Educate and document

When reviewers find bugs or security flaws in AI-generated code, capture the lesson.

Update internal guides with patterns like “When generating handlers, validate and bound inputs, add rate limits, log request IDs, avoid N+1 queries, and sanitize user-visible output.” Over time, bake these into prompts, templates, repo scaffolds, and CI checks so the next AI draft starts closer to done.

Checklist for Reviewing AI Generated Code

Before approving any vibe-coded change, make the standards explicit and verifiable. Use this checklist to confirm behavior, security, performance, integration, and documentation so the draft you got from AI becomes code you can safely ship.

Here’s a checklist a human reviewer should go through before approving vibe-coded output:

1. Define the code’s purpose (scope & non-goals).

Be explicit about what this change does and does not do. Tie it to a user story/ticket and call out non-goals so “helpful” AI changes don’t creep in.

2. Verify X and Y (behavior and edge cases).

Be clear about what you’re verifying. For example, verify input parsing and pagination boundaries, verify that error paths return the correct status and body, and verify that database writes are idempotent. Run existing tests, add missing unit/integration tests, and reproduce edge inputs (empty, null, huge, unicode).

3. Perform code-quality checks (readability, DRY, refactor needs).

AI often produces verbose or duplicated logic. Ensure names are meaningful, side effects are clearly stated, and duplication is removed or minimized. Run linters/formatters, collapse repetition, and extract helpers where they aid clarity.

4. Analyze organization and structure (make sure it fits the architecture).

AI writes code in isolation. Confirm the change uses existing utilities, layers, and boundaries (domain/services/controllers/jobs). Check imports and module placement, avoid reinventing existing helpers, and align with repository conventions.

5. Validate inputs and assumptions (make the implicit explicit).

List the assumptions the AI made (default locale/timezone, allowed ranges, required fields). Add schema validation (DTO/class validators/JSON Schema). Empty, null, over-max, non-ASCII, unexpected enum, malicious strings. And finally, enforce limits/timeouts.

6. Perform security audits (minimum pass).

• AuthN/AuthZ: Confirm endpoint checks identity and authorization paths; deny-by-default.

• Inputs: Sanitize/validate inputs, prevent injection (SQL/NoSQL/command), and escape user-visible output.

• Secrets: No secrets in code/diff/logs, use env/secret manager, and rotate any test keys.

• Abuse controls: Add rate limits, size limits, and timeouts on network and disk operations. Run SAST/secret scan/SCA, and fix or justify findings.

7. Do a performance evaluation (right now, at a small scale).

Look for N+1s, needless network calls, unbounded loops, quadratic sorts. Add a micro-benchmark or run a quick load test for hot paths. Set sensible cache/timeout/retry with jitter where applicable.

8. Manage dependencies (pin, justify, minimize).

Review any new libraries. Are they necessary? Maintained? License compatible? Pin versions, add lockfiles, or remove unused transitive adds.

9. Review documentation (what to add and where).

Ensure the docs are in line with the code. AI often changes some parts or adds code blocks at different places while resolving various issues. These changes might not make it into the docs.

10. Observability (see problems early).

Use structured logs with request/trace IDs, key counters/timers (success/error/latency), health/readiness probes, and a basic dashboard or alert stub.

11. Compliance and data handling (when applicable).

Identify any personally identifiable information (PII), document collection/retention, ensure masking/redaction in logs, verify dependency licenses and data-residency constraints.

How to Work Effectively with AI Tools

At this point, you can probably see why it’s very important to understand the actual skills involved in AI-assisted development.

There’s a pretty big difference between an experienced developer who uses AI tools to help them get more done, and a newbie who thinks AI can build the next Facebook or Google just with a simple prompt.

An inexperienced dev will ask AI something like "Hey, Build me Twitter and make no mistakes"

But an experienced developer who has a solid fundamentals might say say something like:

• "AI, we're building a Twitter replica. Use $SQL_Database, Use $Language, Avoid $Common_Pitfalls, Follow $Standard_Practices."

• "The generated code is prone to X problem, implement this fix."

• "Implementation of $X is flawed because of $Y, do $Z instead."

So as you can see, you still need to know the how's and the why's and what depends on what. Often you’ll just need to make the changes manually, because it will be faster. And you don’t want to outsource the critical thinking part, which is the part that AI can't actually do.

LLMs are good at information retrieval. If you know nothing about what you’re looking for, then asking an AI isn’t going to be that helpful (or that reliable). But if you have an idea, some background knowledge/context, and the skills to verify AI’s responses, then it can be really helpful.

Last month, I shared in my newsletter how my current coding loop looks in practice.

I draft with Claude Code (or Copilot/Cursor), open a PR, and let an AI reviewer like CodeRabbit (or Copilot PR Reviewer / Cursor Bugbot or Greptile) do the first pass. CI runs tests and scans.

I repeat until everything’s green and the PR is ready to merge. It’s fast, but it’s still disciplined.

If you want to understand why this kind of workflow is becoming essential, read this article: Era of AI Slop Cleanup Has Begun. I talk about what’s happening in AI-assisted engineering, where generating code is easy, but keeping it clean and production ready takes experience – and you must have good programming skills.

Conclusion

AI-generated code can boost productivity – but production value still comes from software that is robust, secure, and maintainable.

Mindless code generation creates technical debt. But when you integrate AI thoughtfully, with guardrails, verification, tests, security checks, and documentation, you can go faster without lowering your standards.

That's it for this article. I hope you learned something new today.

If you have any questions about code reviews, engineering, startups, or business in general, please find me on Twitter: @TheAnkurTyagi. I’d be more than happy to discuss them.

Want to read more interesting articles like this?

You can read more about the latest dev tools like this one on my website.

But learning React can feel overwhelming. With so many new terms, patterns, and frameworks like Next.js in the mix, it’s easy to feel lost.

That’s why this handbook focuses on React itself without unnecessary distractions. Once you’ve mastered React at its core, you’ll have the confidence to use it with or without frameworks to build anything you can imagine.

Table of Contents

1. What You Should Already Know

2. What Exactly Is React?

   • Why the “React” name?

   • Is React a framework?

   • Is React only for web development?

   • What’s the primary goal of React?

3. How to Add a React Component to a Website

   • Create a new project directory

   • Create a DOM container

   • Import React, Babel, and your component

   • Create your component

   • Configure a local server

4. What Is JSX?

   • Can React work without JSX?

   • Example 1: Create a React element with JSX

   • Example 2: Create a React element with regular JavaScript

5. What Is React.createElement()?

6. How to Use JSX

   • Use JSX like any JavaScript expression

   • Wrap multi-line JSX in parentheses

   • Wrap expressions in curly braces

   • Use camelCase to name attributes

   • Close empty JSX tags properly

   • A React component can return only a single element

7. Time to Practice with JSX 🤸‍♂️🏋️‍♀️🏊‍♀️

   • The solution

8. What Is a React Component?

   • Syntax of a React component

   • Example of a React component

   • React components best practices

9. How to Render Lists of Elements from an Array

   • Each React element in an array needs a unique key

   • How to add unique keys to each React element in an array

   • Essential things to know about assigning keys

10. How to Handle Events in React

    • Types of event handlers

    • Example: Inline event handler

    • Example: Referenced event handler

11. What Is React State?

    • Syntax of React state

    • Example of React state

    • React trigger vs render vs commit vs paint

    • What does it mean to trigger a render in React?

    • What does it mean to render React components?

    • What does it mean to commit a React UI to the browser’s DOM?

    • What does it mean to paint the DOM nodes on the screen?

12. What Is the React Ref Hook?

    • Syntax of the React ref Hook

    • Example of the React ref Hook

    • React ref Hook best practices

13. Variables vs Refs vs States in React

    • How do variables work in React?

    • How do refs work in React?

    • How do states work in React?

    • Tips on using variables, refs, and states in React

14. What Is the useEffect Hook?

    • Syntax of the useEffect Hook

    • Example of the useEffect Hook

    • useEffect Hook’s best practices

15. How to Style React Components

    • How to use CSS style sheets to style React elements

    • How to use the inline style attribute to style React elements

    • How to use CSS Modules to style React elements

    • How to use a CSS-in-JS library to style React elements

16. Overview

    • Dive deeper into React

What You Should Already Know

You will get the most value out of this handbook if you are familiar with:

• JavaScript fundamentals (variables, functions, arrays, objects)

• Basic CSS for styling

• HTML basics for structure

If you’ve ever written a small JavaScript file or built a simple “Hello World” website, you are all set!

Let’s get started with the basics.

What Exactly Is React?

React is a component-based JavaScript library for efficiently building user interfaces (UI).

No matter how massive or miniature your project may be, React is well-suited to help you develop any web application efficiently.

Developers primarily use React to build independent, reusable components that can be combined with other isolated user interfaces to create highly scalable applications. For instance, the image below illustrates the individual components of YouTube’s video player page.

In other words, React helps you build complex UIs from small, isolated components that can easily be reused in multiple applications. Each independent component tells React the exact element you want to display on screen.

The image above illustrates React as a highly adaptable library that uses JavaScript functions to build user interfaces for both mobile and web-based applications. Let’s discuss the points highlighted in the image.

Why the “React” name?

The name stems from the idea that React renders your UI and reacts to events in the user interface it has rendered on screen.

Is React a framework?

No, React is a library—not a framework. React serves only as an add-on feature to your application. It’s not designed to be used as an app’s primary support system.

Is React only for web development?

No, you don’t just use React on the web. For instance, ReactDOM helps build web applications, and React Native helps build mobile applications.

Can React be used for full-stack applications?

Absolutely. React is super flexible. You can use it in simple HTML projects, integrate it into existing code, or build complex full-stack applications. Its adaptability makes it suitable for a wide variety of development scenarios.

What’s the primary goal of React?

React’s primary goal is for you to use JavaScript functions to return and manage the UI (HTML element) you want to render (display) on the screen. For instance, consider the following:

function DonationUserInterface() {
  return <button>☕ Buy me a coffee</button>;
}

The JavaScript function above is a React component that returns the UI (HTML button element) we want to display on screen and manage with React. In fact, let’s implement the DonationUserInterface component on a live website using only HTML and JavaScript – no frameworks.

How to Add a React Component to a Website

Follow the steps below to add a donation UI component to a live HTML website.

Create a new project directory

mkdir codesweetly-donation-ui-001

Note: You can use any name you prefer. In this guide, we’ll use codesweetly-donation-ui-001 for demonstration.

Afterward, navigate to your project directory using the command line.

cd path/to/codesweetly-donation-ui-001

Create a DOM container

To add a React component to a webpage, you first need to specify the section of the page where you want to insert the UI. So, create an HTML page:

touch index.html

Afterward, open the new file and add the following code:

<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>CodeSweetly Donation UI</title>
  </head>
  <body>
    <!-- A div container (the DOM node) created for React to manage -->
    <div id="donation-ui"></div>
  </body>
</html>

The snippet above created a DOM node (<div> element), inside which we want React to display and manage a donation user interface. In other words, the <div> represents the website’s section you want React to manage.

Some notes:

• The div’s id attribute is the reference we’ll later use in a JavaScript file to find the container and tell React to insert a donation UI.

• Although most developers use a <div> tag as the DOM container, you can use other HTML elements like the <main> tag.

• You can have multiple DOM containers anywhere inside the <body> element.

• A DOM container is usually left empty, as React will overwrite its content.

Import React, Babel, and your component

Use script tags to load React, Babel, and your component into your project’s HTML page.

<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>CodeSweetly Donation UI</title>
    <!-- Load the React Library -->
    <script src="https://unpkg.com/react@18/umd/react.development.js"></script>
    <!-- Load the ReactDOM API -->
    <script src="https://unpkg.com/react-dom@18/umd/react-dom.development.js"></script>
    <!-- Load the Babel Compiler -->
    <script src="https://unpkg.com/@babel/standalone/babel.min.js"></script>
  </head>
  <body>
    <div id="donation-ui"></div>
    <!-- Load your React component -->
    <script type="text/babel" src="DonationUserInterface.js"></script>
  </body>
</html>

The snippet above uses the first three script tags to load React, ReactDOM, and Babel from unpkg.com.

At the same time, we use the fourth script tag to import our donation component (which we will create in the following section).

Some notes:

• The react package is a library containing React’s core functionality for creating React components.

• The ReactDOM API provides the required methods to use React with the DOM.

• Babel is a compiler that transforms React code into plain JavaScript, as browsers don’t understand React syntax by default.

• The type="text/babel" attribute tells Babel to automatically execute and convert the DonationUserInterface.js script from React code into plain JavaScript.

• The setup above is recommended for learning React only. Don’t use it for public projects (production environment). You can learn how to set up React for production in my Code React Sweetly book.

• The scripts will not work if your internet or unpkg.com’s server is down. So, if nothing renders on-screen, enter each script’s src URL in your browser to confirm if the server responds successfully.

Create your component

Create a DonationUserInterface.js JavaScript file inside the same folder in which your HTML file is located.

touch DonationUserInterface.js

Then, paste the following code inside the JavaScript file you’ve just created:

function DonationUserInterface() {
  const [donate, setDonate] = React.useState(false);

  function createUserInterface() {
    if (donate) {
      return (
        <p>
          <a href="https://www.buymeacoffee.com/codesweetly">Support page</a>.
          Thank you so much! 🎉
        </p>
      );
    }
    return <button onClick={() => setDonate(true)}>☕ Buy me a coffee</button>;
  }
  return createUserInterface();
}

const root = ReactDOM.createRoot(document.getElementById("donation-ui"));
root.render(<DonationUserInterface />);

The snippet above does the following:

1. Defines a component named DonationUserInterface.

2. Initializes the component’s state (built-in object) with the Boolean value false.

3. Programs the component to return a paragraph element if the state’s donate variable is true. Otherwise, it should return a button element.

4. Creates a ReactDOMRoot object instance for the donation-ui HTML element you want React to manage. Afterwards, it assigns the newly created instance to the root variable.

5. Uses the object instance’s render() method to display the DonationUserInterface component inside the root donation-ui.

Configure a local server

HTML files containing ES modules work only through http:// and https:// URLs, not locally via a file:// URL.

Since we previously used the type="text/babel" attribute to convert the DonationUserInterface.js JavaScript file to an ES module, we need a local server, like “Live Server” or “Servor,” to load the HTML document via an http:// scheme. Let’s install Servor so we can use it for this project.

Install the Servor local server

npm install servor@4.0.2 --save-dev

Run your app

After installing Servor, use it to start your app from your terminal:

npx servor --browse --reload

Some notes:

• Close the server using Ctrl + C on Windows or Cmd + C on Mac.

• --browse: Opens the browser once the server starts.

• --reload: Reloads the browser whenever you update the project’s files.

• You can also add the servor command to the "scripts" field of your project’s package.json file:

{
  "scripts": {
    "start": "servor --browse --reload"
  },
  "devDependencies": {
    "servor": "^4.0.2"
  }
}

By doing so, you can run your app from your terminal like this:

npm run start

And that’s it! You’ve successfully added a React component to a live website using a JavaScript function to render a donation UI on screen! 🎉

Are you asking why we’re writing HTML inside JavaScript? Well, that HTML-like code is called JSX. Let’s learn about it.

What Is JSX?

JSX is a JavaScript syntax extension that allows you to build React elements with HTML-like syntax directly inside your JavaScript code.

Tips:

• JSX is sometimes called JavaScript XML or JavaScript Syntax eXtension.

• While JSX looks a lot like HTML, it’s not HTML. Instead, it enables you to use HTML-like syntax along with all the strengths of JavaScript.

Can React work without JSX?

Yes. React can work independently of JSX. But JSX makes it easier to create user interfaces (UI).

In other words, whatever you can do with JSX, you can do the same with plain JavaScript. For instance, consider the two examples below. The first includes JSX syntax, while the second is regular JavaScript syntax.

Example 1: Create a React element with JSX

MyBio.js

function MyBio() {
  return <h1>My name is Oluwatobi.</h1>;
}
const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<MyBio />);

index.html

<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>MyBio App</title>
    <script src="https://unpkg.com/react@18/umd/react.development.js"></script>
    <script src="https://unpkg.com/react-dom@18/umd/react-dom.development.js"></script>
    <script src="https://unpkg.com/@babel/standalone/babel.min.js"></script>
  </head>
  <body>
    <div id="root"></div>
    <script type="text/babel" src="MyBio.js"></script>
  </body>
</html>

In the React snippet above, <h1>My name is Oluwatobi.</h1> and <MyBio /> are JSX.

Tip: React supports the .jsx file extension for files with JSX code. So, if you prefer to differentiate your JSX files from JavaScript, you can rename MyBio.js to MyBio.jsx. Just note that choosing between using .js vs .jsx for files with JSX is entirely up to you. (Your JSX code is simply a syntactic sugar for the React.createElement() JavaScript call.)

Example 2: Create a React element with regular JavaScript

MyBio.js

function MyBio() {
  return React.createElement("h1", null, "My name is Oluwatobi.");
}
const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(React.createElement(MyBio));

index.html

<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>MyBio App</title>
    <script src="https://unpkg.com/react@18/umd/react.development.js"></script>
    <script src="https://unpkg.com/react-dom@18/umd/react-dom.development.js"></script>
    <script src="https://unpkg.com/@babel/standalone/babel.min.js"></script>
  </head>
  <body>
    <div id="root"></div>
    <script type="text/babel" src="MyBio.js"></script>
  </body>
</html>

Everything in the React snippet above is plain JavaScript code.

What Is React.createElement()?

React.createElement() is the JavaScript alternative to JSX. It is a method for creating React elements in regular JavaScript.

Browsers can’t read the JSX syntax. This is why we typically use tools like Babel, TypeScript, and Parcel to compile JSX to a React.createElement(component, props, ...children) JavaScript call.

For instance, <button className="support-btn">Buy me a coffee</button> will transform to React.createElement("button", { className: "support-btn" }, "Buy me a coffee ") at runtime.

Under the hood, the React.createElement() method creates a JavaScript object conventionally called “React element.”

Tip: A React element is a JavaScript object that defines the user interface (UI) you want to render on screen.

A simplified version of a React element looks like this:

const myBioReactElement = {
  type: "h1",
  props: {
    className: null,
    children: "My name is Oluwatobi.",
  },
};

React.createElement() is best for projects that want to avoid compiling tools like Babel. Whereas JSX is a syntactic sugar that makes React code easier to read. So, you are free to choose the syntax that works best for you (but most React projects use JSX for its simplicity).

How to Use JSX

The following tips will help you get up and running with JSX so you can use it in your React projects.

Use JSX like any JavaScript expression

You can use JSX like any other JavaScript expression because, at execution time, JSX transpiles into regular JavaScript.

In other words, you can store JSX expressions in variables, use them in if statements, or make them the return value of functions.

Example:

DisplayMyName.js

const firstName = false;
const myFirstName = <h1>My first name is Oluwatobi.</h1>;
const mylastName = <h1>My last name is Sofela.</h1>;
function DisplayMyName() {
  if (firstName) {
    return myFirstName;
  } else {
    return mylastName;
  }
}
const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<DisplayMyName />);

index.html

<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>DisplayMyName App</title>
    <script src="https://unpkg.com/react@18/umd/react.development.js"></script>
    <script src="https://unpkg.com/react-dom@18/umd/react-dom.development.js"></script>
    <script src="https://unpkg.com/@babel/standalone/babel.min.js"></script>
  </head>
  <body>
    <div id="root"></div>
    <script type="text/babel" src="DisplayMyName.js"></script>
  </body>
</html>

The React snippet above stores JSX code in variables. We also made it the return value of a function’s if...else statement.

Wrap multi-line JSX in parentheses

Wrapping your JSX code in parentheses is best when it spans across multiple lines. Doing so will make your code readable and avoid the pitfalls of automatic semicolon insertion.

const myName = (
  <div>
    <h1>My name is Oluwatobi.</h1>
  </div>
);

The snippet above wraps the div in parentheses because it spans multiple lines.

Wrap expressions in curly braces

Suppose you wish to write JavaScript expressions in your JSX code. In that case, wrap the expression in curly braces like so:

ExpressionInJSX.js

function ExpressionInJSX() {
  return <h2>JSX makes it {10 * 3} times faster to build React UIs.</h2>;
}
const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<ExpressionInJSX />);

index.html

<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>ExpressionInJSX App</title>
    <script src="https://unpkg.com/react@18/umd/react.development.js"></script>
    <script src="https://unpkg.com/react-dom@18/umd/react-dom.development.js"></script>
    <script src="https://unpkg.com/@babel/standalone/babel.min.js"></script>
  </head>
  <body>
    <div id="root"></div>
    <script type="text/babel" src="ExpressionInJSX.js"></script>
  </body>
</html>

Tips:

• React reads curly braces ({...}) in JSX code as a JavaScript expression.

• Using curly braces to embed a JavaScript expression works only if you use it in either of two ways:

  1. Directly between the opening and closing JSX tags:

      <openingTag>I have a {javaScriptExpression} content.</closingTag>
     

  2. As the value of a JSX element’s attribute:

      <openingTag attribute={javaScriptExpression}>I have a content</closingTag>
     

Use camelCase to name attributes

React uses camelCase for JSX attribute keys rather than the lowercase HTML attribute naming convention. This is because, under the hood, JSX compiles into plain JavaScript and, therefore, uses the JavaScript Web APIs.

In other words, instead of writing readonly, use readOnly. Likewise, instead of using maxlength, write maxLength. By doing so, React will gain access to JavaScript’s readOnly and maxLength Web APIs.

Example:

const myName = (
  <div>
    <h1 className="about-me">My name is Oluwatobi.</h1>
  </div>
);

Close empty JSX tags properly

React requires closing all JSX elements explicitly with />, including empty tags. For instance, you’ll need to write an HTML <img> element as <img />.

Example:

const emptyJSXElement = <input type="button" value="Click me" />;

A React component can return only a single element

Creating two or more JSX elements from a component requires wrapping them in a single parent element. Otherwise, React will throw an error. This is because React components return only a single element.

Example:

TwoInnerUIs.js

function TwoInnerUIs() {
  return (
    <div>
      <h1>My name is Oluwatobi.</h1>
      <button>Buy me a coffee</button>
    </div>
  );
}
const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<TwoInnerUIs />);

index.html

<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>TwoInnerUIs App</title>
    <script src="https://unpkg.com/react@18/umd/react.development.js"></script>
    <script src="https://unpkg.com/react-dom@18/umd/react-dom.development.js"></script>
    <script src="https://unpkg.com/@babel/standalone/babel.min.js"></script>
  </head>
  <body>
    <div id="root"></div>
    <script type="text/babel" src="TwoInnerUIs.js"></script>
  </body>
</html>

In the expression above, the <div> is a parent element containing two (2) inner tags.

Tip: React allows using a fragment (empty tag) to group elements. Here’s an example:

function TwoInnerUIs() {
  return (
    <>
      <h1>My name is Oluwatobi.</h1>
      <button>Buy me a coffee</button>
    </>
  );
}
const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<TwoInnerUIs />);

Fragments are a great way to return multiple elements without creating unnecessary tags in the HTML DOM.

Time to Practice with JSX 🤸‍♂️🏋️‍♀️🏊‍♀️

Here is your moment to practice the JSX concepts you’ve learned.

In this exercise, you will convert the regular JavaScript code below to its JSX equivalent:

function SupportCodeSweetly() {
  return React.createElement(
    "div",
    { className: "support-ui" },
    React.createElement(
      "a",
      {
        id: "support-link",
        className: "support-link",
        target: "_blank",
        href: "https://www.buymeacoffee.com/codesweetly",
      },
      "Buy me a coffee"
    ),
    ". Thank you!"
  );
}

const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(React.createElement(SupportCodeSweetly));

Take a moment to try it yourself before looking at the solution below. Even if you have to try a couple times, go back and read the above tips, or google a few things, it’ll help you learn the concepts better.

Ok, now that you’ve tried…

The solution:

function SupportCodeSweetly() {
  return (
    <div className="support-ui">
      <a
        id="support-link"
        className="support-link"
        target="_blank"
        href="https://www.buymeacoffee.com/codesweetly"
      >
        Buy me a coffee
      </a>
      . Thank you!
    </div>
  );
}

const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<SupportCodeSweetly />);

The SupportCodeSweetly component returns the UI we want to display on-screen and manage with React. But what exactly is a React component?

What Is a React Component?

A component in React is a class or function that accepts a single argument called props and returns an element (UI).

Syntax of a React component

The above image illustrates the constituent parts of a React component:

1. A JavaScript function with a Pascal case naming convention.

2. A props parameter, which is the only argument React components accept. (Tip: props is short for properties.)

3. The component’s body, where you place a sequence of statements like variables, hooks, and conditionals.

4. A return statement, which is used to output the user interface (UI) you want React to display on-screen. It can be any valid HTML element.

5. An invocator that executes the component to retrieve its user interface. The invocator can also pass arguments (props) to the component.

Example of a React component

function MyBio(props) {
  return <h1>My name is {props.firstName}.</h1>;
}

Try it on CodeSandbox

The code in the snippet above is a function component that accepts a single argument (props) and returns a React element.

React components best practices

When you’re working with components in React, there are a few best practices you should follow:

• Capitalize the first letter of your component’s name.

• Don’t use bracket notation expressions in React component tags.

• React components work best as pure functions.

• Create components at the top level of your file.

• Split long components into smaller chunks.

As it’s common practice to use components to render a list of elements, let’s now discuss how to implement this optimally.

How to Render Lists of Elements from an Array

Suppose you want to create a list of React elements from an array of data. You can use the JavaScript map() method.

Example:

import ReactDOM from "react-dom/client";

// Define the bestColors array:
const bestColors = ["Blue", "White", "Pink"];

// Use the bestColors array to create a list of React elements:
const bestColorsLiElements = bestColors.map((color) => <li>{color}</li>);

// Render the array of <li> elements to the root DOM:
const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<ul>{bestColorsLiElements}</ul>);

Try it on CodeSandbox

The snippet above used map() to create a new list of React elements by converting each of bestColors items to <li> elements.

Notice that we rendered the list of elements directly in the root.render() method. Typically, you would use a component to do such rendering. So, let’s do some refactoring by moving the bestColorsLiElements variable and the <ul> element into a component:

import ReactDOM from "react-dom/client";

function BestColor() {
  // Define the bestColors array:
  const bestColors = ["Blue", "White", "Pink"];
  // Use the bestColors array to create a list of React elements:
  const bestColorsLiElements = bestColors.map((color) => <li>{color}</li>);
  return <ul>{bestColorsLiElements}</ul>;
}

// Render the array of <li> elements to the root DOM:
const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<BestColor />);

Try it on CodeSandbox

Although the snippet above displays the right content on the screen, it’s not efficient. So, React throws a console error. Let’s discuss the issue.

Each React element in an array needs a unique key

If you check your console, you will see a warning message that says: Each child in a list should have a unique "key" prop.

The message means that whenever you create an array of elements, React needs you to specify a unique identity for each item in the list.

The unique identity keys help React identify changes to the array.

Let’s refactor the previous snippet so that each element in the bestColorsLiElements has a unique key prop.

How to add unique keys to each React element in an array

There are two common ways to assign unique keys to each element of an array. The first is the unrecommended way. While the second is the best technique, it is worth noting.

Not recommended way to assign keys to an array of React elements

One way to add unique keys is to use each item’s index as its key prop.

Tip: By default, if you don’t provide a key prop, React uses each element’s index position in the array to identify them (key=0, key=1, and so on).

Example:

import ReactDOM from "react-dom/client";

function BestColor() {
  const bestColors = ["Blue", "White", "Pink"];
  // Use each item's index as its key prop:
  const bestColorsLiElements = bestColors.map((color, index) => (
    <li key={index}>{color}</li>
  ));
  return <ul>{bestColorsLiElements}</ul>;
}

const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<BestColor />);

Try it on CodeSandbox

The snippet above specifies a key prop on each <li> element. It then uses each item’s index as the prop’s value.

But note that it’s best to avoid using indexes as a React element’s key prop. You should use it only as a last resort when you don’t have stable IDs.

Whenever you use an index as the key prop, ensure the order of items in the array never changes. Otherwise, you may have severe issues with performance and component state.

Best way to assign keys to an array of React elements

The best way to add unique keys to each React element in an array is to use stable IDs from either of the following sources:

• Database: Use the database-generated IDs as the key props if your data comes from a database, as they are unique by default.

• crypto.randomUUID() incrementing counter: Use the randomUUID() method to generate Universally Unique Identifiers if you are creating and storing your data locally. (Note: This method is a web API. So, it’s available only in supporting browsers’ HTTPS contexts.)

• uuid: An NPM package for generating Universally Unique Identifiers if you are creating and persisting your data locally. This is a good alternative to the randomUUID() method for cross-platform compatibility.

Example:

index.js

import { createRoot } from "react-dom/client";
import { bestColors } from "./bestColors.js";

function BestColor() {
  // Use each item's id as its key prop:
  const bestColorsLiElements = bestColors.map((color) => (
    <li key={color.id}>{color.name}</li>
  ));
  return <ul>{bestColorsLiElements}</ul>;
}

const root = createRoot(document.getElementById("root"));
root.render(<BestColor />);

bestColors.js

export const bestColors = [
  { id: crypto.randomUUID(), name: "Blue" },
  { id: crypto.randomUUID(), name: "White" },
  { id: crypto.randomUUID(), name: "Pink" },
];

Try it on CodeSandbox

The snippet above specifies a key prop on each <li> element. It then uses each item’s id as the prop’s value.

Note: Each key prop should be unique among its siblings – not globally. It’s okay to use the same key for an element in a different array.

Essential things to know about assigning keys

Here are essential facts to remember whenever you assign keys to an array of React elements.

1. Set each array element’s key while creating the array

The right place to specify each array element’s unique key is directly inside the map() method while creating the list of elements.

In other words, say you extract your template element into a separate component. Set the key prop on the component’s invocation tag—not on the extracted template element.

Example 1: Incorrect placement of the key prop

index.js

import { createRoot } from "react-dom/client";
import { bestColors } from "./bestColors.js";

function ColorListElement({ color }) {
  // WRONG: Don't place the key outside the map() method.
  return <li key={color.id}>{color.name}</li>;
}

function BestColor() {
  const bestColorsLiElements = bestColors.map((color) => (
    // The key attribute above should have been set here.
    <ColorListElement color={color} />
  ));
  return <ul>{bestColorsLiElements}</ul>;
}

const root = createRoot(document.getElementById("root"));
root.render(<BestColor />);

bestColors.js

export const bestColors = [
  { id: crypto.randomUUID(), name: "Blue" },
  { id: crypto.randomUUID(), name: "White" },
  { id: crypto.randomUUID(), name: "Pink" },
];

Try it on CodeSandbox

The snippet above incorrectly sets each item’s key outside the map() method. You should avoid such a mistake!

Always set the key prop while creating the array of elements. So, the snippet above should have set the key on the component invocation tag – in the map() method.

Example 2: Correct placement of the key prop

index.js

import { createRoot } from "react-dom/client";
import { bestColors } from "./bestColors.js";

function ColorListElement({ color }) {
  return <li>{color.name}</li>;
}

function BestColor() {
  const bestColorsLiElements = bestColors.map((color) => (
    // CORRECT: Always define the key directly inside the map() method.
    <ColorListElement key={color.id} color={color} />
  ));
  return <ul>{bestColorsLiElements}</ul>;
}

const root = createRoot(document.getElementById("root"));
root.render(<BestColor />);

bestColors.js

export const bestColors = [
  { id: crypto.randomUUID(), name: "Blue" },
  { id: crypto.randomUUID(), name: "White" },
  { id: crypto.randomUUID(), name: "Pink" },
];

Try it on CodeSandbox

The snippet above correctly sets each item’s key inside the map() method. This allows React to access the key value for each element in the array returned by the map() method.

Tip: React’s reconciliation (diffing) algorithm is programmed to access the key of each top-level item of the array. It never looks for the key in the child or descendant elements.

2. React does not pass keys to components

React neither transfers the key prop to components nor includes it as an attribute of a rendered element.

React uses keys solely to know the state of array items. They help React identify changes to the array.

So if you need to use a specific key’s value in your component or on your DOM element, you should explicitly pass it as the value of a different attribute.

Example:

index.js

import { createRoot } from "react-dom/client";
import { bestColors } from "./bestColors.js";

function ColorListElement(props) {
  return (
    <li>
      {props.color.name} (ID: {props.id})
    </li>
  );
}

function BestColor() {
  // Use `color.id` as the `key` and `id` props' value.
  const bestColorsLiElements = bestColors.map((color) => (
    <ColorListElement key={color.id} id={color.id} color={color} />
  ));
  return <ul>{bestColorsLiElements}</ul>;
}

const root = createRoot(document.getElementById("root"));
root.render(<BestColor />);

bestColors.js

export const bestColors = [
  { id: crypto.randomUUID(), name: "Blue" },
  { id: crypto.randomUUID(), name: "White" },
  { id: crypto.randomUUID(), name: "Pink" },
];

Try it on CodeSandbox

The snippet above initializes each list item’s id attribute with the same value as the key prop. By so doing, the ColorListElement component can access props.id but not props.key.

3. Always generate the keys outside your components

Never generate keys on the fly (while rendering your components). Instead, create them in your data outside your components. Otherwise, React will recreate the elements on every rendering cycle because the key’s value will always be different.

Example 1: Incorrect place to generate the key prop

index.js

import { createRoot } from "react-dom/client";
import { bestColors } from "./bestColors.js";

function BestColor() {
  // WRONG: Never generate keys on the fly.
  const bestColorsLiElements = bestColors.map((color) => (
    <li key={crypto.randomUUID()}>{color}</li>
  ));
  return <ul>{bestColorsLiElements}</ul>;
}

const root = createRoot(document.getElementById("root"));
root.render(<BestColor />);

bestColors.js

// The keys' values should have been set here (outside the component while creating your data).
export const bestColors = ["Blue", "White", "Pink"];

Try it on CodeSandbox

The snippet above incorrectly generated each element’s key while rendering the BestColor component. You should avoid such a mistake to prevent subtle bugs caused by recreating the elements on every render.

Always create each key’s value in your data outside the component.

Example 2: Correct place to generate the key prop

index.js

import { createRoot } from "react-dom/client";
import { bestColors } from "./bestColors.js";

function BestColor() {
  const bestColorsLiElements = bestColors.map((color) => (
    <li key={color.id}>{color.name}</li>
  ));
  return <ul>{bestColorsLiElements}</ul>;
}

const root = createRoot(document.getElementById("root"));
root.render(<BestColor />);

bestColors.js

// CORRECT: Always generate the key in your data outside the component.
export const bestColors = [
  { id: crypto.randomUUID(), name: "Blue" },
  { id: crypto.randomUUID(), name: "White" },
  { id: crypto.randomUUID(), name: "Pink" },
];

Try it on CodeSandbox

The snippet above correctly generated each element’s key in the array data outside the component.

How to Handle Events in React

Event handling in React involves configuring your JSX elements to respond to user interactions on them (such as mouse clicks, form submission, and element focus).

<jsxTag onEvent={handleEvent}>UI Content</jsxTag>

Here’s what’s going on:

• jsxTag: React elements like <div>, <button>, and <input>.

• onEvent: The event listener you want to add to the React element. Some examples are onClick, onBlur, and onHover.

• handleEvent: The event handler function you want to use to handle (respond to) the specified onEvent type.

Tip: Although you can name the event handler anything you prefer, the typical naming convention is to prefix the event’s name with “handle”. For instance, if the event’s name is focus, the handler’s name will be handleFocus.

Types of event handlers

There are two typical ways to define the event handler function in React:

• Inline event handler: A function defined directly on a JSX element’s opening tag as the value of the event listener prop (onEvent).

• Referenced event handler: A function defined as a separate (independent) logic and linked to an event listener attribute (onEvent) by name referencing.

Example: Inline event handler

export default function App() {
  return (
    <h1 onClick={() => alert("You clicked the heading!")}>
      Oluwatobi is my name.
    </h1>
  );
}

Try it on CodeSandbox

Example: Referenced event handler

export default function App() {
  return <h1 onClick={handleClick}>Oluwatobi is my name.</h1>;
}

const handleClick = () => alert("You clicked the heading!");

Try it on CodeSandbox

React components have a unique memory that allows them to remember things between renderings. This memory is called “state.”

What Is React State?

React state is a component’s memory for storing data that React should remember during a component’s re-rendering and whose update should trigger a new render.

Syntax of React state:

import { useState } from "react";

function App() {
  const [state, setState] = useState(initialState);

  // ...
}

• state: The variable containing the component’s state value.

• setState: A function for updating the state value.

• useState: The state Hook for initializing and retrieving the component’s state.

Example of React state:

import { useState } from "react";

function AboutCompany() {
  const [age, setAge] = useState(5);

  function updateAge() {
    setAge(age + 1);
  }

  return (
    <div>
      <h3>CodeSweetly is {age} years old!</h3>
      <button type="button" onClick={updateAge}>
        Click to update age
      </button>
    </div>
  );
}

export default AboutCompany;

Try it on CodeSandbox

When a user clicks the button UI, the onClick event triggers the updateAge event handler, which uses the setAge setter function to update the component’s age state.

Tip: React will trigger a re-render of your component every time you use useState’s setter function to update your state. But what exactly do the terms “trigger” and “render” mean?

React Trigger vs Render vs Commit vs Paint

Triggering, rendering, committing, and painting are the steps involved in displaying React UIs on screen. Here are the differences between the four steps:

The above slide illustrates the four phases in the lifecycle of a component’s UI:

• Trigger: Specifies the component whose UI you want to display on the screen.

• Render: Calls the component you’ve triggered.

• Commit: Updates the DOM with the UI of the rendered component.

• Paint: Converts the DOM code you’ve committed into user-friendly elements that users can interact with in their browsers.

Let’s discuss these differences in detail.

What does it mean to trigger a render in React?

The trigger event is the first step in displaying a React user interface (UI) on screen. It specifies the component whose UI you want to display on the screen. This event happens on two occasions:

1. When the app starts running. The React application uses the createRoot method to specify the component whose UI you want to render to a DOM node.

import ReactDOM from "react-dom/client";
import DonationUI from "./components/DonationUI.js";

// When the app starts running, you need to use createRoot and its render method to trigger an initial rendering of the app's root component.
const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<DonationUI />);

The snippet above does the following:

• Uses the ReactDOM.createRoot() method to create a ReactDOMRoot object instance for the root element argument.

• Use the object instance’s render() method to trigger an initial rendering of the DonationUI component.

In other words, the createRoot().render() method specifies DonationUI as the component whose UI React should display in the root HTML element.

2. The second reason a trigger event can happen is when a component’s (or its ancestors’) state gets updated with a set function.

DonationUI.js

import React from "react";

function DonationUI() {
  const [donate, setDonate] = React.useState(false);
  function createUserInterface() {
    if (donate) {
      return (
        <p>
          <a href="https://www.buymeacoffee.com/codesweetly">Support page</a>.
          Thank you so much!
        </p>
      );
    }
    // The setDonate function will trigger a re-rendering of the DonationUI component.
    return <button onClick={() => setDonate(true)}>Buy me a coffee</button>;
  }
  return createUserInterface();
}

export default DonationUI;

The snippet above does the following:

1. Defines a component named DonationUI.

2. Initializes the component’s state with the Boolean value false.

3. Programs the component to return a paragraph element if the state’s donate variable is true. Otherwise, it should return a button element.

When users click the button element, the setDonate setter function will trigger a re-rendering of the DonationUI component. Below are the entry script and the HTML code so you can try it yourself locally.

index.js

import ReactDOM from "react-dom/client";
import DonationUI from "./components/DonationUI";

const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<DonationUI />);

index.html

<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>CodeSweetly DonationUI</title>
  </head>
  <body>
    <main id="root"></main>
    <script type="module" src="index.js"></script>
  </body>
</html>

Try it on CodeSandbox

What does it mean to render React components?

The rendering step is when React invokes (calls) the component you’ve triggered with either the createRoot method or a set function. Rendering causes React to invoke a component to produce the UI you want to display on the screen. The component React will render depends on the moment the trigger event occurred:

• For an initial trigger (at the start of the app), React will invoke the app’s root component.

• For update triggers (whenever a component’s state gets updated), React will call the function component whose state update initiated the trigger event.

Tip: Rendering a component means “calling a component” to retrieve its user interface (UI).

What does it mean to commit a React UI to the browser’s DOM?

The committing stage is when React updates the DOM with the UI of the rendered component.

There are some important things to note about this process:

• For an initial render (at the start of the app), React will initialize the root DOM with the root component’s UI. It will use the appendChild() JavaScript API to append the DOM nodes (UI) retrieved from the component into the app’s root HTML element.

• For subsequent re-rendering (after the initial commit), React will only update the DOM nodes if there’s a difference between the previous rendering output and the latest one. No changes will occur if the component’s latest output is the same as the previously committed one.

What does it mean to paint the DOM nodes on the screen?

The painting (browser rendering) stage is when the browser repaints the screen to convert the DOM code to user-friendly elements. This is a browser-level process that begins once React has finished updating (committing) the DOM nodes.

Sometimes, components need to store information that shouldn’t trigger a render when updated. In these situations, you can use a ref.

What Is the React Ref Hook?

The React Ref Hook lets you store values that don’t trigger re-renders when changed.

Syntax of the React ref Hook

The useRef Hook accepts only one optional argument. Here is the syntax:

useRef(initialValue);

• initialValue: The value to store in the component’s ref memory. Any JavaScript data type is allowed.

• useRef(): Returns an object ({ current: initialValue }).

Example of the React ref Hook:

import { useRef } from "react";

function App() {
  const myNameRef = useRef("Oluwatobi");

  function handleClick() {
    console.log(myNameRef.current); // Outputs: "Oluwatobi"
  }

  return <button onClick={handleClick}>Click me</button>;
}

export default App;

Try it on CodeSandbox

The snippet above used the useRef Hook to store a value ("Oluwatobi") whose update shouldn’t trigger re-renders.

React ref Hook best practices

When you’re working with React’s ref hook, there are some best practices you should follow:

• Use dot syntax to access and update a ref object’s value instead of square bracket notation.

• Avoid accessing or updating the current property during rendering to maintain the purity of your components.

• Don’t use a function instance as your initialValue. Pass the function itself, not its output.

• You can use the React ref Hook to manage your HTML DOM nodes.

But what’s the difference between refs, states, and variables, I hear you ask? Let’s find out below.

Variables vs Refs vs States in React

In React, variables, refs, and states allow you to store and mutate data. But they work in different ways. Here are the main distinctions between them:

1. Does its value persist during re-rendering?

   • React Ref: Yes

   • React State: Yes

   • JavaScript Variable: No

2. Would updating its value trigger a re-rendering of the component?

   • React Ref: No

   • React State: Yes

   • JavaScript Variable: No

3. Is it plain JavaScript?

   • React Ref: Yes

   • React State: No

   • JavaScript Variable: Yes

4. Can you declare it outside a component?

   • React Ref: No

   • React State: No

   • JavaScript Variable: Yes

5. Is it usable in conditional statements, loops, or nested functions?

   • React Ref: No

   • React State: No

   • JavaScript Variable: Yes

How do variables work in React?

A variable’s value does not persist during re-rendering. Its value resets at the beginning of a new rendering.

Example:

import { useState } from "react";

function App() {
  let myVar = 0;
  const [myState, setMyState] = useState(0);

  function updateVar() {
    myVar = myVar + 1;
    console.log("myVar =", myVar);
  }

  function updateState() {
    setMyState(myState + 1);
  }

  return (
    <div>
      <h2>Variable: {myVar}</h2>
      <h2>State: {myState}</h2>
      <button onClick={updateVar}>Update Variable</button>
      <button onClick={updateState}>Update State</button>
    </div>
  );
}

export default App;