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.