DEV Community: Huiren Woo

Using Jest and LLM assistance to test your real-time chat

Huiren Woo — Tue, 11 Nov 2025 09:10:16 +0000

In the previous article, we delved into creating a simple web server that serves static files, flat file database that uses lock and the API endpoints that allows for real-time chat interaction. In this article, we'll follow-up by taking a look into writing unit tests for our flat file database to ensure that our chat interaction flow works.

What and how to test

We will look at how to setup the testing environment and how to write the tests using Large Language Model (LLM). The scope of the LLM parts of the article would mostly be covering upon using LLM in an agentic manner. It also briefly mentions alternative ways of achieving a similar result in non-agentic approach too. However, areas such as Model Context Protocol (MCP) is outside the scope of this article and would not be touched on. While going through the 'how' aspects of doing tests, we will also evaluate 'what' exactly we are trying to test.

Testing environment setup

For our testing, we will need some developer dependency for mocking and doing spy on certain NodeJS promises. In this article, we are going to setup the environment using popular tools such as Jest. Jest is a comprehensive testing library that includes test runner, assertions and mocking tools which can be used on NodeJS. There are also other tools out there that will do the job equally well for our use-case. The main reason why they were picked was due to their current popularity. Even if you decide to use a different tool, the same concept can be applied.

For the purpose of this article, I am running a Long-Term Support (LTS) version of NodeJS, specifically Node v22.16.0. You will need both NodeJS and Node Package Manager (NPM) to continue. For the sake of brevity, I will not go through how to install NodeJS or NPM. You should refer to Node Version Manager (NVM) on how to do installation for your specific Operating System (OS).

Once you have ensured that you have the correct Node environment, we can then setup the testing tools that we will need. Make sure your NPM environment in your directory has been initialised with a package.json configuration file. If it has not been initialised, you can run the following command the initialise it. Fill in the details as you deem necessary.

npm init

Next, we can install some optional tools that will help us. Node types and jest global types are optional as they're only there to help aid your IDE or code editor to understand the code type hints. These type hints will then allow the IDE to provide "intellisense" or auto-completions which would be extremely useful to you. You can run the following command on your Command Line Interface (CLI) to install Jest types and Node types:

npm install --save-dev @jest/globals @types/node

In the following parts, we'll be setting up the installation for Jest. We will also need to edit our configuration a bit and limit Jest to running unit-tests.

Firstly, let's setup a Jest installation and ask it to initialise a basic configuration file for us to configure. Run the following command to do that. This should create a configuration file named jest.config.mjs which we will configure in awhile.

npm init jest@latest

The command will prompt you with a few questions. For the most part, you can answer them as you deem necessary but make sure you answer no to Typescript, test environment to node and set the provider to v8. If you're new and unfamiliar, here is how I setup mine.

✔ **Would you like to use Jest when running "test" script in "package.json"?** … yes

✔ **Would you like to use Typescript for the configuration file?** … no

✔ **Choose the test environment that will be used for testing** › node

✔ **Do you want Jest to add coverage reports?** … no

✔ **Which provider should be used to instrument code for coverage?** › v8

✔ **Automatically clear mock calls, instances, contexts and results before every test?** … no

Now, we'll need to configure our newly generated Jest configuration file. The following code will alter the configuration in a way that will only allow .jest.test files to run using Jest. Since we are using Jest for writing tests for NodeJS, we also need to specify the test environment.

// jest.config.mjs
...
testEnvironment: "node",
...
testRegex: [  
    '.*\\.jest\\.test\\.[jt]sx?$'  
],
...

Finally, we'll need to edit our package.json file's NPM scripts. This is because we'll be writing Jest test code in ECMAScript modules instead of CommonJS. Thus, we'll need to specify NodeJS to use experimental-vm-modules. The following change adds the appropriate scripts for their respective tools.

// package.json
...
"scripts": { 
  "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"  
},
...

Full package.json output

For the sake of clarity, the following is the full output of my package.json file. This is especially useful if you're viewing this from the future where versions might have changed and the installation commands installed a newer version which might not be relevant or correct.

{  
  "name": "zenika-chat-app",  
  "version": "1.0.0",  
  "type": "module",  
  "main": "index.js",  
  "scripts": {  
    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"  
  },  
  "keywords": [],  
  "author": "",  
  "license": "ISC",  
  "description": "",  
  "devDependencies": {  
    "@jest/globals": "^30.0.4",  
    "@playwright/test": "^1.53.1",  
    "@types/node": "^24.0.4",  
    "jest": "^30.0.4"  
  }  
}

Leveraging LLM for testing

We will first start off by defining the scope of our LLM usage. We will not rely on Large Language Models (LLM) for brainstorming or generating test cases. This is because the LLM might be taking sample information from a pool of badly reason test cases or perhaps, the test-case might not be applicable to your use case. It is extremely important to use our own reasoning skills to craft our own bespoke test-cases. There is also a common misunderstanding due to marketing gimmicks used by LLM companies to present their models as "reasoning". As far as my limited understanding and personal opinion goes, scientific reasoning is not yet possible with the current models and they're still mostly statistical compute machines. This means that you, as the engineer prompter, needs to do the reasoning and thinking. Hence, we will create and reason the test-cases ourselves and thereafter, prompt the LLM to generate the code for our test-cases. You need to provide a lot of guidance to the LLM to make the code work and there's a high chance that the code would not work on the first attempt and would require adjustments or fixes. This would usually mean that we will need to undergo an iterative process to improve the output results of the LLM. You will need to feed a prompt to it and adjust by giving it more information or ask it to correct certain parts of it; iterating till it reaches the ideal state. For the appropriate scenarios, I will be providing a potential prompt which you can try out with a LLM and ask it to help scaffold the initial test code for you. Here is how I would imagine the process to look like:

Identify important parts or critical paths to be tested
Brainstorm and describe the workflows that involves these critical paths
Describe a prompt with specific steps on areas which requires careful guidance
Feed the prompt to the LLM
Verify, evaluate and test the output
Iterate the process until the output is in an ideal state

LLM setup

You can use LLM by either asking it or using it in an agentic manner where the agent would automatically read your files and understand your code structure. For the purpose of this practice, I will be using GitHub co-pilot in Jetbrains Webstorm IDE and using its "Ask" function and attach the relevant files as context. Thereafter, it will generate the code in Co-pilot conversation and I then copied the code over. You could also use GitHub co-pilot in VSCode and the experience will be almost the same. Similarly, you could use ChatGPT (without GPT codex) and provide the necessary prompt and context but it will be much more tedious and of a hassle to do so. If you do not have any of those installed, I would recommend installing the GitHub co-pilot plugin in your favourite code editor but if you do not wish to do so, you could also just use ChatGPT and manually follow along. Specification Driven Development (SDD) will not be covered in the scope of this article as there are complexities, nuances and extra security measures that needs to be covered upon.

In the following segment, we will write some helper utility code that will assist the LLM in testing the flat file database we have written and some of the chat full workflow interactions. In order to generate random data containing random usernames, messages and timestamp, we will want to have convenient and re-usable methods to creating random valid strings and random valid timestamps. Here are some handy functions for us to generate some test data. You should attach the code files as context so that the LLM will able to use these functions in writing the test code. If you're using ChatGPT, you would need to copy this code into your prompt context.

import {randomBytes} from "node:crypto";  

export function generateRandomTimestamp() {  
    const randomDay = Math.floor(Math.random() * 1000);  
    return (new Date(randomDay * 24 * 60 * 60 * 1000)).toISOString();  
}  

export function generateRandomString(byteLength) {  
    return randomBytes(byteLength).toString('base64');  
}

Now, we can proceed to prompt the LLM to write code to test for the areas mentioned.

Testing flat file database

We want to test certain key parts of the flat file database since the flat file database is an important component of our system. Our system would not work if the flat file database does not work based on our assumptions. The composition of the flat file database is interesting in the sense that it might not be obvious that there are lots of other parts abstracted from our view. Whenever we try to use our code to read or write the flat file database, it calls upon NodeJS functions will relies on the operating system's filesystem ability to read and write. There are parts which we would be interested in but also parts which we are not really interested in testing. Let's illustrate this with a simplified diagram.

In our specific use case, we aren't really interested in the actual underlying read or write operations on the operating system filesystem's level. We could make the assumption that NodeJS and the operating system's filesystem is reading and writing as expected. This would reduce the amount of tests we need to do and the complexity we need to handle. But how can we do that? We can mock the implementations of the NodeJS APIs.

When mocking, we can also spy on the parameters used when calling the mocked functions. This allows us to make assertions that the parameters are behaving according to our expectations.

And thereafter, we can even return a mocked response that would allow our software application to function as if it was in an ideal environment.

How Jest can help

Jest is extremely useful here as it makes spying much less of a hassle. We want to be able to mock the read and write operations but still be know that these functions have been called with its appropriate parameters. Its ability to let us mock enables us to observe the parameters sent to the NodeJS APIs easily and make assertions to confirm that the behaviour is as expected.

Diving into the testing parts

First, let's identify the parts which can be considered important. There are a few ways of identifying, one of which would be the critical paths. In our critical paths of reading and writing messages, there are a few requirements that needs to work. Hence, these are the parts that are important and which we would want to test.

For the use case of reading from the database:

Data needs to be readable
- This means that the data from the file to be parsed correctly, follow the specified JSON structure for our defined message and for our code to be able to reference this newly created parsed JSON object.

For the use case of writing to the database:

Data needs to be readable
- Because of how the writes would actually overwrite the previous data, it requires the application to read the previous data and merge with it before writing.
Data needs to be writable
- This means that the JSON object data we write to the file needs to be serialised into string format correctly, should produce the specified stringified JSON structure as defined and finally, to be appended correctly to the list of existing JSON string messages that we have.
There needs to be write-safety using write-lock
- This means that the writelock file must exists when we are doing writes and the other server nodes trying to write to this same file must wait until the write lock is released.

For the use case of storing data over longer periods of time:

Data needs to be persistent
- This means that the data that we write should not be temporal and must exists unless we take action to remove it. Restarting the server or shutting down the server should not affect the existence of data.

For the use case of being able to scale horizontally:

The data should be relatively consistent across several independent nodes (cloud native)
- When other server nodes try to access or read the same data, it should return the same data to all the other server nodes.

After identifying the key components, we will need to understand how we can test these parts. There are various ways to go about testing different parts and for our use case, we can go with something simple. As mentioned in the above points, we can mock the parts that do writing or reading to the filesystem as we do not need to care about its actual underlying behaviours. Data being persistent might be a bit difficult to test in a unit test, so that might be better resolved in an integration test or end-to-end test.

Next, we will evaluate the happy paths related to our workflows. The ideal scenario workflow for message retrieval would look like this:

Attempt to read from the directory and the database flat file's contents
If the database flat file does not exist, we do not create a new database file and we only return empty
If the database flat file exists, read the contents and JSON parse it.
It should successfully parse the JSON contents and return the data in an expected data format
Return the expected Promise data based on the given data stored in the flat file

And the ideal scenario workflow for message sending would look like this:

Attempt to see if there is a write-lock
If there is no write-lock, attempt to create a write-lock file
Attempt to read from the directory and the database flat file's contents
If the database flat file does not exist, return empty data
If the database flat file exists, read the contents and JSON parse it.
Add the new message to the JSON file
Remove the write-lock file

Potential prompting

Given the key parts that we want to test and the happy path scenarios, we can then formulate our prompt. We need to provide guidance on some specific executions, such as how to mock. This is because there are many ways to spy and mock, and without the specific guidance specific to our code, it might end up generating code that is irrelevant or incorrect.

Based on the given source code context, write the Jest test-cases for the given ideal scenario workflow for message retrieval and message sending. Take note that this is a Jest setup in NodeJS using pure JavaScript, use Jest global imports wherever possible. The test function should start with "should XXX", which means it should look like this: 

test("should XXX", () => {

}); 

The data is stored in a flat file so that means that you need to mock the implementation of the appropriate functions to prevent actual file read or writes. I am giving you a tutorial example of how to do a mock implementation, please use this style of mocking to write the whole test file, including all beforeEach and beforeAll and afterEach and afterAll, and also include the Jest spyOn and mock implementation code where appropriate. 

jest.spyOn(fs, 'readFile').mockImplementation(async (path) => {  
    if (path === db.dbFilePath) {  
        return Promise.resolve(JSON.stringify(writtenData?.data || []));  
    }  
    if (path === db.lockFilePath) {  
        return Promise.resolve(lockFileContent || '');  
    }  
    return Promise.resolve();  
});

And then here is the workflow scenario:

<insert the workflow scenario here>

Result

Your prompt result should minimally guarantee that it uses the mock for readFile and all other related parts. The following was the raw unedited code output generated by the LLM for me. You might get a similar output. However, you should not use the code as is without reviewing or editing.

import db from "../db.js";
import {randomUUID} from "node:crypto";
import fs from "node:fs/promises";
import {generateRandomString, generateRandomTimestamp} from "../dbTestUtils.js";
import {afterAll, afterEach, beforeAll, describe, expect, jest, test} from '@jest/globals';

describe("Message Retrieval Workflow Testing", () => {
    let readFileSpy;
    let accessSpy;
    let writeFileSpy;
    let unlinkSpy;

    let dbFileExists = false;
    let dbFileData = null;
    let lockFileExists = false;
    let lockFileContent = null;

    beforeAll(() => {
        readFileSpy = jest.spyOn(fs, 'readFile').mockImplementation(async (path) => {
            if (path === db.dbFilePath) {
                if (!dbFileExists) {
                    const error = new Error('File does not exist');
                    error.code = 'ENOENT';
                    throw error;
                }
                return Promise.resolve(JSON.stringify(dbFileData || []));
            }
            if (path === db.lockFilePath) {
                if (!lockFileExists) {
                    const error = new Error('File does not exist');
                    error.code = 'ENOENT';
                    throw error;
                }
                return Promise.resolve(lockFileContent || '');
            }
            return Promise.resolve();
        });

        accessSpy = jest.spyOn(fs, 'access').mockImplementation(async (path) => {
            if (path === db.dbFilePath && dbFileExists) {
                return Promise.resolve();
            }
            if (path === db.lockFilePath && lockFileExists) {
                return Promise.resolve();
            }
            const error = new Error('File does not exist');
            error.code = 'ENOENT';
            throw error;
        });

        writeFileSpy = jest.spyOn(fs, 'writeFile').mockImplementation(async (path, data) => {
            return Promise.resolve();
        });

        unlinkSpy = jest.spyOn(fs, 'unlink').mockImplementation(async (path) => {
            return Promise.resolve();
        });
    });

    afterEach(() => {
        jest.clearAllMocks();
        dbFileExists = false;
        dbFileData = null;
        lockFileExists = false;
        lockFileContent = null;
    });

    afterAll(() => {
        readFileSpy.mockRestore();
        writeFileSpy.mockRestore();
        accessSpy.mockRestore();
        unlinkSpy.mockRestore();
    });

    test("should return empty array when database file does not exist", async () => {
        dbFileExists = false;

        const messages = await db.readMessages();

        expect(messages).toEqual([]);
        expect(readFileSpy).toHaveBeenCalledWith(db.dbFilePath);
        expect(writeFileSpy).not.toHaveBeenCalled();
    });

    test("should read and parse JSON contents when database file exists with valid data", async () => {
        const testMessages = [
            {
                id: randomUUID().toString(),
                author: generateRandomString(15),
                content: generateRandomString(100),
                timestamp: generateRandomTimestamp()
            },
            {
                id: randomUUID().toString(),
                author: generateRandomString(20),
                content: generateRandomString(150),
                timestamp: generateRandomTimestamp()
            }
        ];

        dbFileExists = true;
        dbFileData = testMessages;

        const messages = await db.readMessages();

        expect(messages).toEqual(testMessages);
        expect(readFileSpy).toHaveBeenCalledWith(db.dbFilePath);
        expect(messages).toHaveLength(2);
        expect(messages[0]).toHaveProperty('id');
        expect(messages[0]).toHaveProperty('author');
        expect(messages[0]).toHaveProperty('content');
        expect(messages[0]).toHaveProperty('timestamp');
    });

    test("should return empty array when database file exists but contains empty array", async () => {
        dbFileExists = true;
        dbFileData = [];

        const messages = await db.readMessages();

        expect(messages).toEqual([]);
        expect(readFileSpy).toHaveBeenCalledWith(db.dbFilePath);
    });

    test("should successfully parse JSON and return data in expected format", async () => {
        const expectedMessage = {
            id: randomUUID().toString(),
            author: "TestUser",
            content: "Test message content",
            timestamp: Date.now()
        };

        dbFileExists = true;
        dbFileData = [expectedMessage];

        const messages = await db.readMessages();

        expect(messages).toEqual([expectedMessage]);
        expect(typeof messages[0].id).toBe('string');
        expect(typeof messages[0].author).toBe('string');
        expect(typeof messages[0].content).toBe('string');
        expect(typeof messages[0].timestamp).toBe('number');
    });

    test("should handle multiple messages with different data types correctly", async () => {
        const testMessages = [
            {
                id: randomUUID().toString(),
                author: generateRandomString(10),
                content: generateRandomString(50),
                timestamp: generateRandomTimestamp()
            },
            {
                id: randomUUID().toString(),
                author: generateRandomString(25),
                content: generateRandomString(200),
                timestamp: generateRandomTimestamp()
            },
            {
                id: randomUUID().toString(),
                author: generateRandomString(8),
                content: generateRandomString(75),
                timestamp: generateRandomTimestamp()
            }
        ];

        dbFileExists = true;
        dbFileData = testMessages;

        const messages = await db.readMessages();

        expect(messages).toEqual(testMessages);
        expect(messages).toHaveLength(3);
        messages.forEach(message => {
            expect(message).toHaveProperty('id');
            expect(message).toHaveProperty('author');
            expect(message).toHaveProperty('content');
            expect(message).toHaveProperty('timestamp');
        });
    });

    test("should not create new database file when file does not exist", async () => {
        dbFileExists = false;

        await db.readMessages();

        expect(writeFileSpy).not.toHaveBeenCalledWith(db.dbFilePath, expect.any(String));
    });

    test("should return Promise that resolves to expected data format", async () => {
        const testMessage = {
            id: randomUUID().toString(),
            author: "PromiseTestUser",
            content: "Testing Promise resolution",
            timestamp: Date.now()
        };

        dbFileExists = true;
        dbFileData = [testMessage];

        const messagesPromise = db.readMessages();

        expect(messagesPromise).toBeInstanceOf(Promise);

        const messages = await messagesPromise;
        expect(messages).toEqual([testMessage]);
    });
});

Validating the prompt
The code generated by the LLM cannot be trusted and must be validated manually. There could potentially be security concerns too. There are several steps that are required in validating the prompt.

1) The code generated should fulfill the workflow given and assert the necessary parts
2) The code generated should have utilised the example given and replicate its part accordingly and where necessary
3) The code generated should not contain any strange code that does not make sense as it could potentially contain a shell fork bomb or maybe even a virus
4) The code generated should be ideally bug-free
5) The code generated should be optimal
6) Finally, the code generated should run without any issue

Based on the code, it was relatively impressive that it was able to use the code setup test helper utility code and managed to follow the structure based on the specified code. It looks mostly correct on first glance but if you look carefully, there were some areas which it fell short of. You can run the test by using the following command on your project root directory.

npm run jest

However, just because it can run, doesn't mean the code itself is correct. This was the output I received after running it.

npm run test                               

> zenika-chat-app@1.0.0 test
> node --experimental-vm-modules node_modules/jest/bin/jest.js

(node:65995) ExperimentalWarning: VM Modules is an experimental feature and might change at any time
(Use `node --trace-warnings ...` to show where the warning was created)
 FAIL  __tests__/db.jest.test.js
  Message Retrieval Workflow Testing
    ✕ should return empty array when database file does not exist (4 ms)
    ✕ should read and parse JSON contents when database file exists with valid data (2 ms)
    ✕ should return empty array when database file exists but contains empty array (1 ms)
    ✓ should successfully parse JSON and return data in expected format (1 ms)
    ✓ should handle multiple messages with different data types correctly (1 ms)
    ✓ should not create new database file when file does not exist
    ✓ should return Promise that resolves to expected data format

If we were to inspect the test case "should handle multiple messages with different data types correctly", we would find that was not useful for our context / usage. This is because our simple flat file database does not have a string length limitation unlike other databases like MySQL or PostgreSQL which would have things like varchar(255) and varchar(63) which imposes different string length limits.

If we were to nitpick even further, there were unused variables in the mockImplementation that could be removed. The code here suggests that the LLM failed to understand how mockImplementation works for Jest. This is because we do not need need to pass in variables as arguments even if the function provides them. We can simply omit them if they're not used in our mock implementation.

Your experience might differ from mine. Ideally, you should have some coding experience as it would be valuable in aiding you to debug what went wrong with the output code and if it is a simple error, you would then be able to manually fix it. However, if the output code does not even have the sound structure, I would recommend you to start a new conversation with a new adjusted prompt instead of asking the LLM to fix the issues. Patience is required as this is an iterative process and the LLM might not get it right on the first attempt.

Fixing the LLM generated code

In my case, I can debug what went wrong and ask it to fix the errors. Because I have experience with Jest and JavaScript, I could read the error and understand the problem was that the encoding information is missing for the assertion.

Based on the error, I have identified a few ways to fixing this:
1) Change assertion for readFileSpy, specifically its assertion of toHaveBeenCalledWith, to have 'utf-8' as its 2nd parameter
2) OR remove the assertion for readFileSpy, specifically its assertion of toHaveBeenCalledWith

I did not give it the solution. Instead, I simply pasted the entire error log output and asked the LLM to fix it for me. It then made corrections and removal to the test code. To make it more succinct, I've remove the areas which are not relevant to the fix.

describe("Message Retrieval Workflow Testing", () => {
    beforeAll(() => {  
        readFileSpy = jest.spyOn(fs, 'readFile').mockImplementation(async (path, encoding) => {  
            if (path === db.dbFilePath) {  
                if (!dbFileExists) {  
                    const error = new Error('File does not exist');  
                    error.code = 'ENOENT';  
                    throw error;  
                }  
                return Promise.resolve(JSON.stringify(dbFileData || []));  
            }  
            if (path === db.lockFilePath) {  
                if (!lockFileExists) {  
                    const error = new Error('File does not exist');  
                    error.code = 'ENOENT';  
                    throw error;  
                }  
                return Promise.resolve(lockFileContent || '');  
            }  
            return Promise.resolve();  
        });  
        // other code
    });  
    // other code
    test("should return empty array when database file does not exist", async () => {  
        dbFileExists = false;
        const messages = await db.readMessages();
        expect(messages).toEqual([]);  
        expect(accessSpy).toHaveBeenCalledWith(db.dbFilePath);  
        expect(writeFileSpy).not.toHaveBeenCalled();  
    });  

    test("should read and parse JSON contents when database file exists with valid data", async () => {  
        const testMessages = [  
            {  
                id: randomUUID().toString(),  
                author: generateRandomString(15),  
                content: generateRandomString(100),  
                timestamp: generateRandomTimestamp()  
            },  
            {  
                id: randomUUID().toString(),  
                author: generateRandomString(20),  
                content: generateRandomString(150),  
                timestamp: generateRandomTimestamp()  
            }  
        ];  

        dbFileExists = true;  
        dbFileData = testMessages;  

        const messages = await db.readMessages();  

        expect(messages).toEqual(testMessages);  
        expect(readFileSpy).toHaveBeenCalledWith(db.dbFilePath, "utf8");  
        expect(messages).toHaveLength(2);  
        expect(messages[0]).toHaveProperty('id');  
        expect(messages[0]).toHaveProperty('author');  
        expect(messages[0]).toHaveProperty('content');  
        expect(messages[0]).toHaveProperty('timestamp');  
    });  

    test("should return empty array when database file exists but contains empty array", async () => {  
        dbFileExists = true;  
        dbFileData = [];  

        const messages = await db.readMessages();  

        expect(messages).toEqual([]);  
        expect(readFileSpy).toHaveBeenCalledWith(db.dbFilePath, "utf8");  
    }); 
    // other code here
});

Reviewing and evaluating its proposed fix

It seems like the LLM chose with an option similar to (1) but not exactly. It changed the readFileSpy assertion for test case 1 to accessSpy whereas for test cases 2 and 3, it used option (1). These corrections are generally fine. However, it did something that isn't really correct; it had added legs to a snake (chinese idiom). For whatever reason, it decided that adding encoding into the mockImplementation for readFileSpy would fix the problem. This goes back to reaffirm my previous guess which was that it failed to understand how mockImplementation works. That addition does not fix the problem nor does it really create any new problems, so, not really a big deal in the grand scheme of things. To the LLM's credit, the test code was fixed!

Let's continue on with other scenarios that may happen and we want to potentially handle it safely. Here are some unhappy scenarios that might be worth considering:

What happens when the directory cannot be written?
What happens when the file cannot be read?
What happens when the lock-file cannot be read/written?
What happens if someone manually changed the JSON contents but made the formatting incorrect?
What happens if someone manually changed the JSON contents but contained invalid JSON format?

For those above-mentioned scenarios, you can apply the same concept and similar prompt and ask the LLM to generate the test code for you. But that seems to be tedious to have to keep copying and pasting the prompt. On top of that, it might be tedious for your team members to use this shared prompt too.

Reusable instructions

The following segments are specific to GitHub co-pilot but similar concepts apply to other LLM tools such as GPT codex, Claude (which would be similar to Claude skills) and on a limited level, Junie too. We will explore two methods of reusing the prompts / instructions. Both methods will have their instructions written in Markdown format, specifically the CommonMark. These files have their extension as .md. They can be used together and does not need to be mutually exclusive.

Transforming into repository-wide instructions

GitHub co-pilot and other agents like Junie allows you to add repository-wide custom instructions that will automatically be used every time it runs. However, although it works fine most of the time, it is not guaranteed to be reliable. Even if the agent has read the file and picked up your instruction, the agent might still misbehave and not use the included information and steps. This is not really the feature's fault but more of an issue with the LLM's reliability. You should treat repository instructions as helpful hints to the LLM and not a safety guarantee.

We can create a sub-section where we include details and guidelines as to how to write Jest tests for the repository.

What / where

As of writing, WebStorm IDE supports a single file copilot instructions. The instructions for our prompt should be put into .github/copilot-instructions.md. You would want to include project information such as its language, software architecture, testing framework, tools or other dependencies. In addition, you should add explicit information about how code and tests should be structured and include short examples so the LLM has concrete patterns to follow. You can also ask the LLM to generate repo-wide guidelines for you and then iterate on the generated draft.

How to write effective repository instructions

Keep three constraints in mind: concise, canonical, and scoped.

Concise: keep each instruction sentence short and focused. Long paragraphs are easy for the model to ignore.
Canonical: provide a small number of canonical examples that demonstrate the exact structure you expect (file header, imports, test naming, assertions).
Scoped: include broad project rules but avoid step-by-step workflows or long multi-step procedures. Those belong in prompts.

Include:

Project-level facts (language, runtime, module system).
Testing framework and versions (e.g., Jest, config caveats).
Global conventions (naming, where tests live, mocking preferences).
A single short example test that demonstrates preferred structure.

Avoid:

Secrets, long logs, huge code dumps.
Stepwise "do X then Y then Z" flows that are task-specific.
Overly long lists; prefer 2–3 clear rules with one compact example.

Example

This is what I prompted the LLM with for generating my guidelines. For the part which it says <insert your prompt here>, I've used the example prompt from the one mentioned above. If you have adjusted or changed that prompt, you should use yours where appropriate.

Based on my following prompt, generate a guideline .github/copilot-instructions.md instructions. The project is a JavaScript webstorm IDE project with a server (NodeJS) and the tests are written with Jest. It uses ESM import style and our Jest version supports .spyOn (without need of using unstable module mock). This guideline should be for copilot to write jest tests. Here is my prompt.

<insert your prompt here>

Result
Here's a screenshot of how that looks like. I am not able to share the output here as it contains code blocks in the instructions too.

Using repository-wide instructions

There are no extra steps in your prompt process that you need to take. GitHub co-pilot would automatically read the instructions.

Limitations

This is a repository wide-instruction, its purpose is more suited for project wide guidance than specific tasks. It might not be suited for one-off instruction or complex tasks that involve multiple steps. If our repository instruction is extremely long due to the specifics of how the test should be written, we would be polluting the global context when we're asking the LLM to work on code that is not related to testing. This is not just costly but it might confuse the LLM, make it more error-prone and less likely to follow the instructions provided. We want our LLM context to be concise and focused.

As an alternative, we can instead create markdown prompt files that can be reused.

Transforming into prompt files

Prompt files are compact, reusable task specifications you store alongside your code so the team can run focused workflows on demand. Their purpose is to separate how something should be done (detailed, runnable steps) from what the project's global conventions are (the repository instructions). Use prompt files for single-purpose jobs you want repeatably executed and reviewed: generate a unit test for a specific module, scaffold a component with the project's patterns, run a structured code review, or produce a standardised README from package.json and repo context. Because prompt files are explicit and executable, they make outputs more predictable, speed up tedious work, and improve consistency when the authoring and usage conventions are enforced via Merge Requests (MRs) and README documentation.

It also presents itself as a sweet spot that does not require Model Context Protocol (MCP). Some organisations might disable MCP from GitHub co-pilot as part of their security policies. This is where prompt files could be able to act as a less dynamic and less powerful version of a MCP service but still perform great.

What / where

For GitHub Copilot, prompt filenames should include the .prompt suffix (e.g., write-jest-tests.prompt.md or generate-readme.prompt.md). Store workspace prompts under .github/prompts/ so other contributors can discover them. User prompts can live in your editor profile, but for team use keep them in the repo.

Prompt files can include a small front-matter block to declare mode, model, or tools (if supported by the client). The body should be a focused task spec: inputs to use, the expected output format, and any constraints.

How to write effective prompt files

A good prompt file reads like a small, self-contained specification that is brief enough for the model to grasp entirely but structured enough to yield relatively consistent results every run.

Keep three constraints in mind: concise, canonical, and scoped.

Concise: each prompt should focus on a single, well-defined task. Avoid long explanations or meta-discussions; the LLM performs best when the intent and output are clearly defined in just a few sentences. Short prompts are easier to debug and maintain.
Canonical: include a clear, single example that demonstrates exactly what the desired output should look like. The example should be representative and complete — for instance, a short Jest test, a scaffolded component, or a generated README snippet. This gives the LLM a pattern to imitate rather than an abstract description.
Scoped: prompts should cover only one workflow or deliverable. Do not combine unrelated tasks (e.g., generating both tests and documentation in one prompt). When the task grows too broad, break it into multiple smaller prompt files that can be run independently.

Include:

The goal or purpose of the task, described in one sentence at the start.
Specific inputs that the LLM should expect, such as module paths, component names, or function signatures.
Output format or constraints for example, "return only the .test.js file content" or "use ESM imports." If you're doing TypeScript, then change to TS.
One canonical example that demonstrates the correct file structure or output.
Optional front-matter to specify the mode (agent), model (gpt-4o or similar), and a short description for clarity.
Clear separation between instructions, inputs, and examples.

Avoid:

Excessive explanation, reasoning, or commentary. The more verbose the prompt, the more likely the LLM will diverge from your intended output.
Combining multiple unrelated tasks into one prompt. Keep each file dedicated to a single purpose.
Ambiguous wording such as "use good practices" without defining what "good" means.
Redundant examples or conflicting conventions within the same prompt file.
Hidden or sensitive data such as secrets, API keys, internal URLs, or credentials. Use placeholders if necessary.

Example

There are many examples available on the GitHub awesome-copilot repository that you can browse through to understand and get a feel of how it works. Thereafter, you can ask the LLM to create a prompt file for you. Here's a prompt to feed the LLM that will produce a ready-to-drop .prompt.md file for generating Jest tests for a single module:

Generate a prompt file suitable for `.github/prompts/write-jest-tests.prompt.md`. 
Output the full prompt file contents only (no commentary). 
The prompt file should target an ESM Node.js project using Jest and must produce a single ready-to-drop `.test.js` file.

Include front-matter with:
- mode: agent
- model: gpt-5
- description: "Generate Jest unit test for a single module (ESM + jest.spyOn)."

In the body, include these labeled sections: Task, Inputs, Constraints, Output, Example output. 
Task: generate one focused Jest test for a specified module and exported function.
Inputs: modulePath, exportedSymbols, testGoal (one-line).
Constraints: use ESM imports, use jest.spyOn() if mocking dependencies, include `afterEach(() => jest.restoreAllMocks())`, keep tests small (<=20 lines).
Output: return only the `.test.js` file content; do not include explanations or extra text.
Example output: provide a minimal working test demonstrating imports, a describe block, afterEach, and one it() block.

Result

Here's a screenshot of how that looks like. I am not able to share the output here as it contains code blocks in the instructions too.

Using prompt files

They only execute when called upon. Where appropriate, in your conversation, you can type /write-jest-tests for it to execute the prompt file.

And here's how the output of that prompt file command should look like:

Limitations

Prompt files are powerful but not guarantees. They must be explicitly invoked as they won't automatically change Copilot's real-time suggestions unless a user runs them. The editor support and behaviors are still evolving between IDEs, so a prompt that works in one client may behave slightly differently in another. As of writing this article, this feature is still in public preview and is still evolving and undergoing changes. Because they are executable instructions, prompt files also require maintenance: naming, discoverability, example fidelity, and expected output formats must be kept in sync with code changes, and they should be reviewed via Merge Requests (MR) like other behavior-changing files. Finally, because LLM outputs can vary, assume a validation step: run generated artifacts in a sandbox, add simple tests or linting rules, and keep prompts intentionally small and single-purpose to reduce unpredictable results.

Quick Summary

Aspect	Repository instructions	Prompt files
Description	Persistent, repository-wide configuration stored at `.github/copilot-instructions.md`. Copilot automatically includes it when generating suggestions.	Smaller reusable instructions stored as `.prompt.md` files. Each file can be manually triggered or referenced when needed.
Pro	Automatically applied for anyone working in the repository, ensuring consistent behavior.	Designed for specific, repeatable tasks such as scaffolding, testing, or documentation generation.
Pro	Ideal for defining project-wide conventions, language style, architecture rules, or testing frameworks.	Can specify mode, model, and tools in front-matter, making prompts flexible and specialized.
Pro	Helps onboard new contributors by embedding general guidance directly into Copilot's context.	Encourages modularity: different teams or features can maintain their own task-focused prompts.
Con	Less effective for multi-step or one-off operations that don’t apply to all areas of the project.	It is not automatically applied. Someone has to explicitly run or invoke the prompt.
Con	Large or overly detailed instructions can dilute Copilot's focus and reduce reliability.	Feature support is still evolving across IDEs; may behave differently between VS Code and WebStorm.
Limitation	Scope is repository-wide. Overly specific content can pollute the context for unrelated tasks.	Scope is local to each prompt; doesn't persist unless called.
Limitation	Usually only one file is supported; formatting rules are strict and extra whitespace can affect parsing.	Requires consistent naming (`.prompt.md`) and manual organising to remain discoverable.
When to use	When you want persistent, general guidance that shapes all Copilot suggestions be it language, architecture, or testing frameworks.	When you need focused, repeatable workflows that can be run on demand such as code reviews, test generation, or documentation.
Example	`.github/copilot-instructions.md` describes how Jest tests should be structured across the entire repo.	`.github/prompts/write-jest-tests.prompt.md` contains detailed steps and examples for generating individual test cases.

Combined approach

We can combine a hybrid approach of using both repository-wide instructions and prompt files. This can greatly improve your overall prompt experience as the results would be more tuned to your setup and tasks. It decreases the amount of file scanning and tokens required by the LLM as the repository-wide instructions already provides necessary project information. It also provides a more targeted result through task specific prompt files.

What / how

Keep repository instructions broad: language, architecture, high-level testing rules, and one canonical example.
Move detailed steps, templates, and per-task examples into prompt files that are invoked when needed.
Exclude detailed test structure from repo instructions and put those specifics in prompt files like write-jest-tests.prompt.md.

This reduces context noise while giving engineers actionable prompts for specific tasks.

Example

Let's prompt our LLM to generate a new set of repository-wide guidelines specific for our hybrid approach. This new repository-wide guidelines need to accommodate for the existence of prompt files.

Generate a guideline file .github/copilot-instructions.md instructions. Take note that there will eventually be GitHub co-pilot prompt files that cover their specific areas such as testing. This means that you should exclude specific or detailed information or examples about how exactly such areas should be implemented. However, you are free to provide broad general guidelines on these areas. The project is a JavaScript webstorm IDE project with a server (NodeJS) and the tests are written with Jest. It uses ESM import style and our Jest version supports .spyOn (without need of using unstable module mock).

As for the prompt file, we can keep it as it is because it is already scoped to its specific task.

Result

Here's a screenshot of how that looks like. I am not able to share the output here as it contains code blocks in the instructions too.

Limitations

Even with the combined effectiveness of repository-wide instructions and task specific prompts, it still fall short in certain areas. It is not as dynamic as MCP and thus, would not be able to tightly integrate with other areas such as your Continuous Integration (CI) setup or other tools that exists elsewhere. Depending on your complexity of use-case, MCP might be more appropriate. As these are static Markdown file instructions, there is also a maintenance cost to consider on the long run where you would need to regenerate the repository-wide instructions or task specific prompts as your software and its dependencies evolves.

Limitations and Tradeoffs

Requires understanding of how to write unit tests

You may not need tool specific knowledge for the basics of writing Jest unit tests using LLM. However, it does test your knowledge and understanding of how to structure and write unit tests, including concepts like spying, mocking and when to effectively use them.

May require debugging

For our basic scenario, asking the LLM to debug and fix the issues mentioned would be relatively easy. But sometimes, it could be completely off and even starting new conversation with a different prompt would not work. This might mean that it is not within the LLM's ability to fix the problem and thus, would require manual intervention. This means that you'll still need to proficient in debugging and understanding what is wrong.

Simple workflows

The examples given are by no means representative of real world applications where there are lots of moving parts, resource limitations imposed and the bigger scale of things.

End-to-end tests covered in next article

As this article was extremely long, I have decided to break it down to 2 parts for testing. On the next article for this series, we will look further into how we can use Playwright and LLM assistance to write our end-to-end (e2e) tests for us. So be sure to stay-tuned!

Source code repository

The code repository for this article will be made available on GitHub after the last article in the series is published.

Conclusion

We've delved into the depths of testing using Jest and LLM assistance. Through this process, we have learnt:

When to use LLM and when not to use LLM for assisting in writing tests
How to document important test specifications for the LLM
Specifying certain code-pieces and structure for the LLM to follow
Iterative approach of prompting the LLM
How to debug when the LLM result fails
Evaluated pitfalls of LLM and how to intervene when its fixes fail too
Writing reusable prompt files

Based on your experience and knowledge, are there anything that you think should be added or improved upon? Leave your suggestions or comments below! Or if you have any questions, please feel free to ask. Collaboration is how our community grows. Happy coding!

Building real-time chat with no external dependencies

Huiren Woo — Wed, 09 Jul 2025 01:59:26 +0000

Introduction

There are many ways to build a real-time chat application. Before websockets was a commonplace, long-polling was a strategy deployed by various companies, including Facebook / Meta. With the rise of websockets, many developers went this route instead of using long-polling methods. However, depending on circumstances or scenarios, websockets may not be what you're looking for. In this article, we will explore how to build a simple chat application that doesn't use any third party libraries or websockets.

This application will use Server-Sent Events (SSE) to push messages from the server to the client in real time. Whilst it sends messages from the client to the server using a simple HTTP POST request.

Benefits of SSE over websockets

Minimal setup

SSE requires minimal setup on both the server and client sides whereas websockets require a more complex handshake process with an upgrade to the protocol. On the devops side, this means that websockets require additional plumbing. In a multi-instance setup you often need session-affinity or a dedicated WebSocket gateway cluster, so messages go to the same server that holds that socket. SSE is a read-only protocol, so it can be load-balanced without worrying about two way-routing.

Simplicity

SSE is simpler to implement than websockets. It uses a simple HTTP connection and does not require any additional libraries or protocols. Typically in websockets, you might need an external library like socket.io to handle it on both the client and server sides.

Downsides of SSE over websockets

No native binary support

In order to send binary data through Server Sent Events (SSE), you need to encode it as a string (e.g. base64) which increases the size of the payload. Whereas websockets can send binary frames natively without any encoding.

No built-in ping/pong heartbeat mechanism

SSE does not have a built-in ping/pong mechanism to keep the connection alive. If there are no frequent messages, some firewalls or proxies may close the connection after a period of inactivity. Whereas websockets have a built-in heartbeat mechanism that allows the server and client to keep the connection alive. You can overcome this by implementing a heartbeat mechanism on the server.

Designing the simple non-scalable chat application

Designing the message structure

Let's keep it simple and have only a few fields in our message. We will have an ID, a timestamp, an author, and the content of the message. For brevity, we will not implement any authentication or authorization, so anyone can send messages.

The message will be a simple JSON object with the following structure:

{
  "id": "unique-message-id",
  "timestamp": "2023-10-01T12:00:00Z",
  "author": "author-name",
  "content": "message-content"
}

Initial client content

The client will consist of a simple HTML page with a form to submit messages and a div to display the messages. We will use the Fetch API to send messages to the server. The following is the HTML contents without the JavaScript code. The endpoints subsections will contain the respective client JavaScript code.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Chat</title>
</head>
<body>
<div id="chat-messages"></div>
<form id="chat-form" action="/send-message" method="POST">
    <input type="text" name="author" placeholder="Username" required/>
    <input type="text" name="content" placeholder="Type your message here..." required/>
    <button type="submit">Send</button>
</form>
<script src="chat-app.js"></script>
</body>
</html>

Server serving HTML content

Next, we will create a simple server that serves the HTML content to the client. It uses directory on the public folder to serve static files like HTML and JavaScript files. We will use Node.js's built-in http and fs modules to create the server.

const __dirname = path.dirname(new URL(import.meta.url).pathname);
const PUBLIC_DIR = path.join(__dirname, 'public');

const MIME_TYPES = {
    '.html': 'text/html; charset=UTF-8',
    '.js': 'application/javascript; charset=UTF-8',
};

// ... other code
if (req.method === "GET") {
    const safeSuffix = path.normalize(decodeURI(req.url)).replace(/^(\.\.[\/\\])+/, '');
    let filePath = path.join(PUBLIC_DIR, safeSuffix);

    // Check if the file exists
    try {
        const stats = fs.statSync(filePath);
        if (stats.isFile()) {
            const ext = path.extname(filePath).toLowerCase();
            const contentType = MIME_TYPES[ext] || 'application/octet-stream';
            res.writeHead(200, {'Content-Type': contentType});
            res.end(fs.readFileSync(filePath));
            return;
        }
    } catch (err) {
        // File does not exist or is not accessible
    }
}

Server message endpoints

We will create two endpoints on the server to handle messages.

GET endpoint

Allows new clients to connect and receive messages that will be broadcasted. This makes use of Server-Sent Events on the server side. Whenever a client connects to this endpoint, it will be added to a list of connected clients. This list of connected clients will be used later.

if (req.url === '/server-sent-events') {
    res.writeHead(200, {
        'Content-Type': 'text/event-stream',
        'Cache-Control': 'no-cache',
        'Connection': 'keep-alive'
    });
    const clientsConnectionsClone = [...clientsConnections];
    clientsConnectionsClone.push(res);
    clientsConnections = [...clientsConnectionsClone];

    res.on('close', () => {
        const clientsConnectionsClone = [...clientsConnections];
        const index = clientsConnectionsClone.indexOf(res);
        if (index !== -1) {
            clientsConnectionsClone.splice(index, 1);
            clientsConnections = [...clientsConnectionsClone];
            console.log('Client disconnected, removed from connections list');
        }
    });

    return;
}

Interacting with GET endpoint

On the client side, we will use the EventSource API to connect to the server and listen for messages. Whenever a message comes through, we will parse it and add it to the chat messages container in the HTML.

const source = new EventSource('/server-sent-events');
source.addEventListener('message', (e) => {
    console.log("Received message from server sent event:", e.data);
    try {
        const parsedData = JSON.parse(e.data);
        addChatMessage(parsedData);
    } catch (e) {
        console.log('Error parsing JSON:', e);
    }
});
source.addEventListener('open', (e) => {
    console.log('connected');
});
source.addEventListener('error', (e) => {
    if (e.eventPhase === EventSource.CLOSED) {
        source.close();
    }
    if (e.target.readyState === EventSource.CLOSED) {
        console.log('closed');
    }
    if (e.target.readyState === EventSource.CONNECTING) {
        console.log('connecting');
    }
});

// ... other client code

function addChatMessage(chatMessage) {
    const chatContainer = document.getElementById('chat-messages');
    const messageElement = document.createElement('div');
    messageElement.innerHTML = `<strong>${chatMessage.author}</strong>: ${chatMessage.content} <span class="timestamp">${new Date(chatMessage.timestamp).toLocaleTimeString()}</span>`;
    chatContainer.appendChild(messageElement);
}

POST endpoint

Allows connected clients to send messages to the server. Whenever the server receives a message, it will parse it and add additional information before broadcasting the message to all connected clients.

if (req.method === "POST") {
    if (req.url === '/send-message') {
        let body = '';
        req.on('data', chunk => {
            body += chunk.toString();
        });
        req.on('end', () => {
            try {
                const jsonData = JSON.parse(body);

                // Validate required fields
                if (!jsonData.author || !jsonData.content) {
                    res.writeHead(400, {'Content-Type': 'application/json'});
                    res.end(JSON.stringify({
                        status: 'error',
                        message: 'Both author and content fields are required'
                    }));
                    return;
                }

                // Create message object with validated fields
                const message = {
                    id: crypto.randomUUID().toString(),
                    author: jsonData.author,
                    content: jsonData.content,
                    timestamp: new Date().toISOString()
                };

                broadcastMessage(message);
                res.writeHead(201, {'Content-Type': 'application/json'});
                res.end(JSON.stringify({status: 'Message sent'}));
            } catch (error) {
                // Handle JSON parsing errors
                res.writeHead(400, {'Content-Type': 'application/json'});
                res.end(JSON.stringify({status: 'error', message: 'Invalid JSON format'}));
            }
        });
        return;
    }
}

function broadcastMessage(messageJsonObject) {
    clientsConnections.forEach(client => {
        client.write(`data: ${JSON.stringify(messageJsonObject)}\n\n`);
    });
}

How it looks like

Chatting with another person works and the message is instant!

No message history sent to newly connected clients due to design limitations.

Making it scalable

The application we have built so far works well for a single instance. However, it is not cloud native and does not scale. This is because the server stores messages in memory, and when the server restarts, all messages are lost. Additionally, if we want to run multiple instances of the server, they will not be able to share messages with each other.

The business benefit of a scalable application is that it can handle more traffic and more users easily, scaling up or down conveniently and when needed.

There are several ways to make this application horizontally scalable. For this article, we will go with the approach of using a file to store the messages. In a more complex setup, you would want to consider using a more reliable datastore like MySQL or Redis. Storing the messages allows enables the following:

Messages are persistent and can be retrieved even if the server restarts
Multiple instances of the server can read from the same file, allowing for horizontal scaling
Messages can be served to new clients that connect after the server has started

Each server instance will store what messages has been broadcasted. We will only need to store the ID of the last message broadcasted.

Server message storage

We will write a file-based database to store the messages. There are some things we want to make sure:

The file is readable and writable by the server process
When multiple instances of the server are running, they can read without conflicts
When multiple instances of the server are running, the file is not written to at the same time

I decided to use a write-lock file to ensure that only one instance of the server can write to the file at a time. The messages will also be stored in a JSON format to make it easy to read and write. To prevent an infinite wait, the lockfile will also store a timestamp of the last write attempt. If the lockfile is older than a certain threshold, the server will assume that we can write to the file again. The flaw and limitation of this approach is that if there are many messages coming in, the server instances might be stuck in a queue as it uses a greedy approach and there is no order to the queue. For the sake of brevity, we will not implement a more complex queue system.

import fs from 'node:fs/promises';
import path from 'node:path';
import {fileURLToPath} from 'node:url';

const __dirname = path.dirname(fileURLToPath(import.meta.url));
const DB_DIR = path.join(__dirname, 'db');
const DB_FILE = path.join(DB_DIR, 'messages.json');
const LOCK_FILE = path.join(DB_DIR, 'messages.lock');
const LOCK_TIMEOUT = 5000; // 5 seconds before considering a lock stale

// Ensure database directory exists
async function ensureDbDir() {
    try {
        await fs.mkdir(DB_DIR, {recursive: true});
    } catch (err) {
        if (err.code !== 'EEXIST') {
            throw err;
        }
    }
}

// Check if database is currently locked
async function isLocked() {
    try {
        await fs.access(LOCK_FILE);

        const lockData = await fs.readFile(LOCK_FILE, 'utf8');
        const lockTime = parseInt(lockData, 10);

        // Check for stale lock
        if (Date.now() - lockTime > LOCK_TIMEOUT) {
            console.log('Found stale lock, removing it');
            await fs.unlink(LOCK_FILE);
            return false;
        }
        return true;
    } catch (err) {
        if (err.code === 'ENOENT') {
            // Lock file doesn't exist
            return false;
        }
        console.error('Lock check error:', err);
        return false;
    }
}

// Create a lock with current timestamp
async function acquireLock() {
    await fs.writeFile(LOCK_FILE, Date.now().toString());
}

// Release the lock
async function releaseLock() {
    try {
        await fs.access(LOCK_FILE);
        await fs.unlink(LOCK_FILE);
    } catch (err) {
        if (err.code !== 'ENOENT') {
            console.error('Error releasing lock:', err);
        }
    }
}

// Read all messages from database
async function readMessages() {
    try {
        await ensureDbDir();
        try {
            await fs.access(DB_FILE);

            const data = await fs.readFile(DB_FILE, 'utf8');
            return JSON.parse(data);
        } catch (err) {
            if (err.code === 'ENOENT') {
                return [];
            }
        }
    } catch (err) {
        console.error('Error reading messages:', err);
        return [];
    }
}

// Write messages to database with lock
async function writeMessages(messages) {
    await ensureDbDir();

    // Wait until lock is available
    let acquired = false;
    while (!acquired) {
        if (await isLocked()) {
            console.log('Database is locked, waiting...');
            await new Promise(resolve => setTimeout(resolve, 100));
        } else {
            acquired = true;
        }
    }

    try {
        await acquireLock();
        await fs.writeFile(DB_FILE, JSON.stringify(messages, null, 2));
    } finally {
        await releaseLock();
    }
}

// Add new message to database
async function saveMessage(message) {
    const messages = await readMessages();
    messages.push(message);
    await writeMessages(messages);
    return message;
}

// Get messages newer than the specified ID
async function getMessagesAfter(lastId) {
    const messages = await readMessages();
    if (lastId == null) {
        return messages;
    }

    const lastIndex = messages.findIndex(msg => msg.id === lastId);
    if (lastIndex === -1) {
        return messages;
    }

    return messages.slice(lastIndex + 1);
}

export default {
    saveMessage,
    getMessagesAfter,
    readMessages,
    dbFilePath: DB_FILE,
    lockFilePath: LOCK_FILE,
};

Rewriting the server messaging

The server will now need to read information from the database, and as well as messages sent to its endpoint. We will poll the database file every 1 second for new messages and broadcast them to the connected clients. We can know where was the last broadcasted message by storing the ID of the last broadcasted message. In a more complex setup with Redis, you would use a pub/sub mechanism to notify all instances of new messages. As our file-based database is limited, we can only use polling to check for new messages and the downside would be the latency of the message updates. Increasing the polling interval would reduce the load on the server, but increase the latency of message delivery. Decreasing the polling interval would increase the load on the server, but decrease the latency of message delivery.

Modify the server message sending endpoint to save the message to the database and broadcast it to all connected clients.

// ... other code
const message = {
    id: crypto.randomUUID().toString(),
    author: jsonData.author,
    content: jsonData.content,
    timestamp: new Date().toISOString()
};

await db.saveMessage(message);
broadcastMessage(message);
res.writeHead(201, {'Content-Type': 'application/json'});
res.end(JSON.stringify({status: 'Message sent'}));
// ... other code

// ... other code
let lastBroadcastedId = null;

// ... other code

function broadcastMessage(messageJsonObject) {
    lastBroadcastedId = messageJsonObject.id;
    clientsConnections.forEach(client => {
        client.write(`data: ${JSON.stringify(messageJsonObject)}\n\n`);
    });
}

async function pollNewMessages() {
    console.log('polling for new messages...');
    try {
        const newMessages = await db.getMessagesAfter(lastBroadcastedId);
        if (newMessages.length > 0) {
            newMessages.forEach(message => {
                broadcastMessage(message);
            });
            lastBroadcastedId = newMessages[newMessages.length - 1].id;
        }
    } catch (err) {
        console.error('Error polling for messages:', err);
    }

    // Poll again after delay
    setTimeout(pollNewMessages, 1000);
}

// ... other code

server.listen(portNumber, async () => {
    console.log('Listening on http://localhost:' + portNumber);

    // Initialize lastBroadcastedId
    const messages = await db.readMessages();
    if (messages.length > 0) {
        lastBroadcastedId = messages[messages.length - 1].id;
    }

    // Start polling
    await pollNewMessages();
});

Upon connecting, the client will receive all messages that have been sent so far. This is done by reading all messages from the database and sending them to the client.

const clientsConnectionsClone = [...clientsConnections];
clientsConnectionsClone.push(res);
clientsConnections = [...clientsConnectionsClone];

// Read all messages from the database and send them to the newly connected client
db.readMessages().then(messages => {
    messages.forEach(message => {
        res.write(`data: ${JSON.stringify(message)}\n\n`);
    });
}).catch(err => {
    console.error('Error sending initial messages to client:', err);
});

How it looks like now

Now there's message history sent to the newly connected client. However, due to the 1 second polling, you will notice there's a slight delay on receiving the message on the other server instance.

Source code repository

The code repository for this article will be made available on GitHub after the last article in the series is published.

Conclusion

We have learnt how to build a simple chat application using Server-Sent Events and HTTP POST requests without any third-party dependencies. Through this process, we have learnt:

How to use Server-Sent Events to push messages from the server to the client in real time
How to create a simple server that serves HTML content and handles messages
Business and technical benefits of making cloud native applications
How to handle multiple instances of the server and ensure that messages are not lost
How to make our own file-based database with write-lock to store messages
How to poll the database for new messages and broadcast them to connected clients

A Practical Guide to Testing Custom React Routers

Huiren Woo — Wed, 18 Jun 2025 07:09:41 +0000

Introduction

When I first shared my article on building a custom React router, I intentionally kept things simple: we manually tested our implementation and provided video or GIF footage as evidence that the router worked as expected. Automated testing wasn't a priority in that initial build; our goal was to focus on building the core functionality, learning, and iterating.

So why am I taking the time to write a follow-up article about testing the router that we previously built? It's a good question and one that touches on an important aspect of modern development practices.

Why Automated Testing Matters

In smaller, personal projects, it's easy to lean on manual testing or simple visual inspections to confirm that things work. However, in a larger organisation, or even in a growing codebase, manual testing alone quickly becomes insufficient. When you're working in a fast-paced environment with many contributors and moving parts, even a small change to a fundamental component like RouterLink can have ripple effects throughout the application. Without a solid suite of tests, you might find yourself second-guessing every change or, worse, introducing regressions that only surface much later.

Automated tests can significantly reduce the scope of uncertainty around these kinds of changes. With well-structured tests in place, you can make adjustments to your router and know that if the base tests pass, the core functionality remains intact. And if a downstream component fails, you can quickly identify the scope of the breakage and address it without having to manually click through the entire application to find the problem.

Beyond practical considerations, writing tests can also be an enjoyable mental exercise. It challenges you to think critically about edge cases, lifecycle management, and user interactions, especially when dealing with hooks and lazy-loaded components. In this article, we'll explore how to test the router hook, the RouterLink component, and the RouterRoot component in our custom router setup. Along the way, we'll discuss best practices and share patterns that can help you build confidence in your code while enabling faster, more reliable development.

Let's dive in!

Testing Environment Setup

We'll continue from our Vite TypeScript project setup. I've chose to use vitest as our main testing tool and have it complemented by Testing Library. This is mainly due to the ease of integration provided by vitest with Vite. jest could still work but with a little more configuration. In any case, we would still need Testing Library as we'll be using renderHook and render, both of which don't seem to be available on vitest.

To set up the environment, we'll just need a few more tools:

npm install -D vitest @testing-library/react @testing-library/dom @types/react @types/react-dom jsdom

We'll also need to configure vite.config.ts file as well

/// <reference types="vitest/config" />
import {defineConfig} from 'vite'
import react from '@vitejs/plugin-react'

// https://vite.dev/config/
export default defineConfig({
  plugins: [react()],
  test: {
    environment: 'jsdom', // or 'jsdom', 'node'
  },
})

Testing the Router Hook

The router hook is the core piece we need to ensure works correctly. The tests for this are the most important, so we want to be thorough but concise. There are two main functions we want to test, and aside from unsubscribing from the store, there isn't much additional cleanup to worry about since we're not using any event listeners here. We just need to make sure there are no unintended side effects when another hook is unmounted.

First, we'll do a basic sanity check to ensure that the navigate function updates the path correctly. Since we intentionally added a setTimeout in our router hook, we'll need to use fake timers in our tests.

...
describe('useRouterHook', () => {
    beforeEach(() => {
        vi.useFakeTimers();
    });

    afterEach(() => {
        vi.useRealTimers();
    });

    test('returns the current path', () => {
        const {result} = renderHook(() => useRouterHook());
        expect(result.current.data.path).toBe('/');
    });

    test('updates when navigate() is called', () => {
        const {result} = renderHook(() => useRouterHook());
        act(() => {
            result.current.navigate('/about');
            vi.runAllTimers();
        });
        expect(result.current.data.path).toBe('/about');
    });
});

Next, we'll consider what happens if multiple components on the same page create their own instance of the hook. Would the navigate function correctly update the state in both components?

...
    test('updates all mounted hook instances', () => {
        const hookA = renderHook(() => useRouterHook());
        const hookB = renderHook(() => useRouterHook());

        act(() => {
            hookB.result.current.navigate('/about');
            vi.runAllTimers();
        });
        expect(hookA.result.current.data.path).toBe('/about');
        expect(hookB.result.current.data.path).toBe('/about');
    });
...

Finally, we'll check that our navigate function and state continue to work even after one of the hooks has been unmounted.

...
    test('unsubscribes cleanly upon unmount', () => {
        const hookA = renderHook(() => useRouterHook());
        const hookB = renderHook(() => useRouterHook());

        // Unmount hookB and navigate again
        hookB.unmount();
        act(() => {
            hookA.result.current.navigate('/about');
            vi.runAllTimers();
        });
        expect(hookA.result.current.data.path).toBe('/about');
    });
...

You might notice that some of these test cases weren't covered in our manual testing. Some things are easier to test manually, while others, like ensuring proper cleanup on unmount, are easier to catch through automated testing.

Testing the Router Link Component

The RouterLink component is a very simple piece of the puzzle, but it also serves as our entry point to integration testing. It ensures that components can use the router hook to navigate programmatically.

...
const TEST_ROUTER_LINK_ABOUT_PAGE_TEST_ID = 'TEST_ROUTER_LINK_ABOUT_PAGE_TEST_ID';

describe('router-link', () => {
    beforeEach(() => {
        vi.useFakeTimers();
    });

    afterEach(() => {
        vi.useRealTimers();
    });

    test('renders router link with clickable navigation', async () => {
        const {result} = renderHook(() => useRouterHook());
        render(<RouterLink data-testid={TEST_ROUTER_LINK_ABOUT_PAGE_TEST_ID} to={'/about'}>About Page</RouterLink>);
        expect(result.current.data.path).toBe('/');
        const routerLinkAboutPage = screen.getByTestId(TEST_ROUTER_LINK_ABOUT_PAGE_TEST_ID);

        await act(async () => {
            fireEvent.click(routerLinkAboutPage);
            vi.runAllTimers();
        });
        expect(result.current.data.path).toBe('/about');
    });
});

Testing the Router Root Component

The RouterRoot component has several important responsibilities:

Listening to the router state provided by the hook and reacting to changes
Listening to the browser's popstate event and responding based on the current pathname
Rendering the appropriate child component
Displaying a "loading" state while the new component is being loaded

We don't need to test scenarios where a route doesn't exist because, by design, our router simply returns null instead of displaying a 404 message. Because of the router's design, we can also assume there will only ever be one RouterRoot, which helps reduce the scope of our tests.

We'll start by writing a test that checks that the router loads without throwing an error or displaying a loading message when there are no routes defined. We'll also need to make some changes to router root to add the test ID.

export const CHILD_PAGE_CONTENT_ID = 'CHILD_PAGE_CONTENT_ID';
export const CHILD_PAGE_CONTENT_DATA = 'some content data here';
export const CHILD_SECOND_PAGE_CONTENT_ID = 'CHILD_SECOND_PAGE_CONTENT_ID';
export const CHILD_SECOND_PAGE_CONTENT_DATA = 'some other stuff here';
export const LOADING_INFO_COMPONENT_ID = 'LOADING_INFO_COMPONENT_ID';

...
    return (
        <div>
            {isPending ? <div data-testid={LOADING_INFO_COMPONENT_ID}>Loading...</div> : null}
            {readyElement}
        </div>
    );
...

...
    test('renders with no routes', async () => {
        await act(async () => {
            render(<RouterRoot routes={{}}/>);
        });

        const element = screen.queryByTestId(LOADING_INFO_COMPONENT_ID);
        expect(element).toBeNull();
    });

Next, we'll check that the loading text is displayed when a route component is loading.

...
    test('renders loading text when initialising', async () => {
        await act(async () => {
            render(<RouterRoot routes={testRoutes}/>);
        });

        const element = screen.queryByTestId(LOADING_INFO_COMPONENT_ID);
        expect(element).toBeDefined();
    });

Then, we'll confirm that the correct content renders once the component has loaded.

...
    test('renders with routes with content', async () => {
        await act(async () => {
            render(<RouterRoot routes={testRoutes}/>);
        });

        const element = await screen.findByTestId(CHILD_PAGE_CONTENT_ID);
        expect(element).toBeDefined();
        expect(element.innerHTML).toBe(CHILD_PAGE_CONTENT_DATA);
    });

Finally, we'll verify that content updates properly when navigating to a new page.

...
    test('renders updated content with route changes', async () => {
        const {result} = renderHook(() => useRouterHook());
        await act(async () => {
            render(<RouterRoot routes={testRoutes}/>);
        });

        vi.useFakeTimers();
        await act(async () => {
            result.current.navigate('/other-page');
            vi.runAllTimers();
        });
        vi.useRealTimers();

        const element = await screen.findByTestId(CHILD_SECOND_PAGE_CONTENT_ID);
        expect(element).toBeDefined();
        expect(element.innerHTML).toBe(CHILD_SECOND_PAGE_CONTENT_DATA);
    });

We can take things a step further by checking whether certain state cleanups occur properly when the component is unmounted. This helps demonstrate that the component is pure (though, of course, tests alone can't guarantee that). This might involve mocking certain functions to observe event listener registration and cleanup.

We'll begin by ensuring that event listeners are correctly added when the component mounts and removed when it unmounts.

...
describe('router-root with event spying', () => {
    let addSpy: MockInstance;
    let removeSpy: MockInstance;
    let originalAdd: typeof window.addEventListener;
    let originalRemove: typeof window.removeEventListener;
    let capturedHandler: EventListenerOrEventListenerObject | null = null;

    beforeEach(() => {
        originalAdd = window.addEventListener.bind(window);
        originalRemove = window.removeEventListener.bind(window);
        addSpy = vi.spyOn(window, 'addEventListener')
            .mockImplementation(
                (
                    type,
                    listener,
                    options
                ) => {
                    if (type === 'popstate') {
                        capturedHandler = listener;
                    }
                    originalAdd(type, listener, options);
                });
        removeSpy = vi.spyOn(window, 'removeEventListener')
            .mockImplementation(
                (
                    type,
                    listener,
                    options
                ) => {
                    originalRemove(type, listener, options);
                }
            );
        vi.useFakeTimers();
    });

    afterEach(() => {
        addSpy.mockRestore();
        removeSpy.mockRestore();
        capturedHandler = null;
        vi.useRealTimers();
    });

    test('registers and then removes the popstate listener on unmount', async () => {
        let componentRenderResult: RenderResult;
        await act(async () => {
            componentRenderResult = render(
                <RouterRoot routes={{}}/>
            );
        });

        expect(addSpy).toHaveBeenCalledWith('popstate', capturedHandler);
        await act(async () => {
            componentRenderResult.unmount();
        });
        expect(removeSpy).toHaveBeenCalledWith('popstate', capturedHandler);
    });
});

Then, we'll check that the router store state does not continue to update after the RouterRoot component has been unmounted.

...
    test('should not be listening after unmount', async () => {
        let componentRenderResult: RenderResult;
        await act(async () => {
            componentRenderResult = render(
                <RouterRoot routes={{}}/>
            );
        });
        const {result} = renderHook(() => useRouterHook());

        expect(result.current.data.path).toBe('/');
        await act(async () => {
            window.history.pushState(null, '', '/about');
            fireEvent.popState(window, {});
            vi.runAllTimers();
        });
        expect(result.current.data.path).toBe('/about');
        await act(async () => {
            componentRenderResult.unmount();
        });
        await act(async () => {
            window.history.pushState(null, '', '/');
            fireEvent.popState(window, {});
            vi.runAllTimers();
        });
        expect(result.current.data.path).toBe('/about');
    });
...

Limitations and Tradeoffs

No End-to-End Testing

We did not add end-to-end tests that simulate user flows spanning multiple components and routes. For this relatively straightforward router, E2E testing may feel like overkill as there are no multi-layered workflows (like checkout or search flows) that require it. However, in more complex applications or user journeys, E2E tests can catch integration issues that unit and integration tests might miss. There are also cases in which things are easier to test with E2E than to use integration or unit tests. For example, if there are many components with sub-components, you could use an E2E to cover most of these components' use cases rather than writing many unit tests to cover them individually.

Reliance on Mocks

Using mocks helps isolate our components and keeps tests fast, but it also carries its own trade-offs. When we mock parts of the router (for example, event listeners), there’s a chance that real-world behavior is obscured. Furthermore, if we change the underlying implementation, such as removing or changing how event listeners are registered, we'll need to update our mocks accordingly. Although we mitigate some of this by calling through to the original functions in our tests, there's still extra maintenance whenever the implementation changes.

No Performance Testing

Our test suite focuses exclusively on correctness and does not include performance profiling. In larger applications, especially those with many routes or heavy client-side navigation, performance can become a bottleneck. Adding benchmarks or stress tests could reveal areas to optimize (for example, lazy-loading strategies or avoiding unnecessary re-renders). However, most optimisation cases should already have been covered by the new React compiler. The main point of these tests would then be for catching potential performance regressions.

Conclusion

I hope that by walking through my thought process and these test cases, you've gained some insight into why and how to test a custom router effectively. Testing isn't just about preventing bugs, it's about building confidence in your code and enabling faster, safer iteration. The full code repository is available here: https://github.com/GIANTCRAB/your-own-react-router.

Build Your Own Lightweight React Router Using React 18 Features

Huiren Woo — Tue, 10 Jun 2025 04:00:35 +0000

Why Build Your Own Router in 2025?

As a Software Consultant, I am always excited to explore how emerging React features can help us build more intuitive, performant applications. Rather than competing with established routing libraries, this article serves as a practical guide to demonstrate some of React 18's most important features, such as useSyncExternalStore, useTransition, and the History API, through the process of creating a basic router. My intention is to share knowledge in a way that is approachable and useful, so you can gain confidence working with these hooks and patterns. By the end of this walkthrough, you will have a lightweight router that supports lazy loading and takes full advantage of React's concurrency capabilities.

Setting Up the Router State System

A simple way to hold routing state is to use useState. It works, but when you need to express more complex state transitions, it quickly becomes limiting. A better approach is to use useReducer, which allows you to describe state changes in clear, declarative actions.

// router-store-reducer.tsx
import {useCallback, useEffect, useMemo, useReducer} from "react";

// To enable type erasure, enum is intentionally not used
type ActionType = 'POPSTATE' | 'NAVIGATE';
type Action = { type: ActionType; path: string };

type RouterStoreStateType = {
    path: string
};

function routerStoreReducer(state: RouterStoreStateType, action: Action): RouterStoreStateType {
    switch (action.type) {
        case 'POPSTATE':
        case 'NAVIGATE':
            return {path: action.path};
        default:
            return state;
    }
}

export function ExampleApp() {
    const [routerState, dispatch] = useReducer(routerStoreReducer, {path: window.location.pathname});

    useEffect(() => {
        const onPop = () => dispatch({type: 'POPSTATE', path: window.location.pathname});
        window.addEventListener('popstate', onPop);
        return () => window.removeEventListener('popstate', onPop);
    }, []);

    const navigate = useCallback((to: string) => {
        window.history.pushState({}, '', to);
        dispatch({type: 'NAVIGATE', path: to});
    }, []);

    const Component = useMemo(() => routerState.path === '/about' ? AboutPage : HomePage, [routerState.path]);

    return (
        <>
            <nav>
                <button onClick={() => navigate('/')}>Home</button>
                <button onClick={() => navigate('/about')}>About</button>
            </nav>
            <Component/>
        </>
    );
}

function HomePage() {
    return <div>Home</div>;
}

function AboutPage() {
    return <div>About</div>;
}

With a reducer in place, you have a clear foundation. However, if you want nested child components, such as individual page components, to respond to router state changes, you will end up passing props through multiple levels of the component tree (prop drilling).

...
export function ExampleAppProp() {
    const [routerState, dispatch] = useReducer(routerStoreReducer, {path: window.location.pathname});

    useEffect(() => {
        const onPop = () => dispatch({type: 'POPSTATE', path: window.location.pathname});
        window.addEventListener('popstate', onPop);
        return () => window.removeEventListener('popstate', onPop);
    }, []);

    const navigate = useCallback((to: string) => {
        window.history.pushState({}, '', to);
        dispatch({type: 'NAVIGATE', path: to});
    }, []);

    const componentWithProp = useMemo(() => {
        if (routerState.path === '/about') {
            return <AboutPage routerState={routerState}/>;
        }
        if (routerState.path === '/') {
            return <HomePage routerState={routerState}/>;
        }
        return null;
    }, [routerState]);

    return (
        <>
            <nav>
                <button onClick={() => navigate('/')}>Home</button>
                <button onClick={() => navigate('/about')}>About</button>
            </nav>
            {componentWithProp}
        </>
    );
}

type HomePagePropsType = {
    routerState: RouterStoreStateType
}

function HomePage({routerState}: HomePagePropsType) {
    return <>
        <div>Home</div>
        <SomeInnerHomePageComponent routerState={routerState}/>
    </>;
}

type SomeInnerHomePageComponentPropsType = {
    routerState: RouterStoreStateType
}

function SomeInnerHomePageComponent({routerState}: SomeInnerHomePageComponentPropsType) {
    return <div>Some inner component {routerState.path}</div>;
}

type AboutPagePropsType = {
    routerState: RouterStoreStateType
}

function AboutPage({routerState}: AboutPagePropsType) {
    return <div>About {routerState.path}  </div>;
}

Prop drilling can become awkward as your component hierarchy grows. A common solution is to introduce a ContextProvider at the top level of your application:

const RouterContext = createContext<RouterContextType>({
    path: window.location.pathname,
    navigate: () => {
    },
});

type RouterProviderPropsType = {
    children: ReactNode
};

function RouterProvider({children}: RouterProviderPropsType) {
    const [state, dispatch] = useReducer(routerStoreReducer, {path: window.location.pathname});

    useEffect(() => {
        const onPop = () => dispatch({type: 'POPSTATE', path: window.location.pathname});
        window.addEventListener('popstate', onPop);
        return () => window.removeEventListener('popstate', onPop);
    }, []);

    const navigate = useCallback((to: string) => {
        window.history.pushState({}, '', to);
        dispatch({type: 'NAVIGATE', path: to});
    }, []);

    return (
        <RouterContext.Provider value={{path: state.path, navigate}}>
            {children}
        </RouterContext.Provider>
    );
}

export function ExampleAppContext() {
    return (
        <RouterProvider>
            <ExampleAppNav/>
            <ExampleAppContent/>
        </RouterProvider>
    );
}

function ExampleAppNav() {
    const {navigate} = useContext(RouterContext);
    return (
        <nav>
            <button onClick={() => navigate('/')}>Home</button>
            <button onClick={() => navigate('/about')}>About</button>
        </nav>
    );
}

function ExampleAppContent() {
    const {path} = useContext(RouterContext);
    return path === '/about' ? <AboutPage/> : <HomePage/>;
}

function HomePage() {
    return <>
        <div>Home</div>
        <SomeInnerHomePageComponent/>
    </>;
}

function SomeInnerHomePageComponent() {
    const {path} = useContext(RouterContext);
    return <div>Some inner component {path}</div>;
}

function AboutPage() {
    const {path} = useContext(RouterContext);
    return <div>About {path}  </div>;
}

While the ContextProvider removes the need for prop drilling, it can lead to a very large context and in a way, it could also be grouping all its child components into one large component. What if you want a navigation bar to listen for route changes without re-rendering every time the page content updates? Instead of relying on context, you can create a centralized store that works seamlessly with useSyncExternalStore. This lets any component subscribe directly to router updates without intermediary providers.

// router-store.ts
export type RouterStoreNotifyCallbackType = () => void;

export type RouterStoreDataType = {
    path: string;
};

type RouterStoreDataUpdateType = {
    path: string;
};

let cachedData: Readonly<RouterStoreDataType> = {
    path: window.location.pathname,
};

type RouterStoreType = {
    getSnapshot: () => Readonly<RouterStoreDataType>,
    updateData: (data: RouterStoreDataUpdateType) => void,
    subscribe: (callback: RouterStoreNotifyCallbackType) => void,
    unsubscribe: (callback: RouterStoreNotifyCallbackType) => void,
};

let subscribers: Readonly<Set<RouterStoreNotifyCallbackType>> = new Set();

function emitChange() {
    for (const subscriber of subscribers) {
        subscriber();
    }
}

export const routerStore: RouterStoreType = {
    getSnapshot: () => cachedData,
    updateData: (data) => {
        if (data.path !== cachedData.path) {
            cachedData = {
                path: data.path,
            };
            window.history.pushState(null, "", data.path);
            emitChange();
        }
    },
    subscribe: (subscription) => {
        const subscribersClone = new Set(subscribers);
        subscribersClone.add(subscription);
        subscribers = subscribersClone;
    },
    unsubscribe: (subscription) => {
        const subscribersClone = new Set(subscribers);
        subscribersClone.delete(subscription);
        subscribers = subscribersClone;
    },
};

This code establishes the basic store, but we still need a way for components to read from and write to that store.

Hooking into the Router State

To connect components to the routerStore, we will create a concise custom hook. This hook encapsulates subscription logic as well as read and update functions for router state. By using this hook, components can navigate or react to route changes without any prop drilling or context dependencies.

// router-hook.ts
import {routerStore, type RouterStoreDataType, type RouterStoreNotifyCallbackType} from "./router-store.ts";
import {useCallback, useSyncExternalStore} from "react";

type RouterHookType = {
    data: Readonly<RouterStoreDataType>,
    navigate: (path: string) => void,
};

function subscribe(callback: RouterStoreNotifyCallbackType) {
    routerStore.subscribe(callback);
    return () => {
        routerStore.unsubscribe(callback);
    }
}

export function useRouterHook(): RouterHookType {
    const data = useSyncExternalStore(
        subscribe,
        routerStore.getSnapshot
    );

    const navigate = useCallback((to: string) => {
        // Intentional setTimeout to make page navigation seem slower
        setTimeout(() => {
            routerStore.updateData({path: to});
        }, 1000);
    }, []);

    return {data, navigate};
}

Navigation with a RouterLink

Now that we have a custom subscription hook, we can create a RouterLink component. This component simply calls the hook's navigation function when clicked. Centralizing navigation logic in one place makes it easy to maintain and reuse.

// router-link.tsx
import {useRouterHook} from "./router-hook.ts";
import {type AnchorHTMLAttributes, memo, type MouseEventHandler, useCallback} from "react";

interface RouterLinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
    to: string;
}

function RouterLink({to, children, ...props}: RouterLinkProps) {
    const {navigate} = useRouterHook();
    const handleClick: MouseEventHandler<HTMLAnchorElement> = useCallback((e) => {
        e.preventDefault();
        navigate(to);
    }, [navigate, to]);

    return (
        <a href={to} onClick={handleClick} {...props}>
            {children}
        </a>
    );
}

export default memo(RouterLink);

Creating the Router Provider Component

Eager Loading Version

Let's begin with an eager loading router component. It renders everything immediately based on the current path. This version establishes the basic routing mechanism and serves as a baseline for more advanced features.

// router-root-eager-load.tsx
import {memo, type ReactElement, useCallback, useLayoutEffect, useState} from "react";
import {useRouterHook} from "./router-hook.ts";

type RouterRootEagerLoadRouteType = {
    [route: string]: ReactElement;
};

type RouterRootEagerLoadPropsType = {
    routes: RouterRootEagerLoadRouteType,
};

function RouterRootEagerLoad({routes}: RouterRootEagerLoadPropsType) {
    const {data, navigate} = useRouterHook();
    const [readyElement, setReadyElement] = useState<ReactElement | null>(null);

    const popStateListener = useCallback(() => {
        if (window.location.pathname != data.path) {
            navigate(window.location.pathname);
        }
    }, [data.path, navigate]);

    useLayoutEffect(() => {
        window.addEventListener('popstate', popStateListener);
        return () => {
            window.removeEventListener('popstate', popStateListener);
        }
    }, [popStateListener]);

    useLayoutEffect(() => {
        setReadyElement(routes[data.path]);
    }, [data.path, routes]);

    return (
        <div>
            {readyElement}
        </div>
    );
}

export default memo(RouterRootEagerLoad);

// example-app-eager-load.tsx
import {useRouterHook} from "./router-hook.ts";
import App from "./App.tsx";
import Register from "./register.tsx";
import Login from "./login.tsx";
import Todo from "./todo.tsx";
import RouterRootEagerLoad from "./router-root-eager-load.tsx";

const routes = {
    '/': <App/>,
    '/register': <Register/>,
    '/login': <Login/>,
    '/todos': <Todo/>,
};

export function ExampleAppEagerLoad() {
    return <>
        <ExampleAppNav/>
        <RouterRootEagerLoad routes={routes}/>
    </>;
}

function ExampleAppNav() {
    const {navigate} = useRouterHook();
    return (
        <nav>
            <button onClick={() => navigate('/')}>Home</button>
            <button onClick={() => navigate('/register')}>Register</button>
            <button onClick={() => navigate('/login')}>Login</button>
            <button onClick={() => navigate('/todos')}>Todos</button>
        </nav>
    );
}

Here's how that looks like

Adding Lazy Loading with Suspense

To improve user experience, we can add lazy loading using React's Suspense. In this example, we will simulate a 5-second delay to illustrate how Suspense displays a fallback while components are loading.

// router-root-basic.tsx
import {
    type ComponentType,
    type LazyExoticComponent,
    memo,
    type ReactElement,
    Suspense,
    useCallback,
    useLayoutEffect,
    useState
} from "react";
import {useRouterHook} from "./router-hook.ts";

type RouterRootRouteType = {
    [route: string]: LazyExoticComponent<ComponentType>;
};

type RouterRootPropsType = {
    routes: RouterRootRouteType,
};

function RouterRootBasic({routes}: RouterRootPropsType) {
    const {data, navigate} = useRouterHook();
    const [readyElement, setReadyElement] = useState<ReactElement | null>(null);
    const makeElement = useCallback((path: string) => {
        const LazyElement = routes[path];
        if (LazyElement != null) {
            return <LazyElement/>
        }
        return null;
    }, [routes]);

    const popStateListener = useCallback(() => {
        if (window.location.pathname != data.path) {
            navigate(window.location.pathname);
        }
    }, [data.path, navigate]);

    useLayoutEffect(() => {
        window.addEventListener('popstate', popStateListener);
        return () => {
            window.removeEventListener('popstate', popStateListener);
        }
    }, [popStateListener]);

    useLayoutEffect(() => {
        setReadyElement(makeElement(data.path));
    }, [data.path, makeElement]);

    return (
        <div>
            <Suspense fallback={<div>Loading...</div>}>
                {readyElement}
            </Suspense>
        </div>
    );
}

export default memo(RouterRootBasic);

// example-app-basic.tsx
import {lazy, memo} from "react";
import {useRouterHook} from "./router-hook.ts";
import RouterRootBasic from "./router-root-basic.tsx";

const routes = {
    '/': lazy(() => delayForDemo(import('./App.tsx'))),
    '/register': lazy(() => delayForDemo(import('./register.tsx'))),
    '/login': lazy(() => delayForDemo(import('./login.tsx'))),
    '/todos': lazy(() => delayForDemo(import('./todo.tsx'))),
};

function delayForDemo(promise: any) {
    return new Promise(resolve => {
        setTimeout(resolve, 5000);
    }).then(() => promise);
}

export function ExampleAppBasic() {
    return <>
        <ExampleAppNavMemoized/>
        <RouterRootBasic routes={routes}/>
    </>;
}

const ExampleAppNavMemoized = memo(ExampleAppNav);

function ExampleAppNav() {
    return (
        <nav>
            <ExampleHomeButtonMemoized/>
            <ExampleRegisterButtonMemoized/>
            <ExampleLoginButtonMemoized/>
            <ExampleTodosButtonMemoized/>
        </nav>
    );
}

// The code below will all be fixed with React Compiler and we can just use a loop instead
const ExampleHomeButtonMemoized = memo(ExampleHomeButton);

function ExampleHomeButton() {
    const {navigate} = useRouterHook();
    return <button onClick={() => navigate('/')}>Home</button>;
}

const ExampleRegisterButtonMemoized = memo(ExampleRegisterButton);

function ExampleRegisterButton() {
    const {navigate} = useRouterHook();
    return <button onClick={() => navigate('/register')}>Register</button>;
}

const ExampleLoginButtonMemoized = memo(ExampleLoginButton);

function ExampleLoginButton() {
    const {navigate} = useRouterHook();
    return <button onClick={() => navigate('/login')}>Login</button>;
}

const ExampleTodosButtonMemoized = memo(ExampleTodosButton);

function ExampleTodosButton() {
    const {navigate} = useRouterHook();
    return <button onClick={() => navigate('/todos')}>Todos</button>;
}

Here's how that looks like

Enabling Concurrency with useTransition

React 18 introduces concurrency features that help keep the UI responsive during expensive updates. Instead of blocking the user interface with a Suspense fallback, we can use useTransition so that navigation does not interrupt ongoing interactions:

// router-root.tsx
import {
    type ComponentType,
    type LazyExoticComponent,
    memo,
    type ReactElement,
    useCallback,
    useLayoutEffect,
    useState,
    useTransition
} from "react";
import {useRouterHook} from "./router-hook.ts";

type RouterRootRouteType = {
    [route: string]: LazyExoticComponent<ComponentType>;
};

type RouterRootPropsType = {
    routes: RouterRootRouteType,
};

function RouterRoot({routes}: RouterRootPropsType) {
    const {data, navigate} = useRouterHook();
    const [isPending, startTransition] = useTransition();
    const [readyElement, setReadyElement] = useState<ReactElement | null>(null);
    const makeElement = useCallback((path: string) => {
        const LazyElement = routes[path];
        if (LazyElement != null) {
            return <LazyElement/>
        }
        return null;
    }, [routes]);

    const popStateListener = useCallback(() => {
        if (window.location.pathname != data.path) {
            navigate(window.location.pathname);
        }
    }, [data.path, navigate]);

    useLayoutEffect(() => {
        window.addEventListener('popstate', popStateListener);
        return () => {
            window.removeEventListener('popstate', popStateListener);
        }
    }, [popStateListener]);

    useLayoutEffect(() => {
        startTransition(() => {
            setReadyElement(makeElement(data.path));
        });
    }, [data.path, makeElement]);

    return (
        <div>
            {isPending ? <div>Loading...</div> : null}
            {readyElement}
        </div>
    );
}

export default memo(RouterRoot);

...
export function ExampleAppFinal() {
    return <>
        <ExampleAppNavMemoized/>
        <RouterRoot routes={routes}/>
    </>;
}
...

Here's how that looks like

When you compare these approaches, you will see that the UI remains interactive while the new route's components load. This pattern aligns with React's vision for concurrent rendering, leading to a smoother user experience.

Limitations and What's Next

No Server-Side Rendering Support

Currently, this router is designed for client-side rendering only. If you need server-side rendering, you would have to extend the implementation substantially.

URL-Coupled and Limited Complex Navigation

This simple router relies on the browser's URL and does not support multiple router instances on the same page. It also lacks advanced nested routing patterns or path-matching capabilities.

Testing Is Not Included Here

Although tests are not part of this walkthrough, the modular structure makes it straightforward to add unit and integration tests. In a follow-up article, I plan to demonstrate how to write tests for each module of this router.

Closing Thoughts

Building a minimal router helps clarify how routing, suspense, and concurrency features work under the hood. In this article, we have:

Explored the limitations of holding router state with useState and seen how useReducer provides a clearer way to describe state transitions.
Discussed the challenges of prop drilling and how a ContextProvider can help, but also why a centralized store can be a more flexible alternative.
Created a routerStore that leverages useSyncExternalStore, enabling components to subscribe directly to route changes without prop drilling or context nesting.
Written a concise custom hook to read from and update the router store, making navigation logic reusable across components.
Built a RouterLink component that centralizes navigation behavior and simplifies link handling in an application.
Implemented an Eager Loading router to establish the basic routing mechanism, then introduced Lazy Loading with React’s Suspense to improve user experience during component loading.
Replaced Suspense fallbacks with the useTransition hook to keep the UI responsive during route transitions, demonstrating React 18’s concurrency capabilities.
Acknowledged areas for improvement, such as the lack of server-side rendering, advanced nested routing patterns, and built-in tests, and outlined how the modular design makes future enhancements straightforward.

My hope is that this walkthrough demystifies some of the React 18 advancements and encourages you to experiment with these hooks in your own projects. If you have questions or suggestions, please reach out! Collaboration is how our community grows. Happy coding!