DEV Community: Xavier Carrera Gimbert

Hexagonal Architecture: Simple Introduction + Real-World Example

Xavier Carrera Gimbert — Wed, 26 Nov 2025 22:59:16 +0000

Hexagonal Architecture is very popular these days. However, I have seen that a lot of the resources out there that try to teach it do so in a very abstract and technical way. While that is great for understanding all the details, it makes for a poor introduction.

So, in this article, I would like to address this issue. I would like to make a simple and straightforward introduction to HA (Hexagonal Architecture) and give you some other resources for further learning, including a public repo that applies HA that I created for this article.

So let's begin!

What is Hexagonal Architecture?

Hexagonal Architecture is a design paradigm that focuses on separating the core of the application from everything else and specifying rules on how these two parts should interact.

What is the "core of the app"? What is "everything else"?

The core of the app is the business logic. All the things that make your app your app, no matter what external tools you use.

For example, if you are making a todo app, you want to be able to create todos, update todos, and remove todos. This is the core of the app.

Your app would still be a todo app if, instead of Postgres, you used SQLite; if instead of Prisma, you used Drizzle; or if instead of getting requests via a NestJS server, you used a CSV processor. These things that are not the core are "everything else".

According to HA, how should the "core of the app" interact with "everything else"?

By using ports.

Ports are the contracts that the core of the app establishes with "everything else" to work.

So, for example, if you want to create a todo, a port would specify that the core app needs a JSON object that provides a title and a description. It doesn't matter if this object comes from an HTTP request, a CSV file, or whatever. The app needs what the port specifies.

To follow this example, a tool like NestJS could get a POST request that a user sent and pass the relevant information following the port contract to the app.

Of course, in this example, we need something to get the request, manage the validation, and send it to the core app following the port contract. This is called the adapter. It's an adapter because it adapts the incoming information into something the core app can use.

To create a little diagram:

User sends request $\rightarrow$ NestJS controller gets it, validates it, and sends it to the core app by obeying a port contract (Adapter) $\rightarrow$ App processes the request (Core App)

The same process is followed for outgoing requests from the core app.

To put an example:

Imagine the core app, once it has received the correct data to create a todo, wants to store it in the database. The core app would send the correct information to the ORM/Database adapter by obeying a port contract, and the adapter would process the todo saving.

Notice that adapters not only adapt incoming information (driving side), they also adapt information from the app to the necessities of external services like an ORM (driven side).

Are there any other rules? That seems easy.

The core concept is not hard to grasp, but the implementation can get tricky.

For example, it is important to not mix the core of the app with the rest, which is easy to say but hard to do.

You do not want the business logic to depend on the ORM, for example. If you are using Prisma as your ORM and then decide to change it to Drizzle, you should not need to change the business logic. If you do, you have not implemented HA correctly.

Where can I learn more about HA?

I highly recommend these two articles to begin with. I think they offer a great explanation.

This one is a great follow-up reading. It is easy to read but gives more specific details about HA: Understanding Hexagonal Architecture - DEV Community
This other one is great because it gives a TS example of HA: A Detailed Guide to Hexagonal Architecture with Examples | by Dev Cookies | Medium

Is there any real-world example code I can check?

Yes! I have created a project that follows the patterns of HA as strictly as I could: Xalsar/user-posts-backend

Good bye! 👋

Hope you liked this little introduction to the topic. Feel free to ask questions or give feedback in the comments if you have it.

Cheers! And happy coding!

Abstract Factory Pattern: Explained for Humans

Xavier Carrera Gimbert — Mon, 24 Nov 2025 17:28:15 +0000

The Problem

We have the classes Payment and Refund. We use these classes to process and refund transactions, as the names imply.

However, we use different payment providers. So, each of the mentioned classes will be instantiated differently depending on the provider, even though they will perform the same core job.

How do we tackle this code problem in a clean way?

By using the Abstract Factory pattern.

The Solution: The Abstract Factory Pattern

First, we create the interfaces that will define the core functionality of the classes we need.

// Product interfaces

interface Payment {
  pay(amount: number): Promise<void>;
}

interface Refund {
  refund(transactionId: string): Promise<void>;
}

ℹ️ We call these interfaces "Product interfaces" because the classes that are going to implement these interfaces are the products of (or instantiated by) factory methods.

ℹ️ A factory is simply a function (or a method or a class) that instantiates a class.

Now we define the interface that the factory class will use to instantiate these products.

// Abstract Factory interface

interface PaymentAbstractFactory {
  createPayment(): Payment;
  createRefund(): Refund;
}

We then define the specific product classes we will instantiate using the interfaces created previously:

// Concrete Products for Stripe

class StripePayment implements Payment {
  async pay(amount: number): Promise<void> {
    console.log(`Processing payment of $${amount} via Stripe...`);
    // Stripe payment logic here
  }
}

class StripeRefund implements Refund {
  async refund(transactionId: string): Promise<void> {
    console.log(
      `Processing refund for transaction ${transactionId} via Stripe...`,
    );
    // Stripe refund logic here
  }
}

And now we create the factory that will create the products:

// Concrete Factory for Stripe

class StripeFactory implements PaymentAbstractFactory {
  createPayment(): Payment {
    return new StripePayment();
  }

  createRefund(): Refund {
    return new StripeRefund();
  }
}

And finally, we use it in the client!

// Client code

const processTransaction = async (
  factory: PaymentAbstractFactory,
  amount: number,
) => {
  const payment = factory.createPayment();
  await payment.pay(amount);
};

const refundTransaction = async (
  factory: PaymentAbstractFactory,
  transactionId: string,
) => {
  const refund = factory.createRefund();
  await refund.refund(transactionId);
};

const stripeFactory = new StripeFactory();
processTransaction(stripeFactory, 100);
refundTransaction(stripeFactory, 'stripe_tx_12345');

What have we done here?

We have created an interface (the Abstract Factory) that we use to create factories. These factories, in turn, create a family of product classes that share a common relationship (e.g., all belonging to the Stripe provider).

Why is this pattern useful?

It allows us to have factories that generate classes which have a common relationship.

In this case, we are able to have a factory that generates classes that work for a common payment service.

We could easily create another factory for a different payment service and use it too:

// Concrete Factory for PayPal

class PayPalFactory implements PaymentAbstractFactory {
  createPayment(): Payment {
    return new PayPalPayment();
  }

  createRefund(): Refund {
    return new PayPalRefund();
  }
}

Where can I learn more about this pattern?

You can ask your trustworthy LLM, drop a comment, or visit one of the most famous resources to learn about design patterns: Refactoring Guru.

Here is the specific article about this design pattern: Abstract Factory

Goodbye!

I hope this article helped you understand this design pattern better! Feel free to leave a comment if you have any questions or feedback.

Thanks!

The Factory Method Design Pattern Explained for Humans

Xavier Carrera Gimbert — Thu, 20 Nov 2025 11:45:12 +0000

Design patterns are often explained in a very complicated way, which makes it hard for casual readers to understand.

So today, I would like to explain to you how I understand the Factory Method Pattern in the simplest way possible—and with a real-world example!

The problem we are trying to solve

Let's assume we are trying to support multiple payment methods in our app. It should be easy but in reality it is very cumbersome to implement. All the methods allow users to do the same operations (pay for an order, get a refund, etc.), but each service does it in a different way. You do not process a payment with Stripe in the same way you do with PayPal, for example.

Also, we want to be able to expand the code in the future without breaking the existing one. Our app may need to support Google Pay in the near future. Who knows!

The solution: The Factory Method

We first define the interface that all our payment methods have to follow. In this case, each payment method has to allow users to process a payment and do a refund. No matter if we use Stripe, PayPal or whatever, users have to be able to perform these two operations.

interface PaymentProcessor {
  processPayment(
    amount: number,
  ): Promise<{ success: boolean; transactionId: string }>;
  refund(transactionId: string): Promise<boolean>;
}

Now we define each processor.

ℹ️ I use the word processor rather than method because in this code context I think it makes more sense.

class StripeProcessor implements PaymentProcessor {
  async processPayment(
    amount: number,
  ): Promise<{ success: boolean; transactionId: string }> {
    console.log(`Processing $${amount} via Stripe...`);
    // Stripe API call
    return { success: true, transactionId: 'stripe_tx_12345' };
  }

  async refund(transactionId: string): Promise<boolean> {
    console.log(`Refunding Stripe transaction ${transactionId}`);
    return true;
  }
}

class PayPalProcessor implements PaymentProcessor {
  async processPayment(
    amount: number,
  ): Promise<{ success: boolean; transactionId: string }> {
    console.log(`Processing $${amount} via PayPal...`);
    // PayPal API call
    return { success: true, transactionId: 'paypal_tx_67890' };
  }

  async refund(transactionId: string): Promise<boolean> {
    console.log(`Refunding PayPal transaction ${transactionId}`);
    return true;
  }
}

We have to also specify our creator, or in other words, the class that will have the factory method that will instantiate the specific processors and orchestrate their methods.

abstract class PaymentService {
  abstract createProcessor(): PaymentProcessor; // The Factory Method

  async checkout(amount: number): Promise<void> {
    const processor = this.createProcessor();
    const result = await processor.processPayment(amount);

    if (result.success) {
      console.log(
        `Payment successful! Transaction ID: ${result.transactionId}`,
      );
    }
  }

  async refund(transactionId: string): Promise<void> {
    const processor = this.createProcessor();
    const success = await processor.refund(transactionId);

    if (success) {
      console.log(`Refund successful for Transaction ID: ${transactionId}`);
    }
  }
}

😨 Are you confused? Don't worry, bear with me; once we finish, you will understand.

Now we create the different implementations of the services by extending the creator class:

class StripePaymentService extends PaymentService {
  createProcessor(): PaymentProcessor {
    return new StripeProcessor();
  }
}

class PayPalPaymentService extends PaymentService {
  createProcessor(): PaymentProcessor {
    return new PayPalProcessor();
  }
}

And finally we apply it in our app:

function processCheckout(paymentMethod: 'stripe' | 'paypal', amount: number) {
  const service =
    paymentMethod === 'stripe'
      ? new StripePaymentService()
      : new PayPalPaymentService();

  service.checkout(amount);
}

processCheckout('stripe', 99.99);

Wait, I do not understand, what happened here?

We have created the classes StripePaymentService and PayPalPaymentService which extend the creator class PaymentService. This creator class uses a factory method createProcessor to create an instance of each the payment processor and use it to orchestrate the checkout and the refund.

Notice that the creator class does not care which payment processor are we using. It simply orchestrates the one it is provided.

Why is this pattern useful?

It allows us to execute different variants (Stripe, PayPal) of a process (processing payments and refunds) with minimal code changes.

We simply instantiate the class we need (StripePaymentService or PayPalPaymentService) and the creator class orchestrates all the different logic.

If in the future we want to add new payment processors it is also very easy to do: we simply create a new processor and extend the creator class (PaymentService).

Where does this pattern shine?

When we have a structure that is repeated multiple times with different implementations.

Like a payment system. The core functionality is the same for all the variants but the implementation changes significantly.

Where is this pattern used?

It is used for example in ORMs that support a lot of database types.

The ORM has the same functionality (query a database, create an item...) for all the databases, but the implementation changes a lot if we use PostgreSQL or MongoDB, for example.

Where can I learn more about this pattern?

Go to one of the most reputable resources to learn about architectural patterns. Refactoring Guru

Good bye!

Hope this article helped you! If you have any doubts, please let me know in the comments.

Setting Up NestJS with Prisma (Without the Headache)

Xavier Carrera Gimbert — Tue, 18 Nov 2025 21:20:14 +0000

Starting a project with NestJS and Prisma should be easy, right? They’re both popular technologies and a great match. There are even official articles (1)(2) explaining how to integrate them.

Wrong.

For some reason, those articles are outdated. So here I am, writing this guide to save you a serious headache when setting up your project.

Let's Get to It

💡 Here is the final code of this set up project. Use it if you get stuck.

💡 I’ll be using pnpm for this project, but feel free to use any package manager you prefer.

1. Create the Project

You’ll be prompted to choose a package manager. Select pnpm if you want to follow this guide without changes. Otherwise, adapt as needed.

💡 At the time of writing, the latest version of @nestjs/cli appears to have a bug, so I'm using an older version. This may have been resolved by the time you're reading.

pnpm dlx @nestjs/cli@11.0.0 new nestjs-prisma-test

2. Set Up PostgreSQL with Docker

Create a Docker file:

touch docker-compose.yml

Add the following content:

# docker-compose.yml

version: '3.8'
services:
  postgres:
    image: postgres:13.5
    restart: always
    environment:
      - POSTGRES_USER=myuser
      - POSTGRES_PASSWORD=mypassword
    volumes:
      - postgres:/var/lib/postgresql/data
    ports:
      - '5432:5432'

volumes:
  postgres:

Run the container and keep the terminal open:

docker-compose up

3. Install Prisma

pnpm add prisma -D

Initialize Prisma:

pnpm dlx prisma init

4. Configure Environment Variables

Install dotenv:

pnpm add dotenv

Update your config files to load environment variables:

// prisma.config.ts
import 'dotenv/config';
// rest of the file...

// src/main.ts
import 'dotenv/config';
// rest of the file...

Update your .env file (remove any comments):

DATABASE_URL="postgres://myuser:mypassword@localhost:5432"

5. Define Your Models

Edit prisma/schema.prisma:

model User {
  id        Int      @id @default(autoincrement())
  email     String   @unique
  name      String
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

Run the initial migration:

pnpm dlx prisma migrate dev --name "init"

6. Install Prisma Client

pnpm add @prisma/client

💡 You don’t need to run generate now - Prisma does it automatically when installing the client. But for future schema changes, run:
pnpm dlx prisma generate

7. Create the Prisma Service

Note: We import from /client, not as shown in the official docs.

// src/services/prisma.service.ts

import { Injectable, OnModuleInit } from '@nestjs/common';
import { PrismaClient } from 'generated/prisma/client';

@Injectable()
export class PrismaService extends PrismaClient implements OnModuleInit {
  async onModuleInit() {
    await this.$connect();
  }
}

8. Register the Prisma Service

// src/app.module.ts

import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { PrismaService } from './services/prisma.service';

@Module({
  imports: [],
  controllers: [AppController],
  providers: [PrismaService],
})
export class AppModule {}

9. Use the Prisma Service

// src/app.controller.ts

import { Controller, Get } from '@nestjs/common';
import { PrismaService } from './services/prisma.service';

@Controller()
export class AppController {
  constructor(private readonly prismaService: PrismaService) {}

  @Get()
  async getUsers() {
    return this.prismaService.user.findMany();
  }
}

💡 This is a minimal setup and not production-ready. In a real app, you shouldn’t call a service directly from the controller. But this is a Prisma + NestJS set up tutorial - so I don’t care.

10. Run the Server

pnpm run start:dev

And that’s it! Populate your database and test the endpoint.

If you run into any issues, let me know in the comments. Hope you enjoyed the ride!

Your app idea is probably trash

Xavier Carrera Gimbert — Thu, 02 Oct 2025 15:37:57 +0000

Video version of this article: https://youtu.be/7xWl97seDIc?si=FkAh0ml6TCNcw5Om

All developers at some point in their lives have had this thought:

“I am gonna make an app and it is gonna be a success. I had an idea that no one else has had. I wonder how this amazing app does not exist already. It must be that I am the first to have it and have the determination to bring it to life. This is gonna be a great success!”

Sorry to break it to you, but you are probably gonna miserably fail with that. Unfortunately, you are probably not a genius. Sorry.

But let me explain to you why I think so.

You probably do not understand what the competition offers

All the apps and services that you use have a lot of issues for sure, but we sometimes tend to forget the things they do extremely well.

Maybe there is a very popular app with a clearly outdated interface that, on the other hand, offers great customer service and has great logistics! Or maybe there is an app that is slow and buggy but offers a product that you can only obtain there, and people are willing to deal with the shenanigans just because they really like the product.

Or maybe it is just that the app is old and it is used by a lot of people, so people do not want to switch because they prefer to deal with an imperfect app they trust than risk it with something they do not know about. Sometimes people are just not very brave.

There are even cases where the only thing the app offers compared to the competition is a big community of people using it. So consumers deal with the not-so-good parts of the app simply because they want to be part of a community. You do not want to be the guy with the most private, secure, and efficient messaging app that has no one to speak to because no one uses that app besides you.

So when comparing your idea to the existing ones, do not focus only on the things you can do better than the competition. But try to be realistic and think of the things the competition does better than you.

Things are more difficult than what you think

Products are not as easy to build as a lot of people want you to believe. It is very probable that you are underestimating the problems you will face down the road and overestimating your capabilities.

Building a product is not just the code. It is the infrastructure, it is the marketing, it is the design, it is the product part (establishing prices, conditions), it is the legal problems, it is the psychological aspect (I am sure you are very motivated now, but what about in a couple of months?).

As you can see, there are a lot of things that can go wrong, and if we acknowledge Murphy’s Law—“if something can go wrong, it will go wrong”—we will rapidly realize that a lot of things will go completely south during the app-building process.

So, please, before quitting your job to become the next Mark Zuckerberg, take into account the real effort you will have to deal with and all the problems that are surely gonna pop up.

Consumers do not know what they want

It is a fact of life. People (including me) love to talk about how things are bad and how things could be better if someone did what we just want. But in reality, when people face the consequences of what they want, you see that they clearly did not know what they wanted.

This especially happens with things related to privacy. Everyone will tell you how much they value privacy, but when we have to face reality and pick between privacy and comfort, we forget our higher values.

Black swans are more common than what you would think

Okay, let us consider that you are amazing, that you have been able to cover a necessity with a great app, and that you have been able to deal with all the problems involved with its creation and maintenance.

You are still not safe—you can encounter a black swan at any moment. What is a black swan, you may be asking yourself? According to Wikipedia:

“The black swan theory or theory of black swan events is a metaphor that describes an event that comes as a surprise, has a major effect, and is often inappropriately rationalized after the fact with the benefit of hindsight .”

In other words, the terrifying unexpected.

You may be developing the greatest app possible, but maybe one day you wake up and realize that some family member is ill and needs money for treatment, or maybe your house gets burned down, or maybe the relationship with your beautiful partner does not work out and now you have to deal with lawyers and a lot of mental stress.

But black swans are not only personal things. Maybe the app you are developing is great, but one day you wake up and realize that someone has just released a very similar app that does something very similar to yours. Or maybe you hire some employees and one day they all leave at once because they were contacted by a recruiter, and now suddenly you do not have a team anymore!

Or maybe a new technological breakthrough pops up that renders your product obsolete. Now what?!

Conclusion

I am by no means telling you not to follow your dreams—in fact, I would like to make another video complementing this one telling you to precisely do that.

What I want to avoid is you getting yourself ruined or in a great mess just because you did not think realistically.

So, in conclusion, follow your dreams, but please, do not ignore reality.

Thank you so much for watching this video! I really hope you like it.

And now it is time to say goodbye.

I send you a very big kiss, a very big hug, I remind you to never forget to be a good person, and I wish you happy coding.

Chao Chao!

Svelte vs React. Which one would I pick?

Xavier Carrera Gimbert — Tue, 04 Mar 2025 17:23:05 +0000

As a React developer, I’ve always been curious about Svelte. Everyone speaks highly of it, but I never had the chance to try it—until now.

In this blog post, I’ll share my first impressions of Svelte compared to React and discuss which one I’d pick for my next project.

The Similarities

Let’s start with what makes both frameworks similar.

The most important similarity is that they both rely on state, which, when changed, updates the DOM.

Of course, they use different syntax to declare and modify state, but the core principle remains the same.

For instance:

useState in React is $state in Svelte.
useEffect in React is $effect in Svelte.

The Core Differences

The key difference, in my opinion, is that React is essentially "JavaScript on steroids," whereas Svelte, thanks to its compiler, enables powerful functionality with minimal effort.

To illustrate:

In React, when you change the state, the component updates the Virtual DOM, compares it with the real DOM, and applies the necessary changes. If not handled properly, unnecessary Virtual DOM updates can be triggered, which isn’t a problem for small apps but can lead to performance issues in larger ones.
In Svelte, you don’t need hooks or special functions—just update a variable like any other, and Svelte applies changes directly to the DOM without the overhead of a Virtual DOM.
With React, you have to think in terms of re-renders. In Svelte, you simply update variables, and the framework takes care of the rest.

Here’s an example of the same logic implemented in React and Svelte so you can see how much simpler Svelte can be.

Svelte

<script>
    let name = $state("")

    function submitForm(event) {
        event.preventDefault()

        alert(`Your name is ${name}`)
    }
</script>

<form onsubmit={submitForm}>
    <label for="name">Enter your name:</label>
    <input id="name" bind:value={name} />
</form>

React

import { useState } from "react";

export default function NameForm() {
  const [name, setName] = useState("");

  const submitForm = (event) => {
    event.preventDefault();
    alert(`Your name is ${name}`);
  };

  return (
    <form onSubmit={submitForm}>
      <label htmlFor="name">Enter your name:</label>
      <input
        id="name"
        value={name}
        onChange={(e) => setName(e.target.value)}
      />
      <button type="submit">Submit</button>
    </form>
  );
}

As you can see, with Svelte, we declare the state using a simple variable, bind it to an input, and that’s all.

With React, we have to use hooks. In this case, it doesn’t make the code significantly more complex, but as the app grows and more advanced data structures like arrays and objects are used, hooks can become more cumbersome to manage.

So, Is Svelte Better?

From the example above, it might seem that Svelte is clearly superior. However, there’s a trade-off.

Its Unique Syntax

Since React is essentially JavaScript, once you learn its quirks, it feels natural to use. Svelte, on the other hand, has its own syntax and peculiarities that take time to learn.

For example:

In React, passing components as children is straightforward, you can have multiple components in a single file, and extracting reusable logic into hooks is easy.
In Svelte, having multiple components in a file requires workarounds, components can’t be passed as props, and separating logic from HTML requires specific conventions.

"That Doesn’t Seem Like a Big Deal!"

You’re right—learning a new syntax isn’t a huge issue, especially if it allows you to build logic more easily than React.

But there’s another drawback that makes me lean toward React for my next project.

React Has a Massive Ecosystem—Svelte Doesn’t

Because React is so popular, you can find a library for almost anything. With Svelte, it can be trickier.

Yes, Svelte’s ecosystem is growing, with tools like SvelteKit (which functions similarly to Next.js for React) and support for many JavaScript libraries. However, React's ecosystem is vast, with countless libraries, tutorials, and community resources.

For now, this makes React my go-to framework for larger projects.
So, Which One Should You Pick?

At the end of the day, the best tool is the one that helps you achieve your goals.

If your team is experienced in jQuery and PHP, those are the best tools for you.
If your team masters Svelte, use Svelte.
If you’re comfortable with React, stick with React.

Both React and Svelte are excellent frameworks, each with its strengths and weaknesses. Choose the one that fits your needs.

And if team composition and previous background don’t matter to you:

Pick React if having a big ecosystem of tutorials and libraries is important to you.
Pick Svelte if you highly value a more straightforward syntax.

Which One Will I Pick?

For big projects, I’ll stick with React because I know it well, and it has the largest ecosystem of libraries and tutorials.

However, I’ll continue exploring Svelte. I really enjoyed working with it, and who knows? Maybe I’ll discover I was wrong and end up using Svelte for my big projects.

Conclusion

React is king when it comes to libraries, tutorials, and community support.
Svelte is clean, efficient, and has less boilerplate but comes with its own quirks.

Try both and decide for yourself!

Additional Resources

Here are the best Svelte tutorials I found:

Svelte Crash Course
Svelte & SvelteKit Introduction

Other:
Simple todo app I build in svelte

Acknowledgments

Photo by Andres Ayrton: https://www.pexels.com/photo/woman-showing-apple-and-bitten-doughnut-6551415/