Forem: Robin Viktorsson

🎮 Learn Design Patterns: Build a “Monster Arena” Game and Master TypeScript Design Patterns (Part 1)

Robin Viktorsson — Fri, 01 Aug 2025 21:32:27 +0000

This article was originally published on Medium.

Design patterns aren’t just academic concepts — they’re practical tools that bring structure, clarity, and flexibility to your code. And what better way to learn them than by building a game?

In this two-part series, we’re creating a Monster Battle Arena in TypeScript and Node.js, where players summon goblins and dragons, assign them attack strategies, and trigger combat through an interactive terminal.

Part 1 focuses on implementing the core gameplay mechanics:

A central GameManager to manage game state
Adding players to the game
Summoning different types of monsters
Fighting monsters
Logging events to a UI terminal

Along the way, you’ll learn how to apply essential software design patterns with clean, practical examples:

🧙‍♂ Singleton — Centralized game state manager
⚔️ Strategy — Flexible monster attack behaviours
👁️ Observer — Real-time battle notifications
🏭 Factory — Dynamic monster creation
🎮 Command — Encapsulated terminal actions
🔁 State — Dynamic monster condition changes
🔗 Chain of Responsibility — Layered damage mitigation

Part 2 will evolve the existing logic with richer mechanics, new design patterns, enhanced UI interactions, and persistence — turning this codebase into a fully modular game simulation.

All gameplay is simulated via a terminal UI — proving that design patterns are not just powerful, but also fun to learn.

What Are Design Patterns? 🤔

Design patterns are tried-and-true solutions to common software design problems. Rather than reinventing the wheel every time we structure code, design patterns offer reusable templates that make your codebase more understandable, scalable, and maintainable.

They’re not libraries or frameworks, but language-agnostic blueprints that help you solve recurring architectural challenges — whether you’re building a backend service, a UI component, or, in our case, a game.

Think of them as battle-tested strategies used by experienced developers to communicate intent and reduce complexity.

Let’s Code the Monster Arena Game! 🛠️

With the core concepts of our game idea and design patterns under our belt, it’s time to bring them to life. In this section, we’ll dive into coding the Monster Arena step by step — from setting up your environment to implementing gameplay features like player management, monster summoning, and combat logic.

By following along, you’ll gain hands-on experience applying design patterns in a fun, practical, and interactive way.

1. Prerequisites 🧱

Ensure you have the following installed:

Node.js
npm (comes with Node.js)

2. Project Structure 📁

Initialize a Node.js project and generate a package.json file with default values using the npm init -y command. Create necessary directories and files. The final structure should look like this:

/monster-arena-game
├── node_modules/
├── src/                        
│   ├── core/  
│   │   ├── BattleSubject.ts                  
│   │   └── GameManager.ts            
│   ├── combat/                 
│   │   ├── AttackStrategy.ts        
│   │   └── DamageHandler.ts        
│   ├── logs/                          
│   │   └── ConsoleLogger.ts       
│   ├── factories/               
│   │   └── MonsterFactory.ts    
│   ├── ui/               
│   │   └── Terminal.ts  
│   └── commands/ 
│       ├── Command.ts
│       ├── AddPlayerCommand.ts
│       ├── SummonMonsterCommand.ts
│       ├── ShowPlayersCommand.ts
│       ├── ShowLogsCommand.ts                     
│       └── AttackMonsterCommand.ts           
├── package.json                
├── package-lock.json           
└── tsconfig.json

3. Install Dependencies 📦

Let’s set up the project with the necessary tools for a smooth TypeScript and Node.js development experience.

// Install TypeScript and related packages
npm install typescript ts-node @types/node

// Initialize the TypeScript configuration
npx tsc --init

Add a start script to your package.json:

"scripts": {
  "start": "ts-node src/index.ts"
}

This lets you run your game with a simple command: npm run start.

4. Singleton Pattern — Global Game Manager 🧙‍♂️

We begin with the Singleton Pattern, which ensures that a class has only one instance and provides a global point of access to it.

In our game, we use a GameManager to control player registration and manage shared game-wide state.

// src/core/GameManager.ts
import { Monster } from './Monster';

export class GameManager {
  private static instance: GameManager;
  private players: string[] = [];
  private monsters: Map<string, Monster> = new Map();

  private constructor() {}

  static getInstance(): GameManager {
    if (!GameManager.instance) {
      GameManager.instance = new GameManager();
    }
    return GameManager.instance;
  }

  addPlayer(name: string) {
    this.players.push(name);
    console.log(`[GameManager] ${name} joined the arena.`);
  }

  getPlayers(): string[] {
    return this.players;
  }

  addMonster(monster: Monster) {
    this.monsters.set(monster.name.toLowerCase(), monster);
    console.log(`[GameManager] ${monster.name} has entered the battlefield.`);
  }

  getMonster(name: string): Monster | undefined {
    return this.monsters.get(name.toLowerCase());
  }

  getMonsters(): string[] {
    return Array.from(this.monsters.keys());
  }
}

The Singleton pattern enforces a single source of truth for global game state — ideal for managing sessions, player data, and coordination logic.

5. Strategy Pattern — Monster Behaviours ⚔️

Monsters in our game attack in different ways — some slash with claws, others hurl fireballs. Instead of hardcoding behaviour, we define them as interchangeable strategies using the Strategy Pattern.

This pattern enables behaviour to be selected at runtime, keeping monster logic clean and flexible.

// src/combat/AttackStrategy.ts
export interface AttackStrategy {
  attack(monsterName: string): void;
}

export class MeleeAttack implements AttackStrategy {
  attack(name: string) {
    console.log(`[Strategy] ${name} performs a claw slash!`);
  }
}

export class RangedAttack implements AttackStrategy {
  attack(name: string) {
    console.log(`[Strategy] ${name} hurls a fireball!`);
  }
}

The Strategy pattern lets monsters dynamically switch their attack style (e.g., from melee to ranged) without altering their core structure.

6. Observer Pattern — Broadcast Battle Updates 👁️

During combat, we want to keep different parts of the system — like logs or future UI components — in sync with what’s happening. The Observer Pattern lets us broadcast important events to multiple listeners without tightly coupling them to the source.

Here’s how we implement it:

// src/core/BattleSubject.ts
export interface Observer {
  update(event: string): void;
}

export class BattleSubject {
  private observers: Observer[] = [];

  subscribe(observer: Observer) {
    this.observers.push(observer);
  }

  notify(event: string) {
    for (const obs of this.observers) obs.update(event);
  }
}

And here’s a simple observer that logs updates to the terminal:

// src/logs/ConsoleLogger.ts
import { Observer } from '../core/BattleSubject';

export class ConsoleLogger implements Observer {
  update(event: string): void {
    console.log(`[Observer] ${event}`);
  }
}

The Observer Pattern decouples the event source (e.g., monsters, combat actions) from the event handlers (e.g., console logs, UI panels). This makes the system more modular and extensible — you can add more observers (like a file logger, WebSocket publisher, or in-game notification panel) without changing the battle logic.

7. Monster Class With Strategy and State 🧬

Our Monster class leverages both the Strategy and State patterns. It uses Strategy to handle different attack styles and State to reflect changing health conditions (like being healthy, wounded, or critical).

// src/core/Monster.ts
import { AttackStrategy } from '../combat/AttackStrategy';
import { MonsterState, HealthyState } from './MonsterState';

export class Monster {
  private state: MonsterState = new HealthyState();

  constructor(
    public name: string,
    private strategy: AttackStrategy
  ) {}

  performAttack() {
    this.strategy.attack(this.name);
    this.state.handleState(this.name);
  }

  setAttackStrategy(strategy: AttackStrategy) {
    this.strategy = strategy;
  }

  setState(state: MonsterState) {
    this.state = state;
  }
}

This shows the power of composition over conditionals. We can change both attack behaviour and state-based responses cleanly and independently.

8. Factory Pattern — Summon Monsters Easily 🏭

Instead of manually creating monsters with specific configurations, we use the Factory Pattern to encapsulate creation logic.

// src/factories/MonsterFactory.ts
import { Monster } from '../core/Monster';
import { MeleeAttack, RangedAttack } from '../combat/AttackStrategy';

export class MonsterFactory {
  static create(type: 'goblin' | 'dragon'): Monster {
    switch (type) {
      case 'goblin': return new Monster('Goblin', new MeleeAttack());
      case 'dragon': return new Monster('Dragon', new RangedAttack());
      default: throw new Error('Unknown monster type');
    }
  }
}

The Factory pattern centralizes and abstracts the creation of complex objects. Need more monster types later? Just add a new case.

9. Command Pattern — Queue and Execute Attacks 🎮

The Command Pattern encapsulates requests as objects — perfect for queuing, logging, or undoing actions. Instead of invoking .performAttack() directly, we wrap it in a command object.

// src/commands/AttackMonsterCommand.ts
import { Command } from './Command';
import { GameManager } from '../core/GameManager';

export class AttackMonsterCommand implements Command {
  constructor(private name: string) {}

  execute(): void {
    const monster = GameManager.getInstance().getMonster(this.name);
    if (monster) {
      monster.performAttack();
    } else {
      console.log(`[Error] Monster "${this.name}" not found.`);
    }
  }
}

The Command pattern separates what should happen from when it happens — ideal for turn-based combat, replays, or action batching.

10. State Pattern — Monster Condition Handling 🔁

Monsters behave differently based on how injured they are. Instead of using conditionals everywhere, we apply the State Pattern to encapsulate each behaviour.

// src/core/MonsterState.ts
export interface MonsterState {
  handleState(name: string): void;
}

export class HealthyState implements MonsterState {
  handleState(name: string) {
    console.log(`[State] ${name} is strong and confident.`);
  }
}

export class WoundedState implements MonsterState {
  handleState(name: string) {
    console.log(`[State] ${name} is hurt but fighting.`);
  }
}

export class CriticalState implements MonsterState {
  handleState(name: string) {
    console.log(`[State] ${name} is barely alive.`);
  }
}

The State pattern eliminates complex if-else chains and allows you to swap state objects to change monster behaviour dynamically.

11. Chain of Responsibility Pattern — Damage Reduction 🔗

Incoming damage might be mitigated by multiple defences — like armour, shields, or magical wards. The Chain of Responsibility Pattern lets us pass damage through each handler in sequence.

// src/combat/DamageHandler.ts
export interface DamageHandler {
  setNext(handler: DamageHandler): DamageHandler;
  handle(damage: number): number;
}

export class ArmorHandler implements DamageHandler {
  private nextHandler?: DamageHandler;

  setNext(handler: DamageHandler): DamageHandler {
    this.nextHandler = handler;
    return handler;
  }

  handle(damage: number): number {
    const reduced = damage * 0.9;
    console.log(`[Chain] Armor reduced damage to ${reduced}`);
    return this.nextHandler?.handle(reduced) ?? reduced;
  }
}

export class ShieldHandler implements DamageHandler {
  private nextHandler?: DamageHandler;

  setNext(handler: DamageHandler): DamageHandler {
    this.nextHandler = handler;
    return handler;
  }

  handle(damage: number): number {
    const reduced = damage - 5;
    console.log(`[Chain] Shield blocked 5 points. New damage: ${reduced}`);
    return this.nextHandler?.handle(reduced) ?? reduced;
  }
}

Each handler focuses on its own logic and passes the result forward. New handlers (e.g., MagicBarrierHandler) can be added without modifying existing code.

12. Command Pattern: Powering the Terminal Interface 🧩

We’ve already used the Command pattern to encapsulate game actions. Now, let’s take it a step further — by turning our terminal into a fully interactive UI powered entirely by commands.

Every user input is parsed into a Command object, which is then executed. This clean separation allows us to decouple user input logic from game logic.

Command Interface 💻

A simple contract that ensures all commands implement the same execute method.

// src/commands/Command.ts
export interface Command {
  execute(): void;
}

AddPlayerCommand 👤

Adds a new player to the game through the GameManager.

// src/commands/AddPlayerCommand.ts
import { Command } from './Command';
import { GameManager } from '../core/GameManager';

export class AddPlayerCommand implements Command {
  constructor(private name: string) {}

  execute(): void {
    GameManager.getInstance().addPlayer(this.name);
  }
}

SummonMonsterCommand 🐲

Creates and adds a monster (goblin or dragon) to the arena, then triggers its attack behavior.

// src/commands/SummonMonsterCommand.ts
import { Command } from './Command';
import { MonsterFactory } from '../factories/MonsterFactory';
import { GameManager } from '../core/GameManager';

export class SummonMonsterCommand implements Command {
  constructor(private type: 'goblin' | 'dragon') {}

  execute(): void {
    const monster = MonsterFactory.create(this.type);
    GameManager.getInstance().addMonster(monster);
  }
}

ShowPlayersCommand 👥

Displays a list of all current players in the game.

// src/commands/ShowPlayersCommand.ts
import { Command } from './Command';
import { GameManager } from '../core/GameManager';

export class ShowPlayersCommand implements Command {
  execute(): void {
    console.log('[Players]', GameManager.getInstance().getPlayers());
  }
}

ShowLogsCommand 📜

Outputs a placeholder log message (you can expand this later with Event Sourcing).

// src/commands/ShowLogsCommand.ts
import { Command } from './Command';

export class ShowLogsCommand implements Command {
  execute(): void {
    console.log('[Logs] No persistent log storage yet.');
  }
}

Terminal: Parsing Commands and Executing Actions 👩‍💻

This class powers our command-line interface. It reads user input, translates it into commands, and runs them. It keeps UI logic separate from game mechanics.

// src/ui/Terminal.ts
import readline from 'readline';
import { AddPlayerCommand } from '../commands/AddPlayerCommand';
import { SummonMonsterCommand } from '../commands/SummonMonsterCommand';
import { ShowPlayersCommand } from '../commands/ShowPlayersCommand';
import { Command } from '../commands/Command';
import { GameManager } from '../core/GameManager';
import { AttackMonsterCommand } from '../commands/AttackMonsterCommand';

export class Terminal {
  private rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout,
  });

  start() {
    console.log('Welcome to the Monster Battle Game!');
    this.printHelp();
    this.prompt();
  }

  private printHelp(): void {
    console.log('\nAvailable commands:');
    console.log('  add-player <name>         - Add a new player');
    console.log('  summon-monster <type>     - Summon a monster (goblin or dragon)');
    console.log('  attack <monsterName>      - Make a monster attack');
    console.log('  show-players              - Show all current players');
    console.log('  help                      - Show this help menu');
    console.log('  exit                      - Quit the game');
  }

  private prompt() {
    this.rl.question('> ', (input) => {
      const [command, ...args] = input.trim().split(' ');

      if (command === 'help') {
        this.printHelp();
      } else if (command === 'exit') {
        console.log('Exiting game. Goodbye!');
        this.rl.close();
        return;
      } else {
        const cmd = this.createCommand(command, args);
        if (cmd) cmd.execute();
        else console.log('Unknown command or invalid arguments. Type "help" to see available options.');
      }

      this.prompt();
    });
  }

  private createCommand(command: string, args: string[]): Command | null {
    switch (command) {
      case 'add-player':
        if (!args[0]) return null;
        return new AddPlayerCommand(args[0]);

      case 'summon-monster':
        if (args[0] !== 'goblin' && args[0] !== 'dragon') return null;
        return new SummonMonsterCommand(args[0] as 'goblin' | 'dragon');

      case 'attack': {
        const name = args[0]?.toLowerCase();
        if (!name) return null;

        const monster = GameManager.getInstance().getMonster(name);
        if (!monster) {
          console.log(`[Error] Monster "${args[0]}" not found.`);
          return null;
        }

        return new AttackMonsterCommand(monster.name);
      }

      case 'show-players':
        return new ShowPlayersCommand();

      default:
        return null;
    }
  }
}

14. Initializing the Game Runtime ⚙️

Let’s wire everything together by creating the main entry point of the application. This is where your Monster Arena game kicks off and the terminal interface comes to life.

// src/index.ts
import { Terminal } from './ui/Terminal';

new Terminal().start();

This simple snippet initializes the terminal UI and starts listening for user input, allowing players to join the game, summon monsters, and initiate battles — all from the command line.

15. Running the Game ▶️

The game can be started using the following command:

npm run start

You’ll be greeted with the interactive terminal interface, ready for action. Here’s a quick example of what a session might look like:

C:\Users\monster-arena-game> npm run start

> monster-arena-game@1.0.0 start
> ts-node src/index.ts

Welcome to the Monster Battle Game!

Available commands:
  add-player <name>         - Add a new player
  summon-monster <type>     - Summon a monster (goblin or dragon)
  attack <monsterName>      - Make a monster attack
  show-players              - Show all current players
  help                      - Show this help menu
  exit                      - Quit the game
> add-player Robin
[GameManager] Robin joined the arena.
> show-players
[Players] [ 'Robin' ]
> summon-monster dragon
[GameManager] Dragon has entered the battlefield.
> attack dragon
[Strategy] Dragon hurls a fireball!
[State] Dragon is strong and confident.
> help

Available commands:
  add-player <name>         - Add a new player
  summon-monster <type>     - Summon a monster (goblin or dragon)
  attack <monsterName>      - Make a monster attack
  show-players              - Show all current players
  help                      - Show this help menu
  exit                      - Quit the game
> exit
Exiting game. Goodbye!

And just like that — you’ve created a fully functional, design-pattern-powered monster game right in your terminal. But this is only the beginning.

In Part 2 of this series, we’ll deepen the architecture by refining existing code base, introducing new design patterns, and adding exciting features: a turn-based system for player actions, health and life mechanics for both players and monsters, plus loot and experience systems to level up your gameplay, and more.

Conclusion 📣

Design patterns are more than just theoretical concepts — they’re practical tools that can transform your code from a tangled mess into a well-structured, flexible system. By building the Monster Arena game, you’ve seen first-hand how these patterns can be applied to solve common software design challenges in a modular and maintainable way.

From managing global state with Singleton, to crafting dynamic monster behaviours using Strategy and State, to enabling real-time updates with Observer, and streamlining object creation with Factory, each pattern brought a unique and powerful advantage to our game architecture. Wrapping actions in Command objects not only made our game logic cleaner but also paved the way for an extensible terminal UI. And finally, the Chain of Responsibility pattern showed how layered logic like damage mitigation can be elegantly handled.

This hands-on project proves that design patterns are not just abstract ideas — they’re practical, approachable, and fun. Whether you’re building games, web apps, or backend services, mastering these patterns in TypeScript will empower you to write cleaner, more scalable, and easier-to-maintain code.

🙏 Thanks for reading to the end! If you have any questions, feel free to drop a comment below. But I am also curious. Would you have designed it different? Can you find flaws with this design? Let me know and we'll discuss it 😊

If you enjoyed this article, follow me on Medium and social media — I’d love to connect and follow you back:

Robin Viktorsson (@robinviktorsson) / Medium
Robin Viktorsson (@robinviktorsson) / X
Robin Viktorsson (@robinviktorsson@mastodon.social) — Mastodon

5 Practices That Help Me Grow as a Software Developer (and Engineer)

Robin Viktorsson — Sun, 06 Jul 2025 10:15:18 +0000

This article was originally published on Medium.

Let’s be real — becoming a skilled, professional software developer is no easy feat. It takes years (sometimes decades) to truly master this craft. Without a deliberate effort to grow daily, it’s easy to get stuck in the same place, falling behind in an industry that evolves faster than any other.

That’s why I’ve adopted these five practices. They’ve helped me sharpen my skills, stay current, and cultivate a mindset that’s always evolving.

1. Feed the Hunger 🍽️🔥

What do I mean by “feed the hunger”? To grow as a software developer, you need more than just a job — you need a genuine curiosity for the craft. I call it hunger. It is the desire to explore new programming languages, dig into architectural patterns, experiment with frameworks, absorb new ideas, etc.

Every day, I attempt to feed this hunger by either:

Reading blog posts, technical articles, or software-related books
Writing blog posts like this one (teaching is learning!)
Exploring source code on GitHub
Solving coding challenges
Learning new tools and methodologies (e.g. testing methodologies, diagramming tools, etc)

Whether it’s 10 minutes or an hour, I noticed that consistency matters more than time. Keep feeding that curiosity, and it will reward you with growth.

P.S. I added links in the list above to hint at what I’m currently exploring.

2. Code Like a Chef 👨‍🍳💻

Yes, I’m comparing coding to cooking — Oh god, another food metaphor. I must be hungry. Let me grab a sandwich. Okay, back. The goal is to approach code like a Michelin-star chef: with planning, care, creativity, and the occasional Gordon Ramsay scream (internally, of course).

Let’s start with planning. Like chefs prepping ingredients the night before, I reflect on challenges before bed or in the shower. Oddly enough, solutions often bubble up when I’m not actively coding. This tiny habit helps me fruit ideas of how I can approach the challenge when waking up tomorrow. This gives me a head start the next day, armed with fresh ideas and a pinch of optimism.

Regarding care: Just like chefs carefully follow a recipe, I keep software requirements front and center while coding. I stay mindful of design principles and best practices to ensure my code is clean, reliable, maintainable, and testable. I also regularly check in with whoever defined the system design — or reflect on my own intent — to make sure I’m on track. This alignment habit usually results in code I can feel proud of.

If you want to dive deeper, here are two of my previous articles (published on Medium.com) covering key principles I rely on:

And don’t forget to taste test your code! Just like chefs sampling their dish before serving, I regularly test and review my code. That means writing thorough tests and refactoring whenever something tastes off — whether it’s too complex, too slow, or just confusing. A well-tested codebase is like a perfectly balanced meal: reliable and enjoyable for everyone.

About creativity. Just like a chef experiments with new spices and flavour combinations, I like to bring creativity into my code. This means trying out new patterns, exploring different libraries, or finding clever solutions to tricky problems — without sacrificing clarity or quality. I’m not afraid to remix familiar ingredients in fresh ways, whether it’s refactoring legacy code or architecting a new feature from scratch. Creativity keeps coding exciting and helps me grow beyond just “making it work” to crafting something elegant and enjoyable to maintain.

3. Share (or Ask for) the Recipe 🔄📖

Alright — we’re way deep into the food metaphor now, so let’s just roll with it. Sharing recipes is what makes great meals — and great teams — possible.

Don’t keep your secret sauce to yourself. Tap into the wisdom of your colleagues at all levels: seniors, mediors, and juniors alike. Use every opportunity — system design reviews, code reviews, pair programming sessions — to exchange ideas and gather constructive feedback. These reviews aren’t just hoops to jump through; they’re chances to refine your code and learn new techniques.

I make it a point to both give and receive feedback regularly because knowledge sharing is like passing down a treasured family recipe. When you teach others, you deepen your understanding and help raise the overall quality of the kitchen — er, team.

Remember: seniors bring hard-earned experience, mediors offer solid knowledge and fresh perspectives, and juniors inject new energy and innovative ideas. By blending these insights, you create a richer, more flavourful learning environment that benefits everyone.

So don’t be shy — share your recipe and ask for theirs. The best cooks don’t cook alone; they learn from and inspire each other every day. That’s why I enjoy sharing stories on Dev.to 🥳

4. Respect the Timing ⏳🍳

Just like cooking requires the right timing — too fast, and the dish is raw; too slow, and it’s overdone — software development needs a balance between speed and patience, and the stakeholders needs to understand this. Rushing can introduce bugs or technical debt, while endless tweaking delays delivery.

I remind myself to trust the process, ship incrementally, and polish thoughtfully over time. Good things take time to mature, whether it’s a soufflé or a software feature.

5. Plate Your Work Nicely 🎨🍽️

Presentation matters — whether it’s a gourmet meal or your codebase. I try to “plate” my work by writing clear, readable, and well-documented code so others can easily understand and enjoy it.

Just like a beautifully arranged dish invites people to dig in, well-organized code invites collaboration and makes debugging or extending features a breeze. Good code is not just about functionality; it’s about creating an experience that’s pleasant for your teammates — and your future self.

Conclusion: Keep Cooking, Keep Growing 📣

Becoming a great software developer isn’t a destination — it’s a journey that requires passion, patience, and continuous effort. By feeding your hunger for knowledge, coding thoughtfully like a chef, sharing your recipes, respecting timing, and plating your work with care, you set yourself up for meaningful growth.

Remember, growth isn’t about perfection or rushing to the finish line. It’s about cultivating habits that nourish your skills and mindset every day. So keep cooking your craft with intention and curiosity — your future self will thank you.

🙏 Thanks for reading to the end! If you have any questions, feel free to drop a comment below.

If you enjoyed this article, follow me on Medium and social media — I’d love to connect and follow you back:

Robin Viktorsson (@robinviktorsson) / Medium
Robin Viktorsson (@robinviktorsson) / X
Robin Viktorsson (@robinviktorsson@mastodon.social) — Mastodon

Setting Up a Modern TypeScript Project with esbuild (No Framework)

Robin Viktorsson — Mon, 07 Apr 2025 19:36:49 +0000

This article was originally published on Medium.

Modern web development focuses on building fast, scalable, and maintainable applications — and choosing the right tools is essential to achieving that. If you’re working with TypeScript, you’re already prioritizing structure, type safety, and maintainability. But to transform your TypeScript code into a fully functioning, production-ready web application, you need more than just the TypeScript compiler (tsc) — you need a bundler. This is where esbuild comes in.

While the TypeScript compiler does an excellent job of transpiling your TypeScript into JavaScript, it doesn’t handle bundling, asset optimization, or other features that streamline both development and production workflows. esbuild steps in to fill these gaps by acting as a fast and efficient bundler that understands your project’s structure, optimizes assets, and produces performant output suitable for the browser.

In this guide, we’ll walk through creating a TypeScript project from scratch using esbuild as the bundler — without relying on any frameworks. You’ll learn how to compile TypeScript, serve files locally with live reloading, handle assets like CSS and images, and optimize your build for production with features such as tree shaking and minification.

Whether you’re diving into bundlers for the first time, building a lightweight utility, or laying the groundwork for a larger application, this hands-on tutorial will give you the confidence to leverage esbuild’s speed and efficiency to optimize your development and production workflows.

Sit back, grab some popcorn 🍿, and enjoy the read!

What is esbuild (as a Bundler)? 🤔

When using the TypeScript compiler (tsc), your code is compiled into individual .js files without bundling. While this maintains project organization, it doesn't optimize performance. Modern applications require a bundler to consolidate code, resolve dependencies, and optimize bundles, improving load times and performance. Bundlers also enable techniques like tree-shaking and dead code elimination (CDE), which remove unused code, further reducing file size. Additionally, they ensure compatibility across various module formats and environments and can handle assets like CSS and images. Features like code splitting and hot module replacement (HMR) make bundlers indispensable for optimizing both development and production workflows.

esbuild is an ultra-fast JavaScript bundler and minifier, designed to be both powerful and simple. The key to esbuild’s speed lies in its implementation. Unlike other bundlers written in JavaScript, esbuild is written in Go, a compiled systems language. This allows it to leverage parallelism and low-level optimizations that result in builds that are often 10–100x faster than tools like Webpack or Rollup.

At its core, esbuild is a bundler — meaning it takes multiple source files (JavaScript, TypeScript, JSX, etc.), resolves their dependencies, and combines them into optimized output files for the browser or Node.js. But esbuild goes beyond simple bundling by offering a complete toolchain for modern frontend development. This process includes key features such as:

Tree-Shaking: esbuild has built-in support for tree-shaking, automatically removing unused code from the final bundle. This results in smaller and more efficient output files — especially valuable in large TypeScript projects where minimizing bundle size directly improves load performance and runtime efficiency.
Asset Management: While esbuild primarily focuses on JavaScript, TypeScript, and CSS, it can be extended to handle static assets like images and fonts via plugins or external tools. With the right setup, esbuild can efficiently include and optimize these assets in your build pipeline, making it a flexible option for production-ready applications.
Plugins and Extensibility: esbuild supports a lightweight plugin API, allowing you to customize how files are processed. Although its plugin ecosystem is still growing compared to other bundlers (e.g. Webpack), esbuild covers many common needs out of the box, such as TypeScript transpilation, JSX transformation, and minification, without requiring complex configurations.
Development Experience: Thanks to its blazing speed, esbuild significantly improves the development experience. It can rebuild large projects in milliseconds, enabling rapid feedback loops. While esbuild doesn’t provide built-in Hot Module Replacement (HMR), it integrates well with tools like Vite or custom dev servers that offer live reloading and HMR support.

Overall, esbuild’s modern architecture and focus on speed make it a great choice for bundling TypeScript projects, especially when quick builds and simple configuration are key. While it may lack some of the deep customization and mature ecosystem of Webpack and Vite, its performance, simplicity, and native TypeScript support make it ideal for many modern web development workflows.

Creating a TypeScript Project with esbuild 👨‍💻

Creating a TypeScript project with esbuild is a great way to learn the modern JavaScript build process, optimize your applications, and gain hands-on experience with fast, lightweight tooling. While many web frameworks offer built-in TypeScript and bundling configurations, there are plenty of scenarios where a minimal, framework-free approach is more appropriate.

Whether you’re building a command-line utility, developing a modular JavaScript/TypeScript library, or simply experimenting with esbuild’s blazing-fast capabilities, this guide will walk you through setting up a TypeScript project from scratch using esbuild as the bundler.

We’ll cover everything from initializing a Node.js project to configuring esbuild, compiling TypeScript, running a lightweight development server, and preparing your project for production. With esbuild and TypeScript, you can create a lean, efficient, and production-ready build system — all while maintaining complete control over your development workflow.

1. Prerequisites 🧱

Ensure you have the following installed:

Node.js
npm (comes with Node.js)

2. Project Structure 📁

Let’s begin by setting up the foundational structure of our project. We’ll initialize a new Node.js project and generate a package.json file with default values using the npm init -y command. Continue to create the necessary directories and files for our TypeScript and esbuild setup:

// Note: 'touch' is not available in Windows, instead create file manually

mkdir ts-esbuild-app
cd ts-esbuild-app
npm init -y

# Create source and assets directory alongside its files
mkdir src
cd src
touch index.html
touch index.ts
touch styles.css
touch assets.d.ts

mkdir assets
cd assets
touch logo.png 

# Create output directory and index.html
cd ../..
mkdir dist

After running the commands, your project directory should look like this:

ts-esbuild-app/
├── dist/
├── src/
│   └── index.ts
│   └── index.html
│   └── assets.d.ts
│   └── styles.css
│   ├── assets/
│   │   └── logo.png
├── package.json

This structure separates your source code (src/) from your build output (dist/), which is a best practice in most modern web projects. We'll populate and refine the contents of all files in the upcoming sections as we configure TypeScript and esbuild.

3. Install Dependencies 📦

Now that we have our project structure in place, it’s time to install the essential development tools that will allow us to compile TypeScript and bundle our project with esbuild. Run the following command to install the required dependencies as development-only packages:

npm install --save-dev typescript esbuild live-server @types/node

Here’s an overview of the purpose of each of these packages:

esbuild: The core bundler that takes your files and dependencies (JS, CSS, images, etc.) and outputs optimized bundles.
live-server: Serves your app locally with live reloading and Hot Module Replacement (HMR) at http://127.0.0.1:8080 or your configured port.
typescript: The TypeScript compiler (tsc) for writing .ts files and compiling them to JavaScript.

These are added as dev dependencies (--save-dev) because they’re only needed during development and build time—not at runtime. With these tools, you now have a full TypeScript + esbuild setup: write in TypeScript, compile and bundle with esbuild, and develop locally with live reloading (if you installed live-server).

4. Create `tsconfig.json` ✍️

To configure how TypeScript compiles your project, you need to create a tsconfig.json file. This file serves as the central configuration for the TypeScript compiler (tsc), allowing you to define the compiler options, project structure, and file inclusion patterns. To generate this file, run the following command in your project root:

npx tsc --init

This command creates a tsconfig.json file with a default set of compiler options. You can then customize it to fit the needs of your project. Here’s a recommended configuration for a modern TypeScript + esbuild setup:

{
  "compilerOptions": {
    "target": "ES6",
    "module": "ESNext",
    "moduleResolution": "node",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "./dist"
  },
  "include": ["src"]
}

The tsconfig.json file contains various compiler options that guide TypeScript in how it should compile your code.

"target": "ESNext" tells TypeScript to compile your code down to latest available ECMAScript JavaScript version. This ensures modern language features are supported while maintaining reasonable browser compatibility.
"module": "ESNext" instructs TypeScript to output native ES module syntax (import/export). This is necessary for esbuild to perform advanced bundling techniques like tree-shaking.
"moduleResolution": "node" uses Node.js-style module resolution, which is compatible with most bundling and package systems. This means TypeScript will mimic how Node.js resolves import paths.
"outDir": "./dist" specifies the directory where compiled JavaScript files should be emitted. In this setup, all output files will go to the dist folder.
"esModuleInterop": true enables interoperability between CommonJS and ES Module systems. This allows you to seamlessly import packages that use module.exports (CommonJS), such as many Node.js packages.
"strict": true enables all of TypeScript’s strict type-checking options. This helps catch potential bugs early and enforces best practices in your codebase.
"skipLibCheck": true skips type checking of external declaration files (e.g., from node_modules). This speeds up compilation and avoids unnecessary type conflicts from third-party packages.
"include": ["src"] tells TypeScript to only include and compile files located in the src folder. This helps keep the build focused and fast by excluding unnecessary files.

These settings work together to create an efficient, modern, and maintainable TypeScript development environment. They ensure compatibility with esbuild, optimize your build speed, and enable strong typing throughout your codebase.

5. Create `esbuild.config.ts` ⚙️

Now that we’ve set up TypeScript, it’s time to configure esbuild — the tool responsible for bundling your code and preparing it for the browser. Create a new file called esbuild.config.ts in the root of your project. This file will define how esbuild handles your source files, compiles TypeScript, and serves your application during development. Here’s a minimal yet effective configuration:

import esbuild from 'esbuild';
import path from 'path';

// Define the output directory for your build
const outDir = path.resolve(__dirname, 'dist');

// Create the esbuild build configuration
esbuild.build({
  entryPoints: ['src/index.ts'], // Main entry point (change as needed)
  bundle: true, // Enable bundling
  format: 'esm',
  outfile: path.join(outDir, 'index.js'), // Output file
  sourcemap: true, // Generate sourcemaps
  minify: true, // Minify the output for production
  assetNames: 'assets/[name]-[hash]', // Asset file naming convention with hash for cache busting
  loader: {
    '.png': 'file', // Handle PNG images
    '.jpg': 'file', // Handle JPEG images
    '.css': 'css', // Handle CSS files
    '.ts': 'ts', // Handle TypeScript files (optional, as esbuild does this by default)
  },
  external: [], // Exclude specific modules from being bundled (e.g., node_modules)
  define: {
    'process.env.NODE_ENV': '"production"', // Define environment variables for optimization
  }
}).catch(() => process.exit(1)); // Exit on error

The esbuild.config.ts file is a configuration file used by esbuild, a lightning-fast JavaScript and TypeScript bundler. It defines how esbuild should process, bundle, and optimize your project’s source files, including JavaScript, TypeScript, CSS, and other assets. Through this configuration, you can customize the build process by specifying entry points, output formats, target environments, external dependencies, and plugin integrations. While esbuild favors simplicity and minimal configuration, the config file allows for advanced customization when needed, especially for large or complex projects.

The importance of the esbuild.config.ts file lies in its ability to deliver extremely fast builds with powerful customization. It enables you to fine-tune how files are compiled and bundled, optimize your output for production with built-in minification, and define build-time constants using environment variables. With support for plugins and watch mode, you can extend esbuild’s capabilities and enhance the development experience. Whether you're building a small library or a large application, esbuild.config.ts provides the flexibility and speed to efficiently manage your build process.

6. Create Sample Code 💻

Let’s add a small piece of TypeScript to verify that everything is wired up correctly. In the src/index.ts file, add the following simple function that logs a personalized greeting to the console:

import './styles.css'; // We will populate this file in next sub-chapter
import logo from './assets/logo.png'; // Will throw a TypeScript error which we will resolve later

function greet(name: string): void {
  const heading = document.createElement('h1');
  heading.textContent = `Hello, ${name}!`;
  document.body.appendChild(heading);

  const img = document.createElement('img');
  img.src = logo;
  img.alt = 'Project Logo';
  img.style.width = '200px';

  document.body.appendChild(img);
}

greet('TypeScript + esbuild');

This minimal example serves as a sanity check to ensure TypeScript compiles properly and the esbuild bundler is functioning as expected.

You will get an TypeScript error “Cannot find module ‘./assets/logo.png’ or its corresponding type declarations.ts(2307)”. Ignore this for now. We will resolve it in the upcoming chapter 8. Bundle Images.

Next, let’s create a basic HTML file to load the compiled JavaScript bundle into the browser. In the src/index.html file, add the following code:

This HTML page simply loads the `index.js` file that esbuild will generate after compilation. Once the esbuild live server is running, this file will be served at `http://127.0.0.1:8080`, and the greeting should appear in your browser's developer console.

With just these two files — `index.ts` and `index.html` — you now have a basic but working TypeScript + esbuild setup ready for further development.

7. Add and Bundle CSS 🎨

Now that your TypeScript and esbuild setup is working, let’s take it a step further and add support for CSS. esbuild can also bundle stylesheets, making it easy to manage CSS alongside your TypeScript files. Add an src/styles.css file which contains some simple styling:

body {
  background-color: #f0f0f0;
  font-family: sans-serif;
  padding: 2rem;
}

h1 {
  color: #3366ff;
}

This works because you added this loader in esbuild.config.ts:

loader: {
    '.png': 'file',
    '.css': 'css',
},

esbuild handles .css files directly if you use the loader: { '.css': 'css' } configuration. CSS is bundled into your final output, or injected depending on your preference.

8. Bundle Images 🖼️

To include images in your TypeScript + esbuild project, you need to configure esbuild to handle static assets like .png, .jpg, .svg, and more. We already created a logo.png while setting up the folder structure.

import logo from './assets/logo.png';

However, our import of the logo.png file in index.ts is still throwing this error: “Cannot find module ‘./assets/logo.png’ or its corresponding type declarations.ts(2307)”. To solve this, add the following to assets.d.ts:

declare module '*.png' {
    const value: string;
    export default value;
}

To make it available in the final dist/ folder, we’ll add the following parameter to out build script --loader:.png=file, but this is something we will add in the next chapter, so hold your horses for now.

When you run the build, your image (e.g., logo.png) will be available in the output folder, and your code will reference it correctly thanks to the static module declaration. If you're using something like live-server to serve your files, it will serve the image alongside your HTML and JavaScript, ensuring it displays properly in the browser.

9. Add Scripts in `package.json` 🔨

In the package.json file, you can define custom scripts to automate common development tasks. These scripts serve as shortcuts for commands you’d otherwise need to run manually in the terminal. When working with esbuild, you can set up similar build and start scripts to handle both development and production workflows.

Start by adding the following entries under the "scripts" section in your package.json:

"scripts": {
  "build": "esbuild --bundle src/index.ts --minify --loader:.png=file src/index.html --loader:.html=copy --outdir=dist",
  "start": "npm run build && live-server dist"
}

The build script runs esbuild to bundle your TypeScript project. It takes the src/index.ts file as the entry point, bundles it along with its dependencies, outputs it to the dist/ folder as index.js, and minifies the output for production use. You can also configure this further using an esbuild.config.ts file for more advanced setups.
The start script uses live-server to serve the content from your dist/ folder at http://127.0.0.1:8080 by default. Unlike Webpack’s Dev Server, esbuild doesn’t include a built-in dev server with Hot Module Replacement (HMR). However, live-server provides automatic reloading whenever files in the dist/ folder change, giving you a simple and effective way to preview changes during development.

These scripts make it easy to build and serve your project without needing to remember long terminal commands, improving your development experience and keeping your workflow efficient.

10. Run the Project ▶️

Once you’ve added the scripts to your package.json, you’re ready to start developing your project using esbuild along with a lightweight development server. To launch the server and view your project in the browser, simply run the following command in your terminal:

npm start

This command starts live-server, which serves your dist/ folder and opens the project in your default web browser at http://127.0.0.1:8080 (or another available port if that one’s taken).

C:\Users\Robin\ts-esbuild-app>npm run start

> ts-esbuild-app@1.0.0 start
> npm run build && live-server dist


> ts-esbuild-app@1.0.0 build
> esbuild --bundle src/index.ts --minify --loader:.png=file src/index.html --loader:.html=copy --outdir=dist


  dist\index.js           302b 
  dist\index.html         210b 
  dist\index.css           81b 
  dist\logo-55DNWN2R.png    0b 

Done in 9ms
Serving "dist" at http://127.0.0.1:8080
Ready for changes

The server watches your output files for changes. So every time you re-run the build command (for example, after editing a TypeScript or CSS file), live-server will automatically refresh the browser to show your latest updates. This live-reloading behavior speeds up your development workflow by keeping your browser in sync with your code—no need to manually refresh the page.

While esbuild doesn’t provide Hot Module Replacement (HMR) out of the box like some other bundlers (e.g. Webpack), this simple setup with live-server gives you a fast, zero-config way to preview changes in real-time and iterate quickly as you build your project.

11. Build the Project ⚒️

While the start script is great for development, the build script is essential when you’re ready to prepare your project for production. Running npm run build will trigger esbuild to bundle and optimize your project for deployment.

npm run build

This command tells esbuild to execute the bundling process according to the configuration set in your esbuild.config.ts file (or esbuild options specified in the script). By default, esbuild will process all your assets—JavaScript, TypeScript, images, and CSS—and output them into the dist/ directory.

C:\Users\Robin\ts-esbuild-app>npm run build

> ts-esbuild-app@1.0.0 build
> esbuild --bundle src/index.ts --minify --loader:.png=file src/index.html --loader:.html=copy --outdir=dist


  dist\index.js           302b 
  dist\index.html         210b 
  dist\index.css           81b 
  dist\logo-55DNWN2R.png    0b 

Done in 9ms

If you’ve configured esbuild to run in production mode (by using the --minify flag, which we did, or through the build configuration), esbuild will automatically apply a series of optimizations to the output files. These optimizations include:

Minification: esbuild will remove unnecessary whitespace, comments, and unused code from your JavaScript and TypeScript files, reducing their size significantly.
Tree-shaking: esbuild will eliminate any unused code that isn’t referenced anywhere in your project, further reducing the bundle size.
Asset optimization: While esbuild doesn’t handle image optimization by default, you can easily use plugins (like esbuild-plugin-image) to process image files and optimize them during the build.

Once the build process completes, you’ll find your bundled JavaScript in the dist/ directory (e.g., dist/index.js). This version of your application is optimized for performance and is ready for production deployment.

By using the build command, you ensure that your project is fully optimized and prepared to be served to users with the best possible performance.

Conclusion 📣

In this guide, we’ve explored how to create a lightweight, framework-free TypeScript project using esbuild. From setting up the project structure to configuring esbuild and enabling TypeScript compilation, you now have a streamlined, production-ready environment. Along the way, we’ve touched on key topics such as tree shaking, asset management, and optimizing both development and production builds for performance.

While frameworks like React or Angular come with pre-configured setups, using a custom TypeScript and esbuild configuration offers you complete control over your build process. This approach is especially beneficial for modular libraries, utilities, or smaller applications that don’t require the overhead of a full framework.

By harnessing esbuild’s fast bundling and optimization capabilities, you can reduce load times and enhance performance. These improvements make your project more efficient and scalable, enabling it to grow from small utilities to large-scale applications, all while keeping things lightweight.

Whether you’re new to TypeScript and esbuild or refining your existing workflow, this guide provides a solid foundation for building, bundling, and optimizing modern JavaScript applications. With a deep understanding of esbuild’s features, you’re now equipped to handle complex web projects with complete control over your application’s build process.

🙏 Thanks for reading to the end! If you have any questions, feel free to drop a comment below.

If you enjoyed this article, follow me on Medium and social media — I’d love to connect and follow you back:

Robin Viktorsson (@robinviktorsson) / Medium
Robin Viktorsson (@RobinViktorsson) / X
Robin Viktorsson (@robinviktorsson@mastodon.social) — Mastodon

Forem: Robin Viktorsson

🎮 Learn Design Patterns: Build a “Monster Arena” Game and Master TypeScript Design Patterns (Part 1)

What Are Design Patterns? 🤔

Let’s Code the Monster Arena Game! 🛠️

1. Prerequisites 🧱

2. Project Structure 📁

3. Install Dependencies 📦

4. Singleton Pattern — Global Game Manager 🧙‍♂️

5. Strategy Pattern — Monster Behaviours ⚔️

6. Observer Pattern — Broadcast Battle Updates 👁️

7. Monster Class With Strategy and State 🧬

8. Factory Pattern — Summon Monsters Easily 🏭

9. Command Pattern — Queue and Execute Attacks 🎮

10. State Pattern — Monster Condition Handling 🔁

11. Chain of Responsibility Pattern — Damage Reduction 🔗

12. Command Pattern: Powering the Terminal Interface 🧩

Command Interface 💻

AddPlayerCommand 👤

SummonMonsterCommand 🐲

ShowPlayersCommand 👥

ShowLogsCommand 📜

Terminal: Parsing Commands and Executing Actions 👩‍💻

14. Initializing the Game Runtime ⚙️

15. Running the Game ▶️

Conclusion 📣

5 Practices That Help Me Grow as a Software Developer (and Engineer)

1. Feed the Hunger 🍽️🔥

2. Code Like a Chef 👨‍🍳💻

3. Share (or Ask for) the Recipe 🔄📖

4. Respect the Timing ⏳🍳

5. Plate Your Work Nicely 🎨🍽️

Conclusion: Keep Cooking, Keep Growing 📣

Setting Up a Modern TypeScript Project with esbuild (No Framework)

What is esbuild (as a Bundler)? 🤔

Creating a TypeScript Project with esbuild 👨‍💻

1. Prerequisites 🧱

2. Project Structure 📁

3. Install Dependencies 📦

4. Create tsconfig.json ✍️

5. Create esbuild.config.ts ⚙️

6. Create Sample Code 💻

7. Add and Bundle CSS 🎨

8. Bundle Images 🖼️

9. Add Scripts in package.json 🔨

10. Run the Project ▶️

11. Build the Project ⚒️

Conclusion 📣

4. Create `tsconfig.json` ✍️

5. Create `esbuild.config.ts` ⚙️

9. Add Scripts in `package.json` 🔨