Hybrid applications in NestJS - Deep Dive

Overview - Hybrid applications

What is it?

Hybrid applications in NestJS are apps that combine different types of servers or protocols in one project. For example, you can have both an HTTP server and a WebSocket server running together. This lets you handle regular web requests and real-time communication in the same app. It makes your app more flexible and powerful without needing separate projects.

Why it matters

Without hybrid applications, developers would need to build and maintain multiple separate servers for different communication methods. This adds complexity, slows development, and can cause harder deployment and scaling. Hybrid apps solve this by letting you manage everything in one place, saving time and reducing errors. This means faster features and better user experiences.

Where it fits

Before learning hybrid applications, you should understand basic NestJS concepts like modules, controllers, and providers, plus how to create a simple HTTP server. After mastering hybrid apps, you can explore advanced topics like microservices, custom transport layers, and scaling strategies.

Mental Model

Core Idea

A hybrid application in NestJS is a single app that runs multiple types of servers or protocols together to handle different communication needs.

Think of it like...

Imagine a Swiss Army knife that has a knife, scissors, and screwdriver all in one tool. Instead of carrying separate tools, you have one device that can do many jobs. Hybrid applications are like that for servers—they combine different communication tools in one app.

┌─────────────────────────────┐
│       Hybrid Application     │
│ ┌───────────────┐ ┌───────┐ │
│ │ HTTP Server   │ │ WS    │ │
│ │ (REST API)    │ │Server │ │
│ └───────────────┘ └───────┘ │
│           │                 │
│           ▼                 │
│    Shared Modules & Logic   │
└─────────────────────────────┘

Build-Up - 6 Steps

1

Foundation

Understanding NestJS Application Basics

Concept: Learn how a basic NestJS app runs a single HTTP server.

A NestJS app starts by creating a main.ts file that bootstraps the app with a single HTTP server. It listens for web requests and routes them to controllers. This is the simplest form of a NestJS app.

Result

You get a working HTTP server that responds to REST API calls.

Knowing how a single server runs is essential before combining multiple servers in one app.

2

Foundation

Introduction to WebSocket Server in NestJS

Concept: Learn how to add a WebSocket server to a NestJS app.

NestJS supports WebSocket gateways that handle real-time communication. You create a gateway class decorated with @WebSocketGateway, which listens for socket events separately from HTTP requests.

Result

You can handle real-time messages alongside HTTP requests in separate parts of the app.

Understanding WebSocket gateways shows how NestJS supports multiple communication protocols.

3

Intermediate

Combining HTTP and WebSocket Servers

🤔Before reading on: do you think you need two separate NestJS apps to run HTTP and WebSocket servers together? Commit to your answer.

Concept: Learn how to run both HTTP and WebSocket servers in the same NestJS app instance.

NestJS allows you to create a hybrid app by simply adding a WebSocket gateway to your existing HTTP app. The main.ts bootstrap stays mostly the same, and NestJS manages both servers internally.

Result

One app instance handles both REST API calls and real-time socket events simultaneously.

Knowing that NestJS can run multiple servers in one app simplifies architecture and reduces overhead.

4

Intermediate

Sharing Modules and Services Across Servers

🤔Before reading on: do you think HTTP controllers and WebSocket gateways need separate services, or can they share the same ones? Commit to your answer.

Concept: Learn how to share business logic and services between HTTP and WebSocket parts of the app.

In NestJS, modules group providers and controllers/gateways. Services injected into both HTTP controllers and WebSocket gateways allow code reuse and consistent behavior across protocols.

Result

You avoid duplicating logic and keep your app maintainable and consistent.

Understanding shared modules prevents code duplication and promotes clean architecture.

5

Advanced

Customizing Hybrid App Lifecycle and Configuration

🤔Before reading on: do you think the lifecycle hooks (like onModuleInit) run separately for HTTP and WebSocket parts, or together? Commit to your answer.

Concept: Learn how lifecycle hooks and configuration work in hybrid apps to manage startup and shutdown cleanly.

NestJS runs lifecycle hooks for all modules and providers regardless of protocol. You can configure middleware, guards, and interceptors to apply selectively to HTTP or WebSocket routes. This control helps manage resources and security.

Result

Your hybrid app behaves predictably and securely across all communication channels.

Knowing lifecycle and configuration details helps avoid bugs and resource leaks in complex apps.

6

Expert

Extending Hybrid Apps with Custom Transport Layers

🤔Before reading on: do you think NestJS only supports HTTP and WebSocket, or can it handle other protocols in hybrid apps? Commit to your answer.

Concept: Learn how to add custom microservice transport layers alongside HTTP and WebSocket in a hybrid app.

NestJS supports microservices with custom transport strategies like TCP, Redis, or NATS. You can combine these with HTTP and WebSocket servers in one app by creating multiple listeners and injecting shared services.

Result

Your app can handle diverse communication methods, scaling to complex enterprise needs.

Understanding custom transports unlocks powerful hybrid architectures beyond common protocols.

Under the Hood

NestJS creates an internal HTTP server using Express or Fastify. When you add a WebSocket gateway, it attaches a WebSocket server to the same underlying HTTP server or a separate port. The framework manages routing and event dispatching for both protocols. Dependency injection ensures shared services are singletons used by all parts. Lifecycle hooks run once per module regardless of protocol, coordinating startup and shutdown cleanly.

Why designed this way?

NestJS was designed to unify different communication methods under one modular architecture to reduce complexity. Instead of forcing separate apps for REST, WebSocket, or microservices, it provides a flexible system to combine them. This design improves developer productivity and app maintainability. Alternatives like separate apps increase deployment overhead and code duplication, which NestJS avoids.

┌───────────────────────────────┐
│          NestJS App            │
│ ┌───────────────┐  ┌─────────┐│
│ │ HTTP Server   │  │ WS Server││
│ │ (Express/Fastify)│ │ (Socket.IO)││
│ └──────┬────────┘  └────┬────┘│
│        │                │     │
│        ▼                ▼     │
│  ┌───────────────┐ ┌─────────┐│
│  │ Controllers   │ │ Gateways││
│  └──────┬────────┘ └────┬────┘│
│         │               │     │
│         ▼               ▼     │
│    ┌───────────────┐         │
│    │ Shared Services│         │
│    └───────────────┘         │
└───────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do you think a hybrid NestJS app requires separate processes for HTTP and WebSocket servers? Commit to yes or no.

Common Belief: You must run separate NestJS apps or processes for HTTP and WebSocket servers.

Reality: NestJS allows running both servers within the same app process and instance.

Why it matters: Running separate apps adds unnecessary complexity, resource use, and deployment overhead.

Quick: Do you think HTTP controllers and WebSocket gateways cannot share services? Commit to yes or no.

Common Belief: HTTP and WebSocket parts need separate services and modules.

Reality: They can share the same services and modules, promoting code reuse.

Why it matters: Not sharing services leads to duplicated logic and harder maintenance.

Quick: Do you think lifecycle hooks run separately for each protocol in a hybrid app? Commit to yes or no.

Common Belief: Lifecycle hooks like onModuleInit run separately for HTTP and WebSocket parts.

Reality: Lifecycle hooks run once per module regardless of protocol, coordinating all parts together.

Why it matters: Misunderstanding this can cause bugs in initialization or cleanup.

Quick: Do you think NestJS only supports HTTP and WebSocket in hybrid apps? Commit to yes or no.

Common Belief: NestJS hybrid apps are limited to HTTP and WebSocket protocols only.

Reality: NestJS supports many transport layers including TCP, Redis, NATS, and custom microservices alongside HTTP and WebSocket.

Why it matters: Limiting to HTTP and WebSocket restricts app scalability and integration options.

Expert Zone

1

Hybrid apps share the same dependency injection container, so singleton services truly remain single instances across protocols.

2

Middleware and guards can be selectively applied to HTTP routes or WebSocket gateways, allowing fine-grained security and processing.

3

Custom transport layers can be integrated seamlessly, but require careful lifecycle and error handling to avoid resource leaks.

When NOT to use

Hybrid applications are not ideal when protocols require completely isolated environments for security or scaling reasons. In such cases, separate microservices or dedicated apps are better. Also, if the app grows too complex, splitting responsibilities can improve maintainability.

Production Patterns

In production, hybrid apps often use shared modules for authentication and data access, with HTTP controllers handling REST APIs and WebSocket gateways managing real-time updates. Custom microservice transports handle background jobs or event buses. Load balancing and clustering are configured to scale each protocol efficiently.

Connections

Microservices Architecture

Hybrid apps can include microservice transport layers alongside HTTP and WebSocket servers.

Understanding hybrid apps helps grasp how microservices can coexist with traditional servers in one codebase.

Event-Driven Systems

WebSocket gateways in hybrid apps enable real-time event-driven communication.

Knowing hybrid apps clarifies how event-driven patterns integrate with request-response models.

Swiss Army Knife Design

Hybrid apps embody the principle of combining multiple tools in one solution.

Recognizing this design pattern aids in architecting flexible, multi-protocol applications.

Common Pitfalls

#1 Trying to run HTTP and WebSocket servers as separate NestJS app instances.

Wrong approach:

const app1 = await NestFactory.create(AppModule);
await app1.listen(3000);
const app2 = await NestFactory.create(AppModule);
await app2.listen(3001);

Correct approach:

const app = await NestFactory.create(AppModule);
await app.listen(3000); // Both HTTP and WS run inside this app

Root cause:

Misunderstanding that NestJS supports multiple servers in one app instance.

#2 Duplicating services for HTTP controllers and WebSocket gateways.

Wrong approach:

@Injectable()
export class HttpService { /* logic */ }

@Injectable()
export class WsService { /* duplicated logic */ }

Correct approach:

@Injectable()
export class SharedService { /* common logic */ }

Root cause:

Not realizing dependency injection allows sharing services across protocols.

#3 Applying HTTP middleware to WebSocket gateways expecting it to work.

Wrong approach:

app.use(someHttpMiddleware); // expecting it to affect WebSocket

Correct approach:

Use WebSocket-specific guards or interceptors for socket events.

Root cause:

Confusing HTTP middleware with WebSocket event handling.

Key Takeaways

Hybrid applications in NestJS let you run multiple servers like HTTP and WebSocket together in one app.

Sharing modules and services across protocols avoids duplicated code and keeps your app clean.

Lifecycle hooks and configuration apply to the whole app, coordinating all servers smoothly.

NestJS supports adding custom transport layers, making hybrid apps powerful and flexible.

Understanding hybrid apps helps build scalable, maintainable, and feature-rich applications.

Practice

1. What is a hybrid application in NestJS?

easy

A. An app that combines HTTP and microservices in one project

B. An app that only uses HTTP controllers

C. An app that only uses microservices

D. An app that runs on multiple servers

Solution

1. Step 1: Understand NestJS application types

   NestJS apps can be HTTP-based, microservice-based, or both combined.

2. Step 2: Define hybrid application

   A hybrid app combines HTTP and microservices in one project to handle both communication types.

3. Final Answer:

   An app that combines HTTP and microservices in one project -> Option A

4. Quick Check:

   Hybrid app = HTTP + microservices [OK]

Hint: Hybrid means mixing HTTP and microservices in one app [OK]

Common Mistakes:

• Thinking hybrid means multiple servers
• Confusing hybrid with only HTTP or only microservices
• Assuming hybrid apps are separate projects

2. Which method is used to add microservice support in a NestJS hybrid application?

easy

A. connectMicroservice()

B. createMicroservice()

C. addMicroservice()

D. useMicroservice()

Solution

1. Step 1: Recall NestJS microservice integration method

   The official NestJS method to add microservices to an app is connectMicroservice().

2. Step 2: Verify method names

   Other options like createMicroservice(), addMicroservice(), or useMicroservice() are not valid NestJS methods.

3. Final Answer:

   connectMicroservice() -> Option A

4. Quick Check:

   Use connectMicroservice() to add microservices [OK]

Hint: Remember: connectMicroservice() connects microservices [OK]

Common Mistakes:

• Using createMicroservice() which does not exist
• Confusing with addMicroservice() or useMicroservice()
• Trying to add microservices without this method

3. Given this NestJS hybrid app code snippet, what will be the output when the app starts?

const app = await NestFactory.create(AppModule);
app.connectMicroservice({ transport: Transport.TCP });
await app.startAllMicroservices();
await app.listen(3000);
console.log('App is running');

medium

A. App listens on port 3000 but microservices do not start

B. App is running (and microservices start listening)

C. Error: connectMicroservice is not a function

D. App crashes due to missing microservice configuration

Solution

1. Step 1: Analyze microservice connection

   The code calls connectMicroservice with TCP transport, which is valid to add microservices.

2. Step 2: Check microservice start and app listen

   startAllMicroservices() starts microservices, then app.listen(3000) starts HTTP server. Console logs 'App is running'.

3. Final Answer:

   App is running (and microservices start listening) -> Option B

4. Quick Check:

   connectMicroservice + startAllMicroservices + listen = running app [OK]

Hint: connectMicroservice + startAllMicroservices means microservices run [OK]

Common Mistakes:

• Thinking microservices start automatically without startAllMicroservices()
• Confusing connectMicroservice with createMicroservice
• Assuming app.listen blocks microservices

4. Identify the error in this NestJS hybrid app setup:

const app = await NestFactory.create(AppModule);
app.connectMicroservice({ transport: Transport.REDIS });
await app.listen(3000);
await app.startAllMicroservices();

medium

A. AppModule cannot be used with microservices

B. connectMicroservice() does not accept transport option

C. startAllMicroservices() must be called before app.listen()

D. Missing await before connectMicroservice()

Solution

1. Step 1: Check method call order

   In NestJS, microservices must be started before the HTTP server listens, so startAllMicroservices() should be before app.listen().

2. Step 2: Validate other options

   connectMicroservice() accepts transport option; AppModule supports microservices; connectMicroservice() is synchronous, no await needed.

3. Final Answer:

   startAllMicroservices() must be called before app.listen() -> Option C

4. Quick Check:

   Start microservices before HTTP listen [OK]

Hint: Call startAllMicroservices() before app.listen() [OK]

Common Mistakes:

• Calling startAllMicroservices() after app.listen()
• Adding await to connectMicroservice()
• Thinking transport option is invalid

5. You want to build a NestJS hybrid app that handles HTTP requests and listens to RabbitMQ messages. Which steps correctly set up the microservice part?

hard

A. Use connectMicroservice({ transport: Transport.TCP }) and call startAllMicroservices() after app.listen()

B. Use createMicroservice({ transport: Transport.RMQ }) and call app.listen() before starting microservices

C. Add RabbitMQ config in AppModule imports and call app.listen() only

D. Use connectMicroservice({ transport: Transport.RMQ, options: { urls: ['amqp://localhost'], queue: 'main_queue' } }), then call startAllMicroservices() before app.listen()

Solution

1. Step 1: Choose correct microservice setup for RabbitMQ

   connectMicroservice() with Transport.RMQ and proper options (urls, queue) is the correct way to add RabbitMQ microservice.

2. Step 2: Call startAllMicroservices() before app.listen()

   Microservices must start before HTTP server listens to ensure both run properly.

3. Final Answer:

   Use connectMicroservice({ transport: Transport.RMQ, options: { urls: ['amqp://localhost'], queue: 'main_queue' } }), then call startAllMicroservices() before app.listen() -> Option D

4. Quick Check:

   connectMicroservice + RMQ options + startAllMicroservices before listen [OK]

Hint: Set RMQ options in connectMicroservice and start microservices first [OK]

Common Mistakes:

• Using createMicroservice() which is not a NestFactory method
• Calling app.listen() before starting microservices
• Using wrong transport type for RabbitMQ
• Not providing RabbitMQ connection options