DEV Community: Mykhailo Toporkov 🇺🇦

Essential Node.js Packages for Effortless Kafka Development!

Mykhailo Toporkov 🇺🇦 — Mon, 07 Sep 2026 11:35:16 +0000

A while back I got annoyed that kafkajs hadn't seen a proper update in a long time, so I figured I'd just rewrite it in TypeScript for myself. Simple weekend project, right?

It went out of control a bit.... One package became two, then three, then four — and somewhere along the way "rewrite kafkajs in TS" quietly turned into a small ecosystem:

🔹 kafka-core - the client itself. Producer, consumer, and admin, talking directly to the Kafka wire protocol.
🔹 kafka-cli - a terminal command built right on top of kafka-core.
🔹 kafka-config - a shared config file loader so core and cli read settings the same way.
🔹 kafka-docs - the documentation site, because undocumented code is just a rumor.
🔹 kafka-studio - a web based UI interface that should simplify your local development

The whole point is TypeScript-first, from the ground up - real types, no bolted-on .d.ts guesswork, built for how Node devs actually work today. Also, I extended compatibility for Kafka features, all of which can be found in the documentation posted on GitHub Pages.

If you work with Kafka and Node, take a look, break something, open an issue, send a PR. Feel free to contribute to my slop )) - seriously though, contributions welcome.

https://github.com/cookieMonsterDev/kafka

A while back I got annoyed that kafkajs hadn't seen a proper update in a long time, so I figured I'd just rewrite it in TypeScript for myself. Simple weekend project, right? It went out of control a… | Mykhailo Toporkov

A while back I got annoyed that kafkajs hadn't seen a proper update in a long time, so I figured I'd just rewrite it in TypeScript for myself. Simple weekend project, right? It went out of control a bit.... One package became two, then three, then four — and somewhere along the way "rewrite kafkajs in TS" quietly turned into a small ecosystem: 🔹 kafka-core - the client itself. Producer, consumer, and admin, talking directly to the Kafka wire protocol. 🔹 kafka-cli - a terminal command built right on top of kafka-core. 🔹 kafka-config - a shared config file loader so core and cli read settings the same way. 🔹 kafka-docs - the documentation site, because undocumented code is just a rumor. 🔹 kafka-studio - a web based UI interface that should simplify your local development The whole point is TypeScript-first, from the ground up - real types, no bolted-on .d.ts guesswork, built for how Node devs actually work today. Also, I extended compatibility for Kafka features, all of which can be found in the documentation posted on GitHub Pages. If you work with Kafka and Node, take a look, break something, open an issue, send a PR. Feel free to contribute to my slop )) - seriously though, contributions welcome. https://lnkd.in/drujQdRa Node.js Kafka GitHub

linkedin.com

The kafkajs hasn't been updated in over 3 years... Any thoughts about this?

Mykhailo Toporkov 🇺🇦 — Tue, 25 Aug 2026 15:06:28 +0000

To be straightforward, I'm not feeling too keen on packages that aren't well-maintained, and three years is a really long time... In these past three years, most developers migrated to using AI, our workflows changed, and everything moved at the speed of light—except KafkaJS. https://www.npmjs.com/package/kafkajs

So, since I don't have much of a social life and I care about maintainability, I decided to do something about it. What started as a simple TypeScript rewrite of KafkaJS went a bit out of control. That's why I'd love to invite the community to help develop and maintain it. https://github.com/cookieMonsterDev/kafka

My thoughs about roadmap includes adding a global setup via kafka.config.ts, an npx-compatible CLI, and a UI studio to visualize, simulate, and manage your Kafka topics and messages.

I'd love to hear your thoughts on my AI slop!)))

Docs skills for AI

Mykhailo Toporkov 🇺🇦 — Sun, 05 Jul 2026 08:34:11 +0000

I need to accept that I can't compete with AI in terms of speed. Although I’m still waiting for the exact moment the bubble bursts and pricing forces people to use tokens more mindfully, I just can't match the speed of an AI agent when I'm searching for something in the codebase.

However, models still hallucinate sometimes, which is why RAG was created. RAG is cool when you need to search the internet for something, but what’s even cooler is giving your agents skills backed by references from official documentation.

Although I originally built this for myself, I thought this repo of skills would be useful to share with everyone! :)

https://github.com/cookieMonsterDev/agents-skills/tree/master

Async Generators Are Underused — Here's How to Change That

Mykhailo Toporkov 🇺🇦 — Sat, 23 May 2026 08:18:08 +0000

We all want to build memory-efficient apps that can handle heavy loads. To achieve this, we optimize them using separate workers, batch processing, and other techniques. Yet, despite these efforts, you rarely see asynchronous generators used - even though their core concept is both lazy and async. You pull the next value only when you're ready for it, making them inherently memory-efficient and naturally backpressure-aware.

Part of the reason is cultural: most tutorials reach for while(true) loops, callback-based streams, or one-shot await calls because that's what people are familiar with. Async generators require a slight mental shift - from pushing data at a consumer to pulling it on demand - and that model isn't well-represented in most learning resources. I want to change that by sharing a few of my favorite practical patterns.

Pagination / Database Cursor

Case: You need to send a personalized newsletter to 100m+ users

Knowing that you need to fetch a large volume of user data from the database and then iterate over it to create a personalized newsletter for every single user, your first thought should be how to efficiently paginate over the records. Of course, you could define limit and offset variables and use a for loop to process data in batches from the database, but I suggest using an async generator to create a custom iterator instead.

type CreateGetUsersIteratorOptions = {
  batchSize?: number;
  where?: string[] | ObjectLiteral[] | Brackets[] /// etc...
};

async *createGetUsersIterator(options: CreateGetUsersIteratorOptions): AsyncGenerator<User[]> {
  const { batchSize = 100, where = [] } = options;

  let offset = 0;

  while (true) {
      const query = userRepository
        .createQueryBuilder('user')
        .orderBy('user.id', 'ASC')
        .skip(offset)
        .take(batchSize);

      if (where.length) where.forEach((i) => query.andWhere(i));

      const batch = await query.getMany();

      if (batch.length === 0) break;

      yield batch;

      if (batch.length < batchSize) break;

      offset += batchSize;
    }
};

// Usage example for the case

const iterator = createGetUsersIterator();

for await (const users of iterator) {
  await sendNewsletter(users);
}

By encapsulating pagination logic inside an async generator, you get a clean, reusable abstraction that keeps memory usage flat regardless of dataset size - you always hold at most one batch in memory at a time. The caller just iterates with for await...of, completely unaware of the underlying batching mechanics. This separation of concerns means you can tune batch size, swap the data source, or add filters in one place without touching any consumer code.

Handling Large Files

Case: You need to parse and process a multi-gigabyte CSV export (logs, transactions, etc.)

Loading a file of that size into memory all at once will crash your process or at least spike RAM to unacceptable levels. The classic workaround - piping a ReadStream through an event emitter - scatters your logic across callbacks. An async generator lets you treat the file as a plain for await...of sequence instead, pulling one chunk at a time.

type CreateReadFileIteratorOptions = {
  chunkSize?: number;
  encoding?: BufferEncoding;
};

async function* createReadFileIterator(
  filePath: string,
  options: CreateReadFileIteratorOptions = {},
): AsyncGenerator<string> {
  const { chunkSize = 64 * 1024, encoding = "utf8" } = options;

  const stream = fs.createReadStream(filePath, {
    highWaterMark: chunkSize,
    encoding,
  });

  let buffer = "";

  for await (const chunk of stream) {
    buffer += chunk;

    const lines = buffer.split("\n");

    buffer = lines.pop() ?? "";

    for (const line of lines) {
      if (line.trim()) yield line;
    }
  }

  if (buffer.trim()) yield buffer;
}

// Usage example for the case

const iterator = createReadFileIterator("./transactions.csv");

for await (const line of iterator) {
  await processTransaction(parseCsvLine(line));
}

Because the generator yields one line at a time, your heap stays constant regardless of whether the file is 10 MB or 10 GB. The highWaterMark option on the underlying ReadStream gives you a single knob to tune I/O throughput vs. memory pressure, while the consumer remains a clean for await...of loop with no knowledge of streams, buffers, or backpressure mechanics.

Streaming API Responses (LLMs, SSE)

Case: You need to relay an LLM's streaming response to your client in real time

LLM APIs (OpenAI, Anthropic, etc.) and Server-Sent Events deliver data incrementally - waiting to accumulate the full response before forwarding it defeats the purpose entirely and adds unnecessary latency. An async generator lets you consume the raw stream token by token and expose it as a clean iterable that any part of your application can for await...of over.

type CreateChatStreamIteratorOptions = {
  model?: string;
  maxTokens?: number;
};

async function* createChatStreamIterator(
  prompt: string,
  options: CreateChatStreamIteratorOptions = {},
): AsyncGenerator<string> {
  const { model = "gpt-4o", maxTokens = 1024 } = options;

  const stream = await openai.chat.completions.create({
    model,
    stream: true,
    max_tokens: maxTokens,
    messages: [{ role: "user", content: prompt }],
  });

  for await (const chunk of stream) {
    const token = chunk.choices[0]?.delta?.content;

    if (token) yield token;
  }
}

// Usage example for the case — forwarding tokens to an HTTP response (Express)

app.get("/chat", async (req, res) => {
  res.setHeader("Content-Type", "text/event-stream");

  const iterator = createChatStreamIterator(req.query.prompt as string);

  for await (const token of iterator) {
    res.write(`data: ${JSON.stringify({ token })}\n\n`);
  }

  res.end();
});

Wrapping the vendor SDK's proprietary stream in your own async generator creates a stable internal contract: swap OpenAI for Anthropic or any SSE source and only the generator changes - every consumer stays untouched. The generator also provides natural flow control at the application level: if your downstream processing is slow, the for await...of loop simply won't request the next token until it's ready, avoiding unbounded accumulation in your own code.

Conclusion

Async generators sit at the intersection of two ideas that are independently powerful - laziness and async - and genuinely rare to find combined so cleanly in a language primitive. Yet, browsing through most production codebases, you'll find manual offset loops, ad-hoc event emitter plumbing, and one-shot await calls where a single async function* would have been simpler, safer, and more memory-efficient.

The three patterns above barely scratch the surface. Rate-limited API crawlers, real-time WebSocket feeds, recursive directory walks, multi-step ETL pipelines - all of them are natural fits. The abstraction is always the same: hide the messy mechanics of how data arrives inside the generator, and let the consumer focus entirely on what to do with each piece.

Async generators have been part of JavaScript since Node 10 and are available in every modern runtime. The tooling is there. The next time you reach for a while(true) pagination loop or a stream callback chain, consider whether an async function* might say the same thing in half the lines - and mean it more clearly.

Link to my original post feel free to like it also, ofc if you liked this one)

How I chose my new work laptop

Mykhailo Toporkov 🇺🇦 — Fri, 06 Mar 2026 18:42:22 +0000

I am, frankly speaking, not a fan of Apple and its ecosystem of products... but I still bought a MacBook Pro.

To begin with, my old ASUS ROG Strix GL553VD was aging (9 years), slow, and I frequently ran into reboots when running unit tests because 16 GB of RAM wasn't enough—though I suppose that was partially an issue of RAM speed. And yeah, increasing the swap size to 20 GB was not the fix.

Obviously, I was annoyed and decided it was time for an upgrade. My first choice was not to engage with Windows. At the beginning of my career, I had experience working on Windows, but mostly via WSL because I liked to play games; however, that is kind of irrelevant now. Really, Windows is only good for games, Office staff, and maybe—really maybe—for developing something in the Windows ecosystem.

Because of this, I was sure that anything I bought would have Linux or UNIX. The question of price didn't worry me much because I wasn't going to buy a laptop for just a year or two. This is where performance, the amount of RAM, and SSD size come into the scene.

Apple sucks when it comes to prices per RAM or disk size. Originally, I was going to wait for the HP EliteBook X G2 with 64 GB of RAM and a 1 TB SSD, but I just could not bear to work with the constant reboots anymore, so I bought a MacBook Pro on M5 with 32 GB of RAM and a 1 TB SSD. It was also partially because the M5 has better single-core performance...

I’ve been working from the Mac for almost a week now, and it is fast, no doubt. I still cannot get used to all the hotkey combinations, though time will fix it. But when I switched from Windows to Ubuntu, the only difference I noticed was that changing the language was different. Right now, my biggest disappointment is that this shitbox does not have any USB-A ports, and I needed to buy an external hub just to connect a USB flash stick or my mouse. So, fuck you Apple for this.

Anyway, if you were click-baited and expected me to compare or advertise one OS over another, you wasted your time. If you like something, you like something. The only important thing is accepting that most of the world's software runs on Linux, most code is probably written on Mac (though I'm not exactly sure about this—I’d probably need to Google it to be certain), and most office stuff is done on Windows. So, choose depending on what you need)))

The Year’s Almost Over — What Tech Stuff Did You Read?

Mykhailo Toporkov 🇺🇦 — Sun, 07 Dec 2025 08:31:03 +0000

This year I went full Breaking Bad mode on tech books — and read almost nothing else. You can have different opinions about how useful these books are, and it really varies from one to another. Some of them are genuinely important and can reshape the way you think about architecture or how you approach building applications.

Here’s the list of books I covered this year:

Clean Architecture – Robert C. Martin
Database Internals – Alex Petrov
The Linux Command Line (2nd Edition) – William E. Shotts Jr.
Clean Code – Robert C. Martin
Building Microservices (2nd Edition) – Sam Newman
Designing Data-Intensive Applications – Martin Kleppmann
The Intelligent Investor – Benjamin Graham

So what about you—what did you read this year, and was it useful?
For me personally, Building Microservices was the most valuable one, partly because I’m currently in the process of splitting a monolith into microservices on my project 😄

NestJS Microservices Monorepo - Setup, Testing and Containerization

Mykhailo Toporkov 🇺🇦 — Sat, 25 Oct 2025 09:21:58 +0000

Yo! Today I’m going to demonstrate how to set up a NestJS monorepo with two REST microservices — Users and Posts — each using its own database through Prisma ORM.

For inter-service communication, we’ll use Kafka, taking advantage of the features provided by @nestjs/microservices.

I’ve also included an example of a GitHub Action workflow for testing the monorepo — it runs tests only for the services that were changed in your commits.

If you’re interested in a specific topic, feel free to use the navigation below:

Monorepo Setup
Unit and E2E testing
Containerization
CI/CD Testing
Conclusion

Monorepo Setup

First things first — to create a monorepo, we need a regular Nest project. I’ll create it like this:

nest new users

Now we can convert it into a monorepo by generating a new app inside it, like this:

cd users && nest generate app posts

Also I will add some shared libs like common and kafka:

nest generate library common && nest generate library kafka

All these commands and other documentation about NestJS monorepos, libraries, and CLI commands can be found in the official NestJS documentation. What’s important for us is to get a structure like the one shown below:

📂 apps
 | --- 📂 users
 |
 | --- 📂 posts
 |
📂 libs
 | --- 📂 common
 |
 | --- 📂 kafka
 |
etc.

I’ll skip the database setup and other boring details, but what’s really important to mention is that I prefer each microservice to have its own .env file at the root of the service. The same goes for the Dockerfile and docker-compose.yml. Since I’m using Prisma as my ORM of choice, the generated files will also be located in the root of each microservice folder.

To summarize, the structure will look like this:

📂 apps
 | --- 📂 users
 |      | --- 📂 generated/prisma (excluded by gitignore by default)
 |      | --- 📂 prisma
 |      | --- 📂 test
 |      | --- 📂 src
 |      | --- .env
 |      | --- Dockerfile
 |      | --- docker-compose.yml
 |
etc.

Now, regarding communication between microservices, I’ll be using Kafka. Here’s my setup in libs/kafka:

import { ConfigService } from '@nestjs/config';
import { MicroserviceOptions, Transport } from '@nestjs/microservices';

export const createKafkaMicroserviceOptions = (configService: ConfigService): MicroserviceOptions => ({
  transport: Transport.KAFKA,
  options: {
    client: {
      clientId: configService.get('APP_NAME') ?? 'default-client',
      brokers: [configService.get('KAFKA_URL') ?? 'localhost:9092'],
    },
    consumer: {
      groupId: `${configService.get('APP_NAME') ?? 'default'}-consumer`,
    },
  },
});

import { ClientKafka } from '@nestjs/microservices';
import { UsersEvents, PostsEvents } from '@libs/kafka/messages';
import { Injectable, OnModuleInit, Inject } from '@nestjs/common';

type KafkaEvents = UsersEvents & PostsEvents;

@Injectable()
export class KafkaService implements OnModuleInit {
  constructor(@Inject('KAFKA_CLIENT') private readonly kafkaClient: ClientKafka) {}

  async onModuleInit() {
    await this.kafkaClient.connect();
  }

  emit<Topic extends keyof KafkaEvents>(topic: Topic, message: KafkaEvents[Topic]) {
    return this.kafkaClient.emit(topic, message);
  }

  send<Topic extends keyof KafkaEvents>(topic: Topic, message: KafkaEvents[Topic]) {
    return this.kafkaClient.send<Topic, KafkaEvents[Topic]>(topic, message);
  }
}

import { Global, Module } from '@nestjs/common';
import { KafkaService } from '@libs/kafka/kafka.service';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { ClientsModule, Transport } from '@nestjs/microservices';

@Global()
@Module({
  imports: [
    ConfigModule,
    ClientsModule.registerAsync([
      {
        name: 'KAFKA_CLIENT',
        imports: [ConfigModule],
        inject: [ConfigService],
        useFactory: (configService: ConfigService) => {
          const appName = configService.get<string>('APP_NAME');
          const kafkaUrl = configService.get<string>('KAFKA_URL');

          return {
            transport: Transport.KAFKA,
            options: {
              client: {
                clientId: appName ?? 'default-client',
                brokers: kafkaUrl ? [kafkaUrl] : ['localhost:9092'],
              },
              consumer: {
                groupId: `${appName ?? 'default'}-consumer`,
              },
            },
          };
        },
      },
    ]),
  ],
  providers: [KafkaService],
  exports: [KafkaService],
})
export class KafkaModule {}

The usage of all this is pretty straightforward: the KafkaModule should be imported into the AppModule of your microservice to enable using the KafkaService inside other services.

The createKafkaMicroserviceOptions, on the other hand, is needed to utilize @nestjs/microservices, which provides many decorators for working comfortably with event-based communication, such as the @MessagePattern decorator:

import { ConfigService } from '@nestjs/config';
import { AppModule } from '@users-micros/app.module';
import { NestFactory, Reflector } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { createKafkaMicroserviceOptions } from '@libs/kafka/kafka.config';
import { ClassSerializerInterceptor, ValidationPipe } from '@nestjs/common';
import { DatabaseExceptionFilter } from '@users-micros/database/databse.filter';

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

  const configService = app.get(ConfigService);

  const kafkaMicroserviceOptions = createKafkaMicroserviceOptions(configService);

  app.connectMicroservice(kafkaMicroserviceOptions);

  app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }));

  app.useGlobalInterceptors(new ClassSerializerInterceptor(app.get(Reflector)));

  app.useGlobalFilters(new DatabaseExceptionFilter());

  const config = new DocumentBuilder()
    .setTitle('Users microservice')
    .setVersion('0.0.1')
    .setDescription('The users microservice API description')
    .build();

  SwaggerModule.setup('docs', app, () => SwaggerModule.createDocument(app, config));

  await app.startAllMicroservices();

  const port = configService.get<number>('APP_PORT') ?? 3021;

  await app.listen(port);
}
bootstrap();

Oh, looking back, I really skipped a lot of stuff… That might raise questions like “How did you set up this or that?” But as I mentioned before, this isn’t a guide on building a microservice app from scratch — it’s about setting up the monorepo. If you’re patient enough to read until the end, you’ll find a link to the repository that was used to create this post))

Unit and E2E testing

The unit tests are also pretty straightforward, and even easier if you don’t set up aliases for your microservice folders. Here’s an example of unit tests for the UsersService:

import * as utils from '@libs/common/utils';
import { KafkaMock } from '@libs/kafka/kafka.mock';
import { NotFoundException } from '@nestjs/common';
import { User } from '@users-micros/generated/prisma';
import { UsersService } from '@users-micros/users/users.service';
import { UsersTopics } from '@libs/kafka/messages/users.messages';
import { DatabaseService } from '@users-micros/database/database.service';

export const mockUsers: User[] = [
  {
    id: '1',
    name: 'John Doe',
    createdAt: new Date(),
    updatedAt: new Date(),
  },
  {
    id: '2',
    name: 'Jane Smith',
    createdAt: new Date(),
    updatedAt: new Date(),
  },
];

export const mockUser = mockUsers[0];

describe('UsersService', () => {
  let usersService: UsersService;
  let databaseService: jest.Mocked<DatabaseService>;
  let kafkaService: typeof KafkaMock;

  beforeEach(() => {
    databaseService = {
      user: {
        create: jest.fn().mockResolvedValue(mockUser),
        findFirst: jest.fn((args) =>
          args.where.id === mockUser.id ? Promise.resolve(mockUser) : Promise.resolve(null),
        ),
        findMany: jest.fn().mockResolvedValue(mockUsers),
        count: jest.fn().mockResolvedValue(mockUsers.length),
        update: jest.fn((args) =>
          args.where.id === mockUser.id ? Promise.resolve({ ...mockUser, ...args.data }) : Promise.resolve(null),
        ),
      },
    } as any;

    kafkaService = { ...KafkaMock };

    usersService = new UsersService(kafkaService as any, databaseService);

    jest.spyOn(utils, 'createSearchQuery');
    jest.spyOn(utils, 'createSortQuery');
  });

  describe('createUser', () => {
    it('should create a user', async () => {
      const data = { name: 'John Doe', email: 'john@example.com' };
      const result = await usersService.createUser(data as any);
      expect(databaseService.user.create).toHaveBeenCalledWith({ data });
      expect(result).toBe(mockUser);
    });
  });

  describe('findUsers', () => {
    it('should return users with filters', async () => {
      const query = { skip: 0, take: 10, search: 'John', sortBy: 'name', sortOrder: 'asc' } as any;
      const result = await usersService.findUsers(query);
      expect(utils.createSearchQuery).toHaveBeenCalledWith(query.search, expect.anything());
      expect(utils.createSortQuery).toHaveBeenCalledWith(query.sortBy, query.sortOrder);
      expect(databaseService.user.findMany).toHaveBeenCalled();
      expect(result).toEqual(mockUsers);
    });
  });

  describe('findUsersCount', () => {
    it('should return count of users', async () => {
      const query = { search: 'John' } as any;
      const result = await usersService.findUsersCount(query);
      expect(utils.createSearchQuery).toHaveBeenCalledWith(query.search, expect.anything());
      expect(databaseService.user.count).toHaveBeenCalled();
      expect(result).toBe(mockUsers.length);
    });
  });

  describe('findUser', () => {
    it('should return user if found', async () => {
      const result = await usersService.findUser(mockUser.id);
      expect(databaseService.user.findFirst).toHaveBeenCalledWith({ where: { id: mockUser.id } });
      expect(result).toBe(mockUser);
    });

    it('should throw NotFoundException if not found', async () => {
      await expect(usersService.findUser('no-id')).rejects.toThrow(NotFoundException);
    });
  });

  describe('updateUser', () => {
    it('should update user and emit kafka event', async () => {
      const data = { name: 'Updated Name' };
      const result = await usersService.updateUser(mockUser.id, data);
      expect(databaseService.user.update).toHaveBeenCalledWith({ where: { id: mockUser.id }, data });
      expect(kafkaService.emit).toHaveBeenCalledWith(UsersTopics.USER_UPDATED, { name: 'Updated Name' });
      expect(result.name).toBe('Updated Name');
    });

    it('should throw NotFoundException if user does not exist', async () => {
      await expect(usersService.updateUser('no-id', { name: 'test' })).rejects.toThrow(NotFoundException);
    });
  });
});

E2E tests require a database connection because they simulate the real behavior of your microservice. It might be a good idea to first check the Containerization section of this post:

import * as request from 'supertest';
import { INestApplication, ValidationPipe } from '@nestjs/common';
import { Test, TestingModule } from '@nestjs/testing';
import { FixtureModule } from '@users-micros/test/fixture.module';
import { DatabaseService } from '@users-micros/database/database.service';

describe('UsersController (e2e)', () => {
  let app: INestApplication;
  let databaseService: DatabaseService;

  beforeAll(async () => {
    const moduleFixture: TestingModule = await Test.createTestingModule({
      imports: [FixtureModule],
    }).compile();

    app = moduleFixture.createNestApplication();
    app.useGlobalPipes(new ValidationPipe({ transform: true }));
    await app.init();

    databaseService = moduleFixture.get(DatabaseService);
  });

  beforeEach(async () => {
    await databaseService.user.deleteMany();
  });

  afterAll(async () => {
    await databaseService.user.deleteMany();
    await app.close();
  });

  describe('POST /users', () => {
    it('should create a user successfully', async () => {
      const userData = { name: 'John Doe' };

      const response = await request(app.getHttpServer()).post('/users').send(userData).expect(200);

      expect(response.body).toMatchObject({
        id: expect.any(String),
        name: userData.name,
        createdAt: expect.any(String),
        updatedAt: expect.any(String),
      });

      const user = await databaseService.user.findUnique({
        where: { id: response.body.id },
      });
      expect(user).toBeTruthy();
      expect(user?.name).toBe(userData.name);
    });

    it('should return 400 when name is missing', async () => {
      await request(app.getHttpServer()).post('/users').send({}).expect(400);
    });

    it('should return 400 when name is empty', async () => {
      await request(app.getHttpServer()).post('/users').send({ name: '' }).expect(400);
    });

    it('should return 400 when name is too long', async () => {
      await request(app.getHttpServer())
        .post('/users')
        .send({ name: 'a'.repeat(65) })
        .expect(400);
    });
  });

  describe('GET /users', () => {
    beforeEach(async () => {
      // Create test users
      await databaseService.user.createMany({
        data: [
          { name: 'Alice Smith' },
          { name: 'Bob Johnson' },
          { name: 'Carol Davis' },
          { name: 'David Wilson' },
          { name: 'Eve Brown' },
        ],
      });
    });

    it('should return paginated users', async () => {
      const response = await request(app.getHttpServer()).get('/users').query({ skip: 0, take: 10 }).expect(200);

      expect(response.body).toMatchObject({
        skip: 0,
        take: 10,
        total: 5,
        data: expect.arrayContaining([
          expect.objectContaining({
            id: expect.any(String),
            name: expect.any(String),
            createdAt: expect.any(String),
            updatedAt: expect.any(String),
          }),
        ]),
      });
      expect(response.body.data).toHaveLength(5);
    });

    it('should search users by name', async () => {
      const response = await request(app.getHttpServer()).get('/users').query({ search: 'alice' }).expect(200);

      expect(response.body.data).toHaveLength(1);
      expect(response.body.data[0].name).toBe('Alice Smith');
    });

    it('should sort users by name', async () => {
      const response = await request(app.getHttpServer())
        .get('/users')
        .query({ sortBy: 'name', sortOrder: 'asc' })
        .expect(200);

      const names = response.body.data.map((user) => user.name);
      expect(names).toEqual([...names].sort());
    });

    it('should return 400 for invalid sort field', async () => {
      await request(app.getHttpServer()).get('/users').query({ sortBy: 'invalid' }).expect(400);
    });
  });

  describe('GET /users/:userId', () => {
    let testUser;

    beforeEach(async () => {
      testUser = await databaseService.user.create({
        data: { name: 'Test User' },
      });
    });

    it('should return a user by id', async () => {
      const response = await request(app.getHttpServer()).get(`/users/${testUser.id}`).expect(200);

      expect(response.body).toMatchObject({
        id: testUser.id,
        name: testUser.name,
        createdAt: expect.any(String),
        updatedAt: expect.any(String),
      });
    });

    it('should return 404 for non-existing user', async () => {
      await request(app.getHttpServer()).get('/users/non-existing-id').expect(404);
    });
  });

  describe('PATCH /users/:userId', () => {
    let testUser;

    beforeEach(async () => {
      testUser = await databaseService.user.create({
        data: { name: 'Test User' },
      });
    });

    it('should update a user successfully', async () => {
      const updateData = { name: 'Updated Name' };

      const response = await request(app.getHttpServer()).patch(`/users/${testUser.id}`).send(updateData).expect(200);

      expect(response.body).toMatchObject({
        id: testUser.id,
        name: updateData.name,
        createdAt: expect.any(String),
        updatedAt: expect.any(String),
      });

      const updatedUser = await databaseService.user.findUnique({
        where: { id: testUser.id },
      });
      expect(updatedUser).toBeTruthy();
      expect(updatedUser?.name).toBe(updateData.name);
    });

    it('should return 404 for non-existing user', async () => {
      await request(app.getHttpServer()).patch('/users/non-existing-id').send({ name: 'New Name' }).expect(404);
    });

    it('should return 400 when update data is invalid', async () => {
      await request(app.getHttpServer()).patch(`/users/${testUser.id}`).send({ name: '' }).expect(400);

      await request(app.getHttpServer())
        .patch(`/users/${testUser.id}`)
        .send({ name: 'a'.repeat(65) })
        .expect(400);
    });
  });
});

Containerization

For now, let’s just add a docker-compose.yml and a Dockerfile for each microservice. As a result, the project structure should look something like this:

📂 apps
 | --- 📂 users
 |      | --- 📂 src
 |      | --- .env
 |      | --- Dockerfile
 |      | --- docker-compose.yml
 |
 | --- 📂 posts
 |      | --- 📂 src
 |      | --- .env
 |      | --- Dockerfile
 |      | --- docker-compose.yml
 |
📂 libs
 | --- 📂 kafka
 |      | --- 📂 src
 |      | --- .env
 |      | --- docker-compose.yml

Here’s an example of my docker-compose.yml. When developing locally, I’ll be honest — I usually comment out the app service because I don’t really need it:

services:
  app:
    container_name: ${APP_NAME}-app
    build:
      context: ../..
      dockerfile: apps/${APP_NAME}/Dockerfile
      args:
        APP_NAME: ${APP_NAME}
    restart: on-failure
    env_file:
      - ./.env
    ports:
      - '${APP_PORT}:${APP_PORT}'
    depends_on:
      - database

  database:
    container_name: ${APP_NAME}-database
    image: postgres:latest
    restart: always
    env_file:
      - ./.env
    environment:
      POSTGRES_DB: '${DATABASE_NAME}'
      POSTGRES_USER: '${DATABASE_USER}'
      POSTGRES_PASSWORD: '${DATABASE_PASSWORD}'
    ports:
      - '${DATABASE_PORT}:5432'
    volumes:
      - database:/var/lib/postgresql/data

volumes:
  database:
    driver: local

Here are also examples of the Dockerfile and .env. Honestly, I’m not sure what else should be added here:

FROM node:22-alpine AS base 

# build stage
FROM base AS build 
ARG APP_NAME 
ARG NODE_ENV=development 
ENV NODE_ENV=${NODE_ENV}
WORKDIR /usr/src/app 
COPY package*.json ./
RUN npm ci
COPY . .
RUN npx prisma generate --schema apps/${APP_NAME}/prisma/schema.prisma \
    && npm run build ${APP_NAME}

# production stage
FROM base AS production 
ARG APP_NAME 
ARG NODE_ENV=production 
ENV NODE_ENV=${NODE_ENV} HUSKY=0
WORKDIR /usr/src/app 
COPY package*.json ./
RUN npm ci --only=production
COPY --from=build /usr/src/app/dist ./dist
COPY --from=build /usr/src/app/node_modules/.prisma ./node_modules/.prisma
COPY --from=build /usr/src/app/apps/${APP_NAME}/prisma ./apps/${APP_NAME}/prisma
COPY --from=build /usr/src/app/apps/${APP_NAME}/generated ./apps/${APP_NAME}/generated

ENV APP_MAIN_FILE=dist/apps/${APP_NAME}/main
ENV DATABASE_SCHEMA=apps/${APP_NAME}/prisma/schema.prisma
CMD ["sh", "-c", "npx prisma migrate deploy --schema ${DATABASE_SCHEMA} && node ${APP_MAIN_FILE}"]

# APP
APP_NAME=users
APP_PORT=3021

# Database
DATABASE_PORT=3022
DATABASE_NAME="postgresql"
DATABASE_USER="johndoe"
DATABASE_PASSWORD="randompassword"
DATABASE_URL="postgresql://johndoe:randompassword@database:5432/postgresql"

# Kafka
KAFKA_URL=localhost:3011

Setting up Kafka is up to you, of course. 😉 If you’d rather have it all ready for local development, check out the repo link at the end of the post.

Also I need to mention, if you want to set up all apps locally without dokcer, you need to be careful with environment variables like DATABASE_URL and KAFKA_URL, as they need to be updated to match your local setup.

CI/CD Testing

For testing in CI/CD, I’ll be using GitHub Actions. If you’re not familiar with them, please read the documentation.

To efficiently run tests inside a monorepo, we need to detect changes across apps and libraries. Therefore, any action that involves testing should start with this:

name: E2E Testing

on:
  push:
    branches: [master]
  pull_request:
    branches: [master]

jobs:
  detect-changes:
    runs-on: ubuntu-latest
    outputs:
      users: ${{ steps.filter.outputs.users }}
      posts: ${{ steps.filter.outputs.posts }}
      common: ${{ steps.filter.outputs.common }}
    steps:
      - uses: actions/checkout@v4

      - name: Detect changes
        id: filter
        uses: dorny/paths-filter@v3
        with:
          filters: |
            users:
              - 'apps/users/**'
              - 'libs/common/**'
            posts:
              - 'apps/posts/**'
              - 'libs/common/**'
            common:
              - 'libs/common/**'

Here are a few grammatically correct and natural rewrites of your sentence — depending on tone:

test-users:
    needs: detect-changes
    if: ${{ needs.detect-changes.outputs.users == 'true' }}
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:latest
        env:
          POSTGRES_USER: johndoe
          POSTGRES_PASSWORD: randompassword
          POSTGRES_DB: postgresql-test
        ports:
          - 3022:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'
      - run: npm ci
      - run: chmod -R +x ./scripts
      - run: npm run database:generate users
      - run: npm run database:push users test
      - run: npm run test:e2e users

  test-posts:
    needs: detect-changes
    if: ${{ needs.detect-changes.outputs.posts == 'true' }}
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:latest
        env:
          POSTGRES_USER: johndoe
          POSTGRES_PASSWORD: randompassword
          POSTGRES_DB: postgresql-test
        ports:
          - 3032:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'
      - run: npm ci
      - run: chmod -R +x ./scripts
      - run: npm run database:generate posts
      - run: npm run database:push posts test
      - run: npm run test:e2e posts

You can see that I’m using scripts such as npm run database:generate posts and npm run test:e2e posts. Relevant examples are available in the repository linked below)

Conclusion

That’s it for now regarding the NestJS monorepo! I hope you found this post useful. Since you made it to the end, here’s the link to the monorepo used in this post. I originally built it to prove a concept to my team, but now that it has served its purpose — feel free to use it!

useVideo - Custom hook for interacting with video

Mykhailo Toporkov 🇺🇦 — Sun, 07 Sep 2025 08:33:36 +0000

Right now, hooks are an essential part of React, and I bet you’ve used some custom hooks at least once to handle logic. Recently, I needed to create a custom video player, and to handle the video I came up with this custom useVideo hook:

import type { RefObject } from "react";
import { useRef, useState, useEffect, useCallback } from "react";

type VideoState = {
  volume: number;
  duration: number;
  isMuted: boolean;
  isEnded: boolean;
  isLoading: boolean;
  isStarted: boolean;
  isPlaying: boolean;
  isSeeking: boolean;
  currentTime: number;
  isBuffering: boolean;
  error: MediaError | null;
};

type UseVideoReturn = VideoState & {
  ref: RefObject<HTMLVideoElement | null>;
  mute: () => void;
  play: () => void;
  pause: () => void;
  unmute: () => void;
  restart: () => void;
  toggleMute: () => void;
  togglePlay: () => void;
  seek: (time: number) => void;
  skip: (seconds: number) => void;
  setVolume: (volume: number) => void;
  setPlaybackRate: (rate: number) => void;
};

const initialState: VideoState = {
  volume: 1,
  error: null,
  duration: 0,
  currentTime: 0,
  isMuted: false,
  isEnded: false,
  isLoading: false,
  isStarted: false,
  isPlaying: false,
  isSeeking: false,
  isBuffering: false,
};

export function useVideo(): UseVideoReturn {
  const ref = useRef<HTMLVideoElement>(null);
  const [state, setState] = useState<VideoState>(initialState);

  const updateState = useCallback((update: Partial<VideoState>) => setState((prev) => ({ ...prev, ...update })), []);

  useEffect(() => {
    const video = ref.current;
    if (!video) return;

    const controller = new AbortController();
    const { signal } = controller;

    const eventMap: Partial<Record<keyof HTMLMediaElementEventMap, () => void>> = {
      pause: () => updateState({ isPlaying: false }),
      abort: () => updateState({ isLoading: false }),
      seeking: () => updateState({ isSeeking: true }),
      canplay: () => updateState({ isLoading: false }),
      emptied: () => updateState({ isLoading: false }),
      stalled: () => updateState({ isLoading: false }),
      suspend: () => updateState({ isLoading: false }),
      waiting: () => updateState({ isBuffering: true }),
      loadstart: () => updateState({ isLoading: true }),
      loadeddata: () => updateState({ isLoading: false }),
      canplaythrough: () => updateState({ isLoading: false }),
      ended: () => updateState({ isPlaying: false, isEnded: true }),
      play: () => updateState({ isStarted: true, isPlaying: true }),
      loadedmetadata: () => updateState({ duration: video.duration }),
      durationchange: () => updateState({ duration: video.duration }),
      timeupdate: () => updateState({ currentTime: video.currentTime }),
      error: () => updateState({ isLoading: false, error: video.error }),
      playing: () => updateState({ isPlaying: true, isBuffering: false }),
      volumechange: () => updateState({ volume: video.volume, isMuted: video.muted }),
      seeked: () => updateState({ isSeeking: false, currentTime: video.currentTime }),
    };

    Object.entries(eventMap).forEach(([event, handler]) => video.addEventListener(event, handler, { signal }));

    updateState({
      volume: video.volume,
      isMuted: video.muted,
      isEnded: video.ended,
      duration: video.duration || 0,
      currentTime: video.currentTime || 0,
      isPlaying: !video.paused && !video.ended,
    });

    return () => controller.abort();
  }, [ref, updateState]);

  const play = useCallback(() => {
    if (!ref.current) return;

    ref.current.play();
  }, [ref]);

  const pause = useCallback(() => {
    if (!ref.current) return;

    ref.current.pause();
  }, [ref]);

  const togglePlay = useCallback(() => {
    if (!ref.current) return;

    ref.current.paused ? ref.current.play() : ref.current.pause();
  }, [ref]);

  const seek = useCallback(
    (seconds: number) => {
      if (!ref.current) return;

      const video = ref.current;

      const newTime = Math.max(0, Math.min((video.currentTime || 0) + seconds, video.duration || 0));

      ref.current.currentTime = newTime;
    },
    [ref],
  );

  const skip = useCallback(
    (seconds: number) => {
      if (!ref.current) return;

      seek((ref.current.currentTime || 0) + seconds);
    },
    [seek, ref],
  );

  const mute = useCallback(() => {
    if (!ref.current) return;

    ref.current.muted = true;
  }, [ref]);

  const unmute = useCallback(() => {
    if (!ref.current) return;

    ref.current.muted = false;
  }, [ref]);

  const toggleMute = useCallback(() => {
    if (!ref.current) return;

    ref.current.muted = !ref.current.muted;
  }, [ref]);

  const setVolume = useCallback(
    (volume: number) => {
      if (!ref.current) return;

      ref.current.volume = Math.max(0, Math.min(volume, 1));
    },
    [ref],
  );

  const setPlaybackRate = useCallback(
    (rate: number) => {
      if (!ref.current) return;

      ref.current.playbackRate = rate;
    },
    [ref],
  );

  const restart = useCallback(() => {
    if (!ref.current) return;

    ref.current.currentTime = 0;

    ref.current.play();
  }, [ref]);

  return {
    ref,
    mute,
    play,
    seek,
    skip,
    pause,
    unmute,
    restart,
    setVolume,
    togglePlay,
    toggleMute,
    setPlaybackRate,
    ...state,
  };
}

Maybe this will save someone some development time, so feel free to Ctrl+C / Ctrl+V ))) Of course, if you have any suggestions for improvements, I’d be glad to read them in the comments.

P.S.
Today, ~~russians~~ terrorists launched the largest air attack on Ukraine and struck a government building for the first time. It seems some world leaders have decided to swallow their guts and suck up to evil instead of fighting it. Guess who can be called the new Chamberlain?

Does anybody have a job opportunity? Cuse I am currently not occupied(((

Mykhailo Toporkov 🇺🇦 — Wed, 20 Aug 2025 09:18:09 +0000

Started to learn Elixir, would you recommend something or mention that I need to know?

Mykhailo Toporkov 🇺🇦 — Wed, 30 Jul 2025 09:59:35 +0000

Dealing with Next.js ways of building Apps

Mykhailo Toporkov 🇺🇦 — Sat, 28 Jun 2025 14:16:49 +0000

Next.js is a popular React-based framework for building full-stack web applications. It has, for better or worse, a unique approach to handling routing. I like Next, but for me, it has far too many downsides to use for large enterprise applications, especially those that are client-heavy. And today, I will write about Next.js behaviors and how to deal with them.

First things first, let's set up a test environment to better understanding what we will deal with. For now, I’ll have one file for server actions where I fetch data, and just one home page component:

// src/actions/index.ts

"use server";

type Post = {
  id: number;
  userId: number;
  title: string;
  body: string;
}

export const getPost = async function (postId: number, delay: number = 1000): Promise<Post> {
  const response = await fetch(`https://jsonplaceholder.typicode.com/posts/${postId}`);
  const json = await response.json();
  await new Promise(resolve => setTimeout(resolve, delay));
  return json;
} 

type Todo = {
  id: number;
  userId: number;
  title: string;
  completed: boolean;
}

export const getTodo = async function (todoId: number, delay: number = 1000): Promise<Todo> {
  const response = await fetch(`https://jsonplaceholder.typicode.com/todos/${todoId}`);
  const json = await response.json();
  await new Promise(resolve => setTimeout(resolve, delay));
  return json;
}

// src/app/page.tsx

import { getPost, getTodo } from '@/actions/index'

export default async function Home() {

  const post = await getPost(1, 2000);

  const todo = await getTodo(1, 5000);

  return (
    <main>
      <section>{JSON.stringify(post)}</section>
      <section>{JSON.stringify(todo)}</section>
    </main>
  );
}

Error Handling

Obviously, this code has two major problems: there's no way to display a loading state while the request is being resolved, and there's no error handling. For now, I'll postpone loading fallbacks and focus on error handling since it's not that difficult to fix. Next.js suggests a few ways to handle errors: redirecting to another page using redirect or notFound, returning the error as data by creating a wrapper that catches any error and returns some metadata about it, or using an error.tsx file.

I genuinely think that error.tsx is the worst option among them all. It’s not that it doesn’t have its uses—my concern is that it’s an entire file that serves as a fallback UI for unexpected runtime errors across the whole page. That’s really problematic. If I have an error in getTodo, I want to show an error only in the Todo component, not replace the entire page.

The redirect and notFound seem more attractive to use here, but they require pages to redirect the user to, and they still don’t handle runtime errors that can occur before the redirection happens. So, with all that said, we’re left with only one reliable way to handle errors: return an error as data.

Here is the basic wrapper for handling action errors:

// src/actions/index.ts

"use server";

type ActionData<T> = {
  data: T;
  error: null;
};

type ActionError = {
  data: null;
  error: Record<string, any>;
};

type Action<Args extends any[], Data> = (...args: Args) => Promise<Data>;

const createAction = function <Args extends any[], Data>(action: Action<Args, Data>) {
  return async (...args: Parameters<Action<Args, Data>>): Promise<ActionData<Data> | ActionError> => {
    return action(...args)
      .then((data: Data) => ({ data, error: null }))
      .catch((error: any) => ({ data: null, error: { message: error.message } }));
  };
};

type Todo = {
  id: number;
  userId: number;
  title: "string;"
  completed: boolean;
};

export const getTodo = createAction(async function (todoId: number, delay: number = 1000): Promise<Todo> {
  const response = await fetch(`https://jsonplaceholder.typicode.com/todos/${todoId}`);
  const json = await response.json();
  await new Promise((resolve) => setTimeout(resolve, delay));

  throw Error("Some error");

  return json;
});

// etc...

Now, the Todo component is inside the page, and its related errors can be displayed without affecting other information on the page, such as the post info:

// src/app/page.tsx

import { getPost, getTodo } from "@/actions/index";

export default async function Home() {
  const { data: postData, error: postError } = await getPost(1, 2000);

  const { data: todoData, error: todoError } = await getTodo(1, 5000);

  return (
    <main>
      <section>
        {postData && <div className="text-green-400">{JSON.stringify(postData)}</div>}
        {postError && <div className="text-red-400">{JSON.stringify(postError)}</div>}
      </section>
      <section>
        {todoData && <div className="text-green-400">{JSON.stringify(todoData)}</div>}
        {todoError && <div className="text-red-400">{JSON.stringify(todoError)}</div>}
      </section>
    </main>
  );
}

With this setup, we successfully avoid creating multiple error.tsx files for different routes (file overheat). However, you still need at least a root-level error.tsx file to handle unexpected scenarios.

It’s worth mentioning that you can still use custom React error boundaries. However, for this, data fetching needs to be placed in the target component where you plan to use the data. Of course, the error boundary component cannot be in the same file as your server component, since it is a client component. At this point, it's clear that I'm not a fan of creating that many files for a component's behavior when some logic can be grouped into a single file.

Loading Fallbacks

Displaying some UI for the user while data is being fetched is common sense, and yet, we’re currently not doing it. As with error handling, Next.js suggests a few ways to address this—such as using a loading.tsx file or React Suspense. In Error Handling, I mentioned that we want to handle errors per component, not for the entire page. The same applies to loading fallbacks. If we use loading.tsx, the loading fallback will be displayed (for the entire page) until the slowest promise is resolved. That is why loading.tsx is not for us, and now we left with <Suspense>.

To actually use suspense, we first need to move the fetching logic to a separate server component. Then, we wrap the component in <Suspense>. Where exactly to wrap it is a separate question.

We can have both the loading component and the server component exported from the same file, and then use them with <Suspense> at the page level:

// src/components/post.tsx

import { getPost } from "@/actions";

export function PostLoading() {
  return <div>Post Loading....</div>;
}

export async function Post({ postId }: { postId: number }) {
  const { data, error } = await getPost(postId, 2000);

  return (
    <section>
      {data && <div className="text-green-400">{JSON.stringify(data)}</div>}
      {error && <div className="text-red-400">{JSON.stringify(error)}</div>}
    </section>
  );
}

Or we can have everything in the same file, which is my preferred approach. If you're attentive, you might notice a small drawback: when I need to pass props to my <TodoServer> component, I actually have to pass them through <Todo>, which results in a bit of props drilling — minor, but still... I’ll address this drilling later in the article.

// src/components/todo.tsx

import { Suspense } from "react";
import { getTodo } from "@/actions";

function TodoLoading() {
  return <div>Todo Loading....</div>;
}

async function TodoServer({ todoId }: { todoId: number }) {
  const { data, error } = await getTodo(todoId, 5000);

  return (
    <section>
      {data && <div className="text-green-400">{JSON.stringify(data)}</div>}
      {error && <div className="text-red-400">{JSON.stringify(error)}</div>}
    </section>
  );
}

export function Todo(props: { todoId: number }) {
  return <Suspense fallback={<TodoLoading />} children={<TodoServer {...props} />} />;
}

That is just an example how will this look inside page component:

// src/app/page.tsx

import { Suspense } from "react";
import { Todo } from "@/components/todo";
import { Post, PostLoading } from "@/components/post";

export default async function Home() {
  return (
    <main>
      <Suspense fallback={<PostLoading />}>
        <Post postId={1} />
      </Suspense>
      <Todo todoId={1}/>
    </main>
  );
}

Now that we’ve covered error handling and UI loading fallbacks, the application is much more interactive and user-friendly. Next, I want to address issues related to params and searchParams in Next.js.

Page Params Drilling

Next.js allows dynamic routing, so let’s move our Todo to a separate page with its own route. app/[todoId]/page.tsx. At this stage, everything is fairly straightforward: define types for params and searchParams, await their resolution, display them, and pass them to the <Todo> component:

// src/app/[todoId]/page.tsx

import { Todo } from "@/components/todo";

type PageProps = {
  params: Promise<{ todoId: number }>;
  searchParams: Promise<{ page: number }>;
};

export default async function TodoPage({ params, searchParams }: PageProps) {
  const { todoId } = await params;
  const { page } = await searchParams;

  return (
    <main>
      <h2>TodoId: {todoId}</h2>
      <h2>Page: {page}</h2>
      <Todo todoId={todoId} />
    </main>
  );
}

At this point, you might feel satisfied — but I’m certainly not. You see, while this approach is good enough for a simple page DOM tree, I foresee a props drilling nightmare when it comes to a more complex setup.

What are you going to do if your component is nested inside another component, which is inside yet another one, and so on? It’s not like you can use React Context in server components... This line of thinking leads to a justified desire to access the URL state directly within a server component.

In a server component, we can access cookies and headers, so I suggest utilizing them. However, before retrieving data from them, we need to store that data first — and for this, Next.js middleware.ts is the best option:

// src/middleware.ts

import { NextResponse, NextRequest } from "next/server";

export async function middleware(request: NextRequest) {
  const response = NextResponse.next();

  const { pathname, searchParams } = request.nextUrl;

  response.cookies.set("x-page-params", JSON.stringify(pathname.split("/").filter(Boolean)));
  response.cookies.set("x-page-search-params", JSON.stringify(Object.fromEntries(searchParams.entries())));

  return response;
}

export const config = {
  matcher: [
    // Run on everything but Next internals and static files
    "/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)",
  ],
};

As you can see, the params I put in the cookie are just an array taken from the pathname. This carries a bit of risk, because unlike Next.js—which automatically maps params to your endpoint—you need to know exactly where your component is located to extract dynamic params, not just static ones.

The getters for these params are fairly simple. In them, I omitted checking whether the JSON was parsed correctly for the sake of simplicity, but I don't recommend skipping this check when building a real app:

// src/utils.ts

"use server";
import { cookies } from "next/headers";

export async function getParams(): Promise<Array<string>> {
  const cookieStore = await cookies();
  const pageParams = cookieStore.get("x-page-params");
  return JSON.parse(pageParams ? pageParams.value : "[]") as Array<any>;
}

export async function getSearchParams(): Promise<Record<string, string>> {
  const cookieStore = await cookies();
  const pageParams = cookieStore.get("x-page-search-params");
  return JSON.parse(pageParams ? pageParams.value : "{}") as Record<string, string>;
}

With getters in place, params and search params are available inside server components, and you may use them however you like:

// src/components/todo.tsx

import Link from "next/link";
import { Suspense } from 'react'
import { getTodo } from "@/actions";
import { getParams, getSearchParams } from "@/utils";

export function TodoLoading() {
  return <div>Todo Loading....</div>;
}

export async function TodoServer() {
  const params = await getParams();
  const searchParams = await getSearchParams();

  const todoId = +params[0] || 1;

  const currentPage = +searchParams.page || 1;

  const nextPageQuery = { ...searchParams, page: currentPage + 1 };

  const prevPageQuery = { ...searchParams, page: currentPage - 1 };

  const { data, error } = await getTodo(todoId, 2000);

  return (
    <section>
      {data && (
        <>
          <div>{JSON.stringify(params)}</div>
          <div>{JSON.stringify(data)}</div>
          <div className="flex gap-8">
            <Link href={{ query: prevPageQuery }}>Prev page</Link>
            <span>Page: {currentPage}</span>
            <Link href={{ query: nextPageQuery }}>Next page</Link>
          </div>
        </>
      )}
      {error && <div style={{ color: "red" }}>{JSON.stringify(error)}</div>}
    </section>
  );
}

export async function Todo() {
  return <Suspense fallback={<TodoLoading />} children={<TodoServer />} />;
}

Try playing around with this pagination — do you notice how React Suspense works in Next.js? That will be the next chapter to cover.

Suspense with Search Params

If you followed the code and tried to play around with it, you may notice that the loading fallback does not appear when the search parameter is changed via a link click.

Suspense fallback does not show when only search parameters change because Next.js does not remount the server component — it reuses the existing one. Since no navigation to a new route occurs, the component isn't re-fetched, and Suspense is not triggered again. To force a reload, you must use dynamic key or segment that reacts to search params.

I prefer addressing this by creating a custom <Suspense> that re-renders when the search params or path change—solving the issue where the fallback doesn’t show on search param updates.

// src/components/search-params-suspense.tsx

"use client";
import { Suspense } from "react";
import type { ComponentProps } from "react";
import { usePathname, useSearchParams } from "next/navigation";

export function SearchParamsSuspense(props: ComponentProps<typeof Suspense>) {
  const pathname = usePathname();
  const searchParams = useSearchParams();

  const key = `${pathname}?${searchParams.toString()}`;

  return <Suspense key={key} {...props} />;
}

That's pretty much all I wanted to share about working with Next.js. I won't claim that my approach is the only correct one—someone might come up with a better solution. But for now, I'll just patiently wait for your thoughts on the matter. See ya!

Tomorrow will be my second blood donation. This time, it will be at the Blood Center of the Ministry of Defense of Ukraine. Also thanks to Vasyl Maliuk and everyone involved in today’s event!

Mykhailo Toporkov 🇺🇦 — Sun, 01 Jun 2025 13:40:29 +0000