German Cocca - freeCodeCamp.org

Event-Based Architectures in JavaScript: A Handbook for Devs

German Cocca — Wed, 05 Nov 2025 17:21:43 +0000

In modern software development, event-driven architectures have become one of the most powerful ways to build scalable, decoupled, and responsive systems.

Instead of relying on direct calls between components, event-driven systems communicate through events – messages that signal that something has happened.

JavaScript, with its inherently asynchronous nature and built-in event loop, is a natural fit for this paradigm. From browser interactions to backend microservices, event-based communication enables flexibility, performance, and maintainability across the entire stack.

This handbook explores how event-driven architectures work, how they can be implemented in JavaScript (both in Node.js and in the browser), and why they are foundational to building modern distributed applications.

Prerequisites: What you should already know

JavaScript fundamentals (ES6+): modules, classes, closures, this
Asynchronous JS: callbacks, Promises, async/await, and the event loop
Node.js basics

1. Introduction
2. Fundamentals of the Event Model in JavaScript
3. Publisher–Subscriber (Pub/Sub) Pattern
4. Implementations in Node.js
5. Event-Driven Microservices Architecture
6. Frontend Applications and Events
7. Event Sourcing and CQRS (Command Query Responsibility Segregation)
8. Benefits and Challenges
9. Real-World Use Cases
10. Best Practices and Conclusions
Conclusion

1. Introduction

Software systems are becoming increasingly distributed, asynchronous, and complex. Traditional request–response architectures – where one component directly calls another and waits for a reply – often create tight coupling and limit scalability.

In contrast, event-driven architectures (EDA) embrace asynchrony by letting components communicate through events (messages that represent a change or an occurrence in the system). When an event happens (for example, “Order Created”), other parts of the system that care about that event can react to it independently, without knowing who triggered it or when.

This simple shift from commands to events has profound implications for scalability, resilience, and system design. It allows applications to evolve as loosely coupled collections of independent components that listen for and emit events, rather than monolithic blocks of code that depend directly on each other.

What Is an Event-Driven Architecture?

An event-driven architecture is a software design pattern where the flow of the program is determined by events. An event can be any significant change in state, like a user action, a message from another system, a sensor reading, or even an internal trigger like a database update.

In this model:

Producers (also called emitters or publishers) generate and broadcast events.
Consumers (or listeners or subscribers) react to those events asynchronously.

Unlike traditional request-driven systems, producers and consumers don’t directly call each other. Instead, they communicate through a mediator (like an event bus, queue, or topic), achieving loose coupling and higher flexibility.

Why JavaScript Naturally Fits This Paradigm

JavaScript was built around an event-driven model from its very beginning. In the browser, every user interaction – clicks, scrolls, network responses – is handled through events. The event loop, callback queue, and non-blocking I/O make JavaScript particularly well-suited for systems where many things happen concurrently.

In Node.js, this model extends to the backend. The EventEmitter API, asynchronous I/O, and the single-threaded event loop allow developers to write scalable services that handle thousands of concurrent connections efficiently. This makes JavaScript a natural language for implementing and experimenting with event-driven systems across the full stack, from the UI to distributed microservices.

Event-Driven vs. Request-Driven Architectures

Here’s a quick summary of the main features and differences:

Aspect	Request-Driven	Event-Driven
Communication	Direct, synchronous (A calls B)	Indirect, asynchronous (A emits event, B reacts)
Coupling	Tight (services know each other)	Loose (services only know event types)
Scalability	Limited by synchronous blocking	Naturally scalable with asynchronous flows
Failure handling	Errors propagate directly	Components fail independently
Typical example	REST API call chain	Message bus or event broker (Kafka, RabbitMQ)

Event-driven systems tend to perform better in environments that require real-time updates, asynchronous workflows, or high concurrency, such as financial transaction systems, IoT platforms, and analytics pipelines.

But adopting an Event-Driven Architecture is not a universal solution. It introduces its own complexities and is best suited to problems where loose coupling, scalability, and reactivity are primary goals.

When It Makes Sense to Use an Event-Driven Architecture

Asynchronous or real-time requirements: When the system needs to react to changes instantly (for example, new data, user interactions, or external triggers).
High scalability and resilience: When services must handle variable workloads independently, without blocking or waiting for each other.
Microservices or distributed systems: When independent services must communicate without strong dependencies or shared state.
Extensibility and flexibility: When you expect the system to evolve over time, adding new consumers without modifying existing producers.
Data streaming or continuous processing: When the system processes streams of events (for example, telemetry, logs, or payments) rather than discrete requests.

When It Might Not Be the Right Choice

Simple, synchronous applications: For small systems where interactions are linear (for example, a CRUD API or a small monolith), introducing an event bus may be unnecessary overhead.
Strong consistency requirements; When the system must maintain a strict order of operations or immediate transactional integrity, asynchronous event flows can complicate data coherence.
Limited observability or operational tooling: Debugging distributed events is harder – tracing and replaying events requires good logging and monitoring infrastructure.
Team inexperience: If the development team is not familiar with asynchronous systems, event versioning, or message brokers, the cognitive load may outweigh the benefits.

Typical Business Use Cases

E-commerce platforms: Events like OrderPlaced, PaymentProcessed, ItemShipped trigger workflows across inventory, billing, and logistics services.
Financial and banking systems: Real-time updates of transactions, fraud detection, and asynchronous settlement processing.
IoT and telemetry processing: Devices emit data continuously. The backend aggregates, filters, and reacts to these events asynchronously.
Streaming analytics and monitoring: Continuous event ingestion from applications or sensors to update dashboards and trigger alerts.
Social networks and messaging apps: Notifications, chat updates, and activity feeds naturally map to event streams that multiple consumers can subscribe to.
Workflow orchestration systems: Each step in a process (for example, document signed, email sent, approval granted) triggers subsequent actions automatically.

Event-driven architectures change the way we think about program flow. Instead of pulling data or waiting for responses, components react to what’s happening in the system.

By leveraging JavaScript’s asynchronous foundations, like the event loop, promises, and non-blocking I/O, developers can build architectures that are more responsive, resilient, and scalable than traditional request-driven designs.

In the next section, we’ll dive deeper into how JavaScript’s event model works, exploring the event loop, the task queue, and the key mechanisms (like EventEmitter) that make this paradigm possible.

2. Fundamentals of the Event Model in JavaScript

JavaScript is inherently event-driven. From its earliest days in the browser to its modern incarnation on the server with Node.js, the language has been designed to handle asynchronous operations gracefully through events – signals that something has happened.

Understanding how this works under the hood is essential before applying event-driven principles to large systems.

The Event Loop, Task Queue, and Call Stack

At the heart of JavaScript’s concurrency model lies the event loop, a mechanism that enables asynchronous, non-blocking behavior in a single-threaded environment.

Let’s break it down:

Call Stack: This is where JavaScript executes code line by line. Each function call creates a new frame on the stack.
Task Queue (or Callback Queue): When asynchronous operations finish (like a setTimeout or a network request), their callbacks are queued here for later execution.
Event Loop: Constantly checks if the call stack is empty. When it is, the loop dequeues a task and pushes it onto the stack to execute.

This cycle repeats indefinitely – hence the term “event loop.”

console.log("A");

setTimeout(() => {
  console.log("B");
}, 0);

console.log("C");

// Output:
// A
// C
// B

Even though the timeout is 0, the callback runs after the synchronous code because it’s queued in the task queue and executed only when the call stack is clear.

This model allows JavaScript to remain responsive and non-blocking, even while performing I/O operations or waiting for user input.

EventEmitter and the Pub/Sub Pattern

Node.js exposes its event-driven core through the EventEmitter class – one of its most fundamental building blocks.

An EventEmitter lets objects emit events and subscribe to them. This mechanism forms the foundation for countless Node.js APIs, from HTTP servers to file streams.

Here’s a simple example:

const EventEmitter = require('events');
const emitter = new EventEmitter();

// Subscriber (listener)
emitter.on('dataReceived', (data) => {
  console.log(`Data received: ${data}`);
});

// Publisher (emitter)
emitter.emit('dataReceived', 'User profile loaded');

Output:

Data received: User profile loaded

Each event has:

A name (string or symbol)
A set of listeners (functions) that react to it

This is the classic Publisher–Subscriber pattern (Pub/Sub): components publish events, while others subscribe to react – without direct references to each other.

EventTarget, CustomEvent, and Browser Events

In the browser, the same concept exists through the EventTarget API. Every DOM element can listen for or dispatch events.

const button = document.querySelector('button');

button.addEventListener('click', () => {
  console.log('Button clicked!');
});

We can also create custom events to simulate our own event-driven behavior:

const userEvent = new CustomEvent('userLoggedIn', {
  detail: { name: 'Alice' }
});

document.addEventListener('userLoggedIn', (e) => {
  console.log(`Welcome, ${e.detail.name}!`);
});

document.dispatchEvent(userEvent);

Output:

Welcome, Alice!

This lightweight mechanism allows front-end applications to coordinate behavior across components without tight coupling.

Putting It All Together

Whether in the browser or Node.js, JavaScript’s asynchronous runtime and event-driven APIs form a natural foundation for building reactive, modular, and scalable systems.

In Node.js, nearly everything is an event emitter – HTTP requests, streams, process signals, and even errors. In the browser, events are how users and systems interact through clicks, network responses, and state changes.

This unified model across client and server is what makes JavaScript uniquely powerful for implementing end-to-end event-driven architectures.

In the next section, we’ll explore the Pub/Sub pattern in depth: we’ll understand its advantages, pitfalls, and how to implement it cleanly in plain JavaScript before scaling up to distributed systems.

3. Publisher–Subscriber (Pub/Sub) Pattern

The Publisher–Subscriber pattern, often abbreviated as Pub/Sub, is one of the most common and powerful foundations of event-driven systems. It defines how components can communicate asynchronously without knowing each other directly – a principle known as loose coupling.

In a Pub/Sub model:

Publishers (or emitters) broadcast events.
Subscribers (or listeners) register interest in those events.
A broker (or event bus) acts as a mediator between the two.

This separation allows systems to evolve and scale independently: new subscribers can be added without changing the publishers, and vice versa.

Concept and Advantages of Decoupling

In traditional architectures, one component often depends directly on another:

function processOrder(order) {
  sendInvoice(order);
  notifyWarehouse(order);
}

Here, processOrder is tightly coupled to the functions it calls. If we later need to send a shipping confirmation or trigger analytics, we must modify processOrder again. This violates the Open/Closed Principle (open for extension, closed for modification).

In a Pub/Sub model, the same logic becomes event-driven:

const EventEmitter = require('events');
const bus = new EventEmitter();

bus.on('order:created', sendInvoice);
bus.on('order:created', notifyWarehouse);

bus.emit('order:created', { id: 42, items: 3 });

Now, processOrder doesn’t need to know who’s listening. It simply emits an event (order:created), and any number of subscribers can react to it – even ones that didn’t exist when the code was written.

Advantages:

✅ Loose coupling between components
⚙️ Easier extensibility: add new behaviors by adding listeners
🚀 Parallel evolution: teams can work on producers and consumers independently
🧩 Greater testability: events can be simulated in isolation

Basic Implementation in Plain JavaScript

While Node.js provides a ready-to-use EventEmitter, you can easily build a minimal event bus in plain JavaScript. This helps illustrate the underlying logic:

function createEventBus() {
  const listeners = {};

  return {
    subscribe(event, callback) {
      if (!listeners[event]) listeners[event] = [];
      listeners[event].push(callback);
    },
    publish(event, data) {
      (listeners[event] || []).forEach((callback) => callback(data));
    },
    unsubscribe(event, callback) {
      listeners[event] = (listeners[event] || []).filter((cb) => cb !== callback);
    }
  };
}

// Example usage
const bus = createEventBus();

function onUserRegistered(user) {
  console.log(`Welcome, ${user.name}!`);
}

bus.subscribe('user:registered', onUserRegistered);
bus.publish('user:registered', { name: 'Alice' });
bus.unsubscribe('user:registered', onUserRegistered);

This simple implementation already captures the essence of Pub/Sub:

You can subscribe to an event.
You can publish events with data.
You can unsubscribe dynamically.

Limitations and When to Use a Library

While the above implementation works for small-scale use, real-world systems often require:

Wildcard or hierarchical event names (for example, order.* or user.created)
Asynchronous delivery (with message queues or brokers)
Error handling and retries
Event persistence or replay
Cross-process or distributed communication

In those cases, using a dedicated library or broker is more appropriate.

Popular options include Node.js’s built-in EventEmitter for in-process events, RxJS for reactive programming and stream composition, and message brokers like RabbitMQ, Kafka, or Redis Streams for distributed, scalable architectures

Each of these tools extends the Pub/Sub model to handle larger scale, fault tolerance, and observability – essential features in modern distributed systems.

Summary

The Publisher–Subscriber pattern is the backbone of event-driven design. It transforms direct, synchronous function calls into indirect, asynchronous communications, allowing systems to evolve gracefully and handle change without friction.

In JavaScript, this pattern is everywhere – from browser DOM events to Node.js streams and microservice architectures.

In the next section, we’ll dive deeper into practical implementations in Node.js, exploring how the events module powers many of the platform’s most important features and how it can be extended to build robust, event-oriented systems.

4. Implementations in Node.js

Node.js was designed from the ground up around the event-driven paradigm. Its single-threaded, non-blocking I/O model allows it to handle thousands of concurrent operations efficiently – not by running code in parallel, but by reacting to events as they occur.

At the heart of this model lies the events module, which exposes the EventEmitter class used throughout Node’s core APIs, from HTTP servers to file streams.

How to Use the Native `events` Module

The EventEmitter class provides a standard way to emit and listen for events within a Node.js process.
It’s a lightweight yet powerful abstraction for asynchronous communication between components.

Let’s look at a simple example:

const EventEmitter = require('events');
const emitter = new EventEmitter();

// Register an event listener
emitter.on('user:login', (user) => {
  console.log(`User logged in: ${user.name}`);
});

// Emit the event
emitter.emit('user:login', { name: 'Alice' });

Output:

User logged in: Alice

Each EventEmitter instance maintains an internal map of event names to listener functions. Listeners can be added using .on() or .once() (for one-time execution), and events are triggered asynchronously with .emit().

Real Example: Event-Oriented Microservice

To see this in action, imagine a simplified order-processing microservice:

const EventEmitter = require('events');
const bus = new EventEmitter();

function createOrder(order) {
  console.log(`Order created: ${order.id}`);
  bus.emit('order:created', order);
}

function sendInvoice(order) {
  console.log(`Invoice sent for order ${order.id}`);
}

function updateInventory(order) {
  console.log(`Inventory updated for order ${order.id}`);
}

// Subscribe listeners
bus.on('order:created', sendInvoice);
bus.on('order:created', updateInventory);

// Simulate an order
createOrder({ id: 123, items: ['Book', 'Pen'] });

Output:

Order created: 123
Invoice sent for order 123
Inventory updated for order 123

Here, the microservice emits an order:created event whenever a new order is placed. Multiple listeners (invoice and inventory handlers) react independently – a miniature event-driven architecture in a single process.

This approach scales naturally as the system grows. New behaviors, like sending notifications or analytics tracking, can be added by simply subscribing new listeners.

Error Handling and Backpressure

In event-driven systems, error management is crucial because unhandled exceptions inside event listeners can crash the entire Node.js process.

To prevent this, Node provides built-in mechanisms:

Error events: You can emit and handle errors explicitly.

 const EventEmitter = require('events');
 const emitter = new EventEmitter();

 emitter.on('error', (err) => {
   console.error('An error occurred:', err.message);
 });

 emitter.emit('error', new Error('Database connection failed'));

If an 'error' event is emitted without at least one listener, Node.js will throw it as an uncaught exception and terminate the process.

Backpressure management: In streaming scenarios, producers can emit data faster than consumers can handle.

Node.js Streams solve this through backpressure, where consumers signal when they are ready for more data.
```
 const fs = require('fs');
 const readable = fs.createReadStream('large-file.txt');
 const writable = fs.createWriteStream('copy.txt');

 readable.pipe(writable); // Automatically manages flow control
```
Under the hood, streams use event-based coordination (data, drain, end) to ensure stability even under heavy load.

How to Build an Event Bus Across Services

While EventEmitter works within a single process, real-world architectures often span multiple microservices or containers. In such cases, an external message broker (like RabbitMQ, Kafka, or Redis Streams) acts as a distributed event bus.

Each service becomes either:

a producer (publishing events), or
a consumer (subscribing and reacting).

Node.js integrates seamlessly with these systems using community libraries:

amqplib for RabbitMQ
kafkajs for Apache Kafka
redis for Redis Pub/Sub

Example (simplified with Redis):

const { createClient } = require('redis');
const publisher = createClient();
const subscriber = createClient();

await publisher.connect();
await subscriber.connect();

subscriber.subscribe('user:created', (message) => {
  console.log(`New user event received: ${message}`);
});

await publisher.publish('user:created', JSON.stringify({ id: 1, name: 'Alice' }));

This pattern allows cross-service communication without tight coupling. Each service reacts to events asynchronously, whether it’s hosted locally or across a cluster.

Summary

The Node.js EventEmitter encapsulates the essence of event-driven design at the process level: lightweight, decoupled, and asynchronous. Combined with external message brokers, it becomes a powerful tool for building scalable, distributed event-driven systems.

Through events, Node.js applications can handle multiple concurrent workflows efficiently, maintain clear separation of concerns, and grow organically as the system evolves.

In the next section, we’ll extend this idea beyond a single application. We’ll explore Event-Driven Microservices Architecture, where multiple independent services communicate entirely through asynchronous event flows.

5. Event-Driven Microservices Architecture

As applications grow, a single event bus inside one process is no longer enough. When your system consists of multiple independently deployed services – each owning its own data and responsibilities – the Event-Driven Architecture becomes a natural fit for enabling asynchronous, decoupled communication.

In an event-driven microservice ecosystem, services don’t call each other directly through HTTP or RPC.
Instead, they publish and consume events through a message broker – a central medium that handles delivery, queuing, and persistence of messages between services.

Asynchronous Communication via Message Brokers

In a request-driven microservice system, one service directly invokes another via REST or gRPC:

Order Service  →  Inventory Service  →  Notification Service

Each call is synchronous, meaning the caller waits for a response. This creates coupling and potential cascading failures if one service is down or slow.

In an event-driven model, communication happens asynchronously through events:

Order Service  →  [Event Bus]  →  Inventory Service, Notification Service

The event bus becomes the backbone of the system. Each service publishes events and subscribes to those it needs, without knowing who will consume them.

This brings several advantages:

⚙️ Loose coupling: services don’t depend on each other’s availability
📈 Scalability: new consumers can subscribe without changing existing code
🔁 Resilience: temporary outages are absorbed by the broker’s queues
🧩 Extensibility: new workflows can be added just by listening to existing events

Example: Order → Inventory → Notification Flow

Let’s consider a practical scenario in an e-commerce platform:

Order Service publishes an order:created event when a user places an order.
Inventory Service subscribes to order:created and decrements stock.
Notification Service also subscribes to order:created and sends a confirmation email.

          ┌──────────────────────┐
          │   Order Service      │
          │ emits "order:created"│
          └──────────┬───────────┘
                     │
          ┌──────────▼───────────┐
          │     Event Bus        │
          │ (Kafka, RabbitMQ...) │
          └──────┬───────────────┘
      ┌──────────┴───────────┐   ┌────────────────────┐
      │ Inventory Service    │   │ Notification Service│
      │ updates stock        │   │ sends email         │
      └──────────────────────┘   └────────────────────┘

Node.js example (simplified with Redis):

// order-service.js
const { createClient } = require('redis');
const publisher = createClient();
await publisher.connect();

async function createOrder(order) {
  console.log(`Order created: ${order.id}`);
  await publisher.publish('order:created', JSON.stringify(order));
}

createOrder({ id: 42, items: ['Book', 'Pen'] });

// inventory-service.js
const { createClient } = require('redis');
const subscriber = createClient();
await subscriber.connect();

await subscriber.subscribe('order:created', (message) => {
  const order = JSON.parse(message);
  console.log(`Updating inventory for order ${order.id}`);
});

// notification-service.js
const { createClient } = require('redis');
const subscriber = createClient();
await subscriber.connect();

await subscriber.subscribe('order:created', (message) => {
  const order = JSON.parse(message);
  console.log(`Sending confirmation email for order ${order.id}`);
});

Each service is now independent. They communicate only through events, not direct calls.

Designing Event Contracts (Event Schemas)

In a distributed system, events are contracts – they define what information producers share and consumers rely on. Defining and maintaining these contracts carefully is crucial to avoid breaking downstream consumers.

A good event should:

Contain enough context for consumers to act independently
Use a versioned schema to evolve safely over time
Include metadata like eventId, timestamp, and source

Example event schema (JSON):

{
  "event": "order:created",
  "version": 1,
  "timestamp": "2025-10-29T18:45:00Z",
  "data": {
    "orderId": 42,
    "userId": 123,
    "items": [
      { "sku": "BOOK-001", "quantity": 2 },
      { "sku": "PEN-003", "quantity": 1 }
    ],
    "total": 39.90
  }
}

Best practices:

Use namespaced event types (order:created, payment:failed)
Include a version number (v1, v2) to avoid schema drift
Store events in a central registry (for example, JSON Schema repository)
Log all events for auditing and debugging

When to Use an Event-Driven Microservice Architecture

Event-driven microservices are especially valuable when:

Systems require real-time updates (for example, notifications, analytics)
Components must operate independently and asynchronously
The platform needs to scale horizontally across services
New capabilities should be added without touching existing code

But this architecture also brings challenges:

Harder to trace flows across multiple asynchronous hops
Requires observability tools (logs, traces, metrics) to debug issues
Event ordering and exact-once delivery can be complex
Increased operational overhead from managing brokers and message queues

Summary

Event-driven microservices take the principles of the Pub/Sub pattern and scale them across distributed systems. By communicating exclusively through asynchronous events, services become autonomous, resilient, and extensible. This is ideal for modern cloud architectures and high-throughput applications.

In the next section, we’ll shift our focus to the front end and explore how event-driven principles power reactivity in browsers and frameworks like React and Vue, and how technologies like WebSockets and Server-Sent Events enable real-time user experiences.

6. Frontend Applications and Events

While backend systems use event-driven architectures to coordinate between services, frontend applications have relied on event-based programming since JavaScript’s creation. And again, every user interaction is handled through events.

Understanding how events flow in the browser, and how modern frameworks like React and Vue build upon this model, is key to creating responsive, decoupled, and real-time user interfaces.

Custom Events in the Browser

In vanilla JavaScript, every DOM element can emit and listen to events through the EventTarget API.
This mechanism is the foundation of how browsers handle user interaction and component communication.

Example – Basic Event Handling:

Here, the button acts as an event emitter. When the click event occurs, the listener function reacts. This is a simple example of publish-subscribe behavior within the DOM.

You can also define custom events to allow decoupled communication between components:

const userEvent = new CustomEvent('user:registered', {
  detail: { name: 'Alice', email: 'alice@example.com' }
});

// Listen for the event
document.addEventListener('user:registered', (e) => {
  console.log(`Welcome ${e.detail.name}!`);
});

// Dispatch it
document.dispatchEvent(userEvent);

Output:

Welcome Alice!

This approach allows different parts of the UI to react to user actions or system changes without directly calling each other.

Event Communication in Modern Frameworks

Modern JavaScript frameworks like React, Vue, and Angular abstract the native event system, but the core idea remains the same: components react to events.

React Example

React’s synthetic event system wraps the browser’s native events, providing a unified interface across browsers.

function NewsletterSignup() {
  function handleSubmit(e) {
    e.preventDefault();
    console.log('Newsletter form submitted!');
  }

  return (
    
      type="email" placeholder="Your email" />
      
    
  );
}

Behind the scenes, React uses an event delegation model: it attaches a single listener at the root and dispatches events down the component tree efficiently.

For cross-component communication, React developers often use:

Context or state managers (like Redux, Zustand, or Recoil)
Event emitter utilities (like mitt or nanoevents)
Custom hooks for modular event handling

Example using a lightweight emitter (mitt):

import mitt from 'mitt';

export const bus = mitt();

Then anywhere in your app:

// Component A
bus.emit('theme:changed', 'dark');

// Component B
bus.on('theme:changed', (theme) => {
  console.log(`Theme updated to ${theme}`);
});

This simple event bus decouples components that don’t share a direct parent-child relationship.

Vue Example

Vue provides a native event system for child-to-parent communication and also supports global event buses.

The parent component can listen for user-registered and react accordingly. Vue 3 also supports custom event buses via external libraries like mitt, enabling component-to-component events without tight coupling.

Real-Time Architectures: WebSockets and Server-Sent Events

In modern web applications, the event-driven model extends beyond the client, connecting the front end and back end in real-time.

WebSockets

WebSockets provide a full-duplex channel between the browser and the server. This means both sides can send events at any time, enabling instant updates without polling.

Example:

const socket = new WebSocket('wss://example.com/socket');

socket.addEventListener('open', () => {
  console.log('Connected to server');
  socket.send(JSON.stringify({ event: 'user:joined', name: 'Alice' }));
});

socket.addEventListener('message', (msg) => {
  const data = JSON.parse(msg.data);
  console.log('New event from server:', data);
});

Use cases:

Real-time chat applications
Live dashboards
Online multiplayer games

Server-Sent Events (SSE)

SSE is a simpler alternative when you only need one-way communication – from server to client – using standard HTTP connections.

const source = new EventSource('/events');

source.addEventListener('update', (e) => {
  const data = JSON.parse(e.data);
  console.log('Received update:', data);
});

SSE is ideal for live notifications, monitoring dashboards, and continuous data feeds.

Summary

The frontend world has always been event-driven – from DOM interactions to modern component frameworks and real-time connections.

By treating the UI as a system that reacts to events rather than polling for changes, we build interfaces that are more responsive, more modular, and easier to extend and integrate with event-driven back ends.

Whether you use CustomEvent, mitt, WebSockets, or SSE, the principle is the same: emit events, listen for changes, and let your app respond asynchronously.

In the next section, we’ll explore how these same principles extend into Event Sourcing and CQRS (Command Query Responsibility Segregation) – advanced architectural patterns that persist and reconstruct system state entirely through events.

7. Event Sourcing and CQRS (Command Query Responsibility Segregation)

Up to this point, we’ve explored events as transient messages that trigger behavior – signals passed between components or services. But in more advanced architectures, events can also become the source of truth for the system’s state itself.

This is where Event Sourcing and CQRS come into play.

These patterns are fundamental in systems that require auditability, replayability, and scalable state reconstruction, such as banking platforms, e-commerce systems, and workflow engines.

Event Sourcing: The Core Idea

In traditional architectures, a system stores only the current state: for example, a database row representing the latest balance of a user’s account.

In Event Sourcing, the system instead stores a series of events that led to that state. Each event represents a historical change, such as AccountCreated, FundsDeposited, or FundsWithdrawn.

When you need the current state, you don’t query a static record – you replay all relevant events in sequence.

Traditional Model:

Account	Balance
#001	$500

Event-Sourced Model:

Timestamp	Event	Data
10:00 AM	AccountCreated	{ id: 1, owner: 'Alice' }
10:05 AM	FundsDeposited	{ id: 1, amount: 300 }
10:10 AM	FundsDeposited	{ id: 1, amount: 200 }

To calculate the balance, you replay the events:

0 + 300 + 200 = $500

This approach provides:

🧾 Full audit history: every state change is recorded
🔁 Replayability: rebuild state after crashes or schema changes
🧩 Temporal queries: know what the system looked like at any point in time

Example: Reconstructing State from Events

Let’s illustrate with a simple JavaScript implementation.

const events = [
  { type: 'AccountCreated', data: { id: 1, owner: 'Alice' } },
  { type: 'FundsDeposited', data: { id: 1, amount: 300 } },
  { type: 'FundsDeposited', data: { id: 1, amount: 200 } },
  { type: 'FundsWithdrawn', data: { id: 1, amount: 100 } }
];

function rebuildAccount(events) {
  let balance = 0;

  for (const event of events) {
    switch (event.type) {
      case 'FundsDeposited':
        balance += event.data.amount;
        break;
      case 'FundsWithdrawn':
        balance -= event.data.amount;
        break;
    }
  }

  return balance;
}

console.log('Current balance:', rebuildAccount(events)); // 400

Here, we never stored a static “balance” field. Instead, we reconstructed it from the sequence of past events – the same way a ledger works in accounting.

This technique is powerful for debugging, auditing, or migrating systems: you can replay all events in a new environment to rebuild state exactly as it was.

CQRS: Command Query Responsibility Segregation

CQRS (Command Query Responsibility Segregation) is a complementary pattern often used with Event Sourcing.
It separates the model for writing data (commands) from the model for reading data (queries).

Commands modify system state by producing events (OrderPlaced, PaymentProcessed).
Queries read data optimized for retrieval (for example, a denormalized “view” of orders).

This separation improves scalability and performance because the read and write sides can evolve independently – even use different databases.

Simplified diagram:

[User Action]
      │
      ▼
 ┌────────────┐
 │ Command API│  --->  emits --->  [Event Store]
 └────────────┘                      │
                                    ▼
                        ┌────────────────────┐
                        │  Read Model / View │
                        │ (e.g., MongoDB)    │
                        └────────────────────┘

Example (conceptual):

function placeOrder(order) {
  // Write model
  eventStore.push({ type: 'OrderPlaced', data: order });
}

function getOrdersView() {
  // Read model
  return eventStore
    .filter((e) => e.type === 'OrderPlaced')
    .map((e) => e.data);
}

Here, the event store acts as the single source of truth, while query views can be rebuilt or optimized as needed.

Difference Between Event Sourcing and Pub/Sub

It’s common to confuse Event Sourcing with simple event-driven messaging, but they solve different problems:

Aspect	Pub/Sub	Event Sourcing
Purpose	Asynchronous communication	Persistent state representation
Event lifetime	Temporary (in transit)	Permanent (stored)
Consumer type	Services that react	Systems that rebuild state
Example	Send email when order created	Reconstruct order history

You can – and often should – use both together: an event-sourced service emits domain events to notify other systems.

When to Use Event Sourcing and CQRS

Use when:

You need a complete audit trail or historical reconstruction.
The business domain is complex and event-driven by nature (finance, logistics, IoT).
The system requires high resilience and state recoverability.

Avoid when:

You’re building a small, CRUD-oriented app with limited complexity.
You don’t need event replay or full history, as it adds storage and operational overhead.
Your team lacks experience managing distributed consistency and event evolution.

Summary

Event Sourcing and CQRS extend event-driven design to the data layer. Instead of only reacting to events, your system persists them and uses them as the foundation for rebuilding, auditing, and scaling.

This approach transforms your architecture from a static data store into a living timeline, where every change is captured as part of an ongoing story of the system’s behavior.

In the next section, we’ll analyze the benefits and challenges of event-driven architectures. We’ll explore why they scale so effectively, but also why debugging and observability can be tricky in large distributed environments.

8. Benefits and Challenges

Event-driven architectures offer remarkable scalability, resilience, and flexibility, qualities that make them a cornerstone of modern distributed systems. But these benefits come with trade-offs: debugging becomes more complex, data consistency is harder to guarantee, and operational visibility requires specialized tooling.

In this section, we’ll examine both sides — why EDAs are so powerful and what challenges teams face when implementing them.

Benefits of EDA

1. Scalability and Responsiveness

Event-driven systems naturally handle high concurrency. Because components react to events asynchronously, they can process workloads in parallel without blocking one another.

For example, in a retail platform:

The Order Service publishes an event.
The Inventory, Billing, and Notification services consume it concurrently.

This decoupling allows systems to scale horizontally, adding new consumers or instances without affecting existing ones.

Also, when combined with brokers like Kafka or RabbitMQ, EDAs can handle massive throughput while maintaining order and reliability.

2. Loose Coupling and Extensibility

In a traditional system, integrating new functionality often requires editing existing components. In an event-driven system, new consumers simply subscribe to existing events.

For instance, adding a new Analytics Service that listens for order:created events requires:

No changes to the Order Service
No disruption to other consumers
No coordination between teams

This makes event-driven systems extensible by design, which is invaluable for large organizations with multiple teams or evolving business logic.

3. Resilience and Fault Isolation

Since communication is asynchronous, if one service fails, others can continue working. Events are buffered in the broker and delivered later.

This prevents cascading failures typical of tightly coupled, request-response systems. For example, if the Notification Service is down, orders can still be processed, and notifications will be sent once it recovers.

Many brokers also provide durable queues and retries, ensuring no event is lost even under heavy load or downtime.

4. Real-Time and Reactive Experiences

Event-driven systems power real-time applications, from chat apps and IoT platforms to fraud detection systems and live analytics dashboards.

Because events represent changes as they happen, they enable instant updates, alerts, and responsive UIs. When combined with technologies like WebSockets, Server-Sent Events, or GraphQL Subscriptions, the same model extends seamlessly to the frontend.

5. Auditability and Traceability

When paired with Event Sourcing, EDAs provide a complete audit trail of everything that has happened in the system. This is crucial for domains like finance, healthcare, or logistics, where compliance and historical accuracy are mandatory.

Challenges of EDA

1. Debugging and Tracing

Unlike synchronous systems, where a stack trace shows the full call path, event-driven systems are non-linear. An event may pass through multiple services, queues, and transformations before triggering an outcome.

This makes it difficult to answer questions like:

“Why did this event trigger twice?”
“Where did this data originate?”
“Which services consumed this message?”

To mitigate this, teams rely on distributed tracing tools such as:

OpenTelemetry
Jaeger
Zipkin
AWS X-Ray
Kafka UI / Conduktor (for message inspection)

Embedding trace IDs in event metadata is a best practice that allows cross-service correlation of events.

2. Data Consistency

Because events are asynchronous, maintaining strict transactional consistency is challenging. For example, when an OrderPlaced event triggers multiple actions, those actions may complete at different times – or even fail independently.

To manage this, developers often use:

Idempotent event handlers (safe to re-run)
Outbox pattern (ensuring events are emitted only after successful database commits)
Saga pattern (for distributed transactions and compensating actions)

These patterns add robustness but also increase system complexity.

3. Message Duplication and Ordering

In distributed systems, you must assume:

Events may arrive twice (due to retries)
Events may arrive out of order

Because of this, consumers need to be designed for idempotency and order independence. Many event stores or brokers (like Kafka) provide partitioning and offsets to preserve partial ordering, but global order is rarely guaranteed.

4. Operational Complexity

While adding a message broker improves decoupling, it also introduces new infrastructure to manage:

Brokers and topics
Retention policies
Consumer groups
Dead-letter queues (for failed messages)

Monitoring and maintaining these systems requires DevOps expertise and mature observability practices.

5. Team and Mental Model Shift

Event-driven systems require developers to think differently:

Systems become reactive, not procedural.
Data flows are eventual, not immediate.
Debugging requires system-wide visibility, not local inspection.

For teams used to request-response logic, this transition can be difficult, requiring training, discipline, and careful design reviews.

Summary

Event-driven architectures offer:

⚙️ Scalability
🧩 Extensibility
🔁 Resilience
⚡ Real-time capabilities

But they demand:

🧠 Rethinking data flow
🔍 Better observability
🧰 Advanced tooling

When implemented carefully, EDAs unlock new levels of system flexibility and business agility, but success depends on balancing their power with strong governance, well-defined event contracts, and team alignment.

In the next section, we’ll look at real-world use cases, examining how leading industries like fintech, e-commerce, and IoT leverage event-driven architectures to achieve scale, responsiveness, and reliability.

9. Real-World Use Cases

Event-driven architectures are not just theoretical patterns. They power many of the systems we use every day. From instant payments to social networks, EDAs provide the backbone for handling real-time data, asynchronous workflows, and massive scalability.

Below are some of the most common and impactful use cases across different industries.

1. Financial and Banking Systems

Financial institutions rely heavily on asynchronous, reliable event flows to process millions of operations safely and in real time.

Typical Events

TransactionInitiated
FundsDeposited
PaymentProcessed
FraudAlertTriggered

How It Works

When a user initiates a payment:

The Payment Service emits a PaymentInitiated event.
The Fraud Detection Service subscribes to it, analyzing risk in parallel.
The Ledger Service records the transaction asynchronously.
The Notification Service sends confirmations.

Each component operates independently, and failures or slow responses in one don’t block others.

Benefits

Real-time fraud detection
Parallel transaction processing
Clear audit trail for compliance (with Event Sourcing)

Example: Modern payment systems (like Revolut, Stripe, and PayPal) use event-driven microservices to orchestrate transactions securely and at scale.

2. E-commerce Platforms

E-commerce systems are naturally event-driven. Every customer action generates events that ripple across subsystems.

Typical Events

OrderCreated
ItemAddedToCart
InventoryUpdated
ShipmentDispatched

Event Flow Example

When a user places an order:

The Order Service emits OrderCreated.
Inventory Service reserves stock.
Billing Service processes the payment.
Shipping Service schedules delivery.
Analytics Service records metrics.

Each step occurs asynchronously, allowing thousands of orders to be processed concurrently.

Benefits

High scalability during peak sales (for example, Black Friday)
Fault isolation between modules
Easy integration of new services (for example, loyalty or recommendation engines)

Example: Amazon and Shopify both use event-based pipelines for order management, tracking, and analytics.

3. IoT and Sensor Networks

In IoT ecosystems, thousands or millions of devices constantly emit data. Event-driven architectures are essential for ingesting, processing, and reacting to these streams efficiently.

Typical Events

TemperatureMeasured
DeviceConnected
MotionDetected
BatteryLow

Event Flow Example

Devices publish sensor data to a message broker (like MQTT, Kafka, or AWS IoT Core).
The Processing Service filters and enriches data.
Alert Services emit notifications if thresholds are crossed.
Analytics Pipelines store aggregated data for insights.

Benefits

Real-time monitoring
Predictive maintenance (based on event patterns)
Scalable ingestion from thousands of sources

Example: Smart cities and connected vehicles use event-driven systems to react to sensor data in milliseconds, adjusting traffic lights, tracking fleets, or monitoring energy grids.

4. Real-Time Analytics and Monitoring

Modern analytics systems depend on stream processing, continuously ingesting and analyzing events to derive insights instantly.

Typical Events

PageViewed
UserLoggedIn
MetricUpdated

Event Flow Example

Applications emit user interaction events to a message queue.
A Stream Processor (like Apache Flink or Kafka Streams) aggregates events in real time.
Dashboards and alerting systems consume processed results via WebSockets or APIs.

Benefits

Live metrics and dashboards
Early anomaly detection
Continuous feedback loops for ML models

Example: Netflix uses event-driven data pipelines (built on Kafka) to monitor playback quality and deliver adaptive streaming experiences in real time.

Social platforms are fundamentally event-driven systems. Every post, like, message, or comment is an event that triggers updates across multiple systems.

Typical Events

PostCreated
MessageSent
UserMentioned
NotificationDelivered

Event Flow Example

When a user sends a message:

The Chat Service emits MessageSent.
The Notification Service alerts the recipient.
The Search Index Service updates conversations.
The Analytics Service logs engagement metrics.

Benefits

Instant notifications and updates
Asynchronous scalability across millions of users
Modular and evolvable product features

Example: Slack, WhatsApp, and Facebook Messenger rely on distributed event buses to coordinate billions of message and presence events per day.

6. Workflow Automation and Orchestration

Workflow systems such as document approvals, CI/CD pipelines, or business processes are often built around events.

Typical Events

TaskCreated
TaskCompleted
ApprovalGranted
PipelineDeployed

How It Works

Each action in a workflow triggers the next step through events, allowing flexible orchestration without hardcoding dependencies. This makes it easy to reconfigure or extend workflows dynamically.

Example: GitHub Actions and Zapier use event-driven models to execute workflows automatically based on triggers (for example, a commit, file upload, or webhook).

Summary

Event-driven architectures power some of the most demanding digital systems in existence. Across industries, they provide:

⚙️ Scalable infrastructure for handling massive event streams
⏱ Real-time responsiveness to user and system actions
🧩 Modularity and evolution as systems grow by subscribing to new events

Whether in fintech, IoT, e-commerce, or analytics, EDAs have proven to be a flexible, future-proof foundation for building systems that react intelligently to change.

In the final section, we’ll synthesize the lessons learned, summarizing best practices, common pitfalls, and key takeaways for adopting event-driven architectures successfully in modern JavaScript ecosystems.

10. Best Practices and Conclusions

Event-driven architectures offer a flexible, scalable, and future-proof foundation for modern software systems. But their power comes with complexity: events are easy to emit but hard to manage at scale without discipline and consistency.

This final section distills practical best practices for designing and operating event-driven systems effectively, followed by a summary reflection on when and how to adopt this architecture.

1. Version and Validate Events

Events evolve over time as your system grows. Adding or changing fields can break consumers if versions aren’t managed carefully.

Best practices:

Use explicit versioning in event names or schemas (for example, order:created.v2).
Validate event payloads using JSON Schema or tools like ajv or Zod.
Maintain a central event catalog or schema registry shared by all services.

This ensures backward compatibility and reduces surprises when consumers update at different times.

2. Design for Idempotency

In distributed systems, duplicate messages are inevitable – retries, network hiccups, or failovers can cause events to be processed multiple times.

Make consumers idempotent, meaning they can handle the same event repeatedly without unintended side effects.

For example:

if (!processedEvents.has(event.id)) {
  process(event);
  processedEvents.add(event.id);
}

Always include a unique event ID and check for duplicates before applying changes.

3. Keep Events Meaningful and Self-Contained

Each event should represent a domain-level change, not just a technical signal. Avoid overly generic messages like "update" or "dataChanged", as they make debugging and evolution difficult.

Good events:

Describe what happened (not what to do).
Include enough context for consumers to act independently.
Avoid exposing internal database models directly.

Example:

{
  "event": "user:email:updated",
  "data": { "userId": 123, "oldEmail": "a@x.com", "newEmail": "b@x.com" }
}

This provides clear, business-oriented semantics.

4. Implement Robust Error Handling and Dead-Letter Queues

Not every event will be processed successfully. Network failures, schema mismatches, or transient service outages are inevitable.

Mitigation strategies:

Use retry policies with exponential backoff.
Send failed messages to a dead-letter queue (DLQ) for inspection.
Build alerting and monitoring on DLQ metrics to detect recurring issues.

This ensures resilience and prevents message loss.

5. Ensure Observability and Traceability

Debugging asynchronous flows requires visibility. Embed tracing and correlation data into your events:

{
  "event": "payment:processed",
  "eventId": "9b7f...c0",
  "traceId": "c74d...d9",
  "timestamp": "2025-11-03T13:45:00Z"
}

Integrate with tools like:

OpenTelemetry for distributed tracing
Jaeger or Zipkin for visualization
Kafka UI, Redpanda Console, or Conduktor for message inspection

This allows you to reconstruct event lifecycles across services, which is critical for debugging, compliance, and performance tuning.

6. Use Patterns for Reliability

Certain design patterns make large-scale event-driven systems more reliable:

Pattern	Purpose
Outbox Pattern	Ensures events are emitted only after DB transactions succeed
Saga Pattern	Coordinates distributed transactions with compensating actions
Event Choreography	Lets services react naturally without central orchestration
Event Carried State Transfer	Includes enough data in events for consumers to act independently

Applying these patterns reduces race conditions and improves data consistency.

7. Choose the Right Broker for the Job

Different brokers serve different use cases:

Broker	Strength
RabbitMQ	Simple, reliable queues; easy to use for small systems
Kafka	High throughput, event persistence, replayability
Redis Streams	Lightweight, in-memory stream processing
NATS / Pulsar	Low-latency, cloud-native messaging for microservices

Your choice depends on throughput, durability, and delivery guarantees.

8. Balance Event-Driven and Request-Driven Approaches

Event-driven systems excel in asynchronous workflows, but not everything should be event-driven.

Use synchronous APIs for immediate, transactional actions (for example, authentication, user profile lookup). And use events for background or decoupled processes (for example, analytics, notifications, async updates).

Combining both models yields the best balance of responsiveness and reliability.

9. Educate and Align the Team

Architecture is as much about people as it is about technology. Ensure developers share a common understanding of event naming conventions, schema versioning policies, error handling and retry rules, and ownership of producer and consumer responsibilities.

Without alignment, even the best tools lead to inconsistent, brittle systems.

10. Start Small, Then Evolve

You don’t need Kafka clusters or event sourcing to begin. Start small:

Use Node.js EventEmitter or a simple in-memory bus for decoupling modules.
Gradually evolve toward distributed brokers as complexity increases.

The key is incremental adoption – building understanding before scaling infrastructure.

Conclusion

Event-driven architectures fundamentally change how we design software. By focusing on what happens rather than what to do next, systems become more adaptable, reactive, and aligned with real-world processes.

In JavaScript – a language born from events – this paradigm feels especially natural. From browser interactions to Node.js microservices, event-driven thinking unifies the frontend and backend under a single principle: react to change.

When used wisely, EDA is not just a design pattern – it’s an architectural mindset that empowers systems to evolve continuously, communicate fluidly, and stay resilient in the face of complexity.

The NestJS Handbook – Learn to Use Nest with Code Examples

German Cocca — Fri, 13 Jun 2025 20:13:49 +0000

NestJS is a progressive Node.js framework for building efficient, reliable, and scalable server-side applications. Combining the best ideas from OOP (Object-Oriented Programming), FP (Functional Programming), and FRP (Functional Reactive Programming), it gives you a fully-architected, batteries-included platform on top of Express (or Fastify).

If you’re coming from Angular, you’ll feel right at home with its module/controller/service structure and powerful dependency-injection system.

In this article we’ll cover both theory – why NestJS exists, how it’s structured, and when to reach for it –and practice, with bite-sized code snippets demonstrating how to bootstrap a project, define routes, inject dependencies, and more. Let’s start by understanding what NestJS is and where it came from.

What is NestJS?
- 1.1 History and Philosophy
Why Choose NestJS?
- 2.1 Benefits and Use Cases
- 2.2 Comparison with Other Frameworks
Getting Started
Core NestJS Building Blocks
Dependency Injection
- 5.1 How DI Works in NestJS
- 5.2 Custom Providers and Factory Providers
Routing & Middleware
- 6.1 Defining Routes
- 6.2 Applying Middleware
Request Lifecycle & Pipes
- 7.1 What Are Pipes?
- 7.2 Built-In vs. Custom Pipes
Guards & Authorization
- 8.1 Implementing Guards
- 8.2 Role-Based Access Control
Exception Filters
- 9.1 Handling Errors Gracefully
- 9.2 Creating Custom Filters
Interceptors & Logging
- 10.1 Transforming Responses
- 10.2 Logging and Performance Metrics
Database Integration
Configuration Management
- 12.1 @nestjs/config Module
- 12.2 Environment Variables
Authentication
- 13.1 JWT Strategy
- 13.2 OAuth2 / Social Login
Conclusion & Further Resources
- Summary
- Official Docs and Community Links

1. What is NestJS?

NestJS is a framework for building server-side applications in Node.js. It’s written in TypeScript (but supports plain JavaScript as well). At its core, it:

Wraps a mature HTTP server library (Express or Fastify)
Standardizes application architecture around modules, controllers, and providers
Leverages TypeScript’s type system for compile-time safety and clear APIs
Offers built-in support for things like validation, configuration, and testing

Rather than stitching together middleware by hand, NestJS encourages a declarative, layered approach. You define modules to group related functionality, controllers to handle incoming requests, and providers (often called “services”) for your business logic. Behind the scenes, NestJS resolves dependencies via an IoC container, so you can focus on writing clean, reusable classes.

To start up a project, run the following commands:

# Install the Nest CLI globally
npm install -g @nestjs/cli

# Create a new project called 'my-app'
nest new my-app

cd my-app
npm run start:dev

Once it’s running, you have a ready-to-go HTTP server with hot reloading, strict typing, and a sensible folder layout.

1.1 History and Philosophy

NestJS first appeared in 2017, created by Kamil Myśliwiec. Its goal was to bring the architectural patterns of Angular to the backend world, providing:

Consistency: A single, opinionated way to structure applications.
Scalability: Clear boundaries (modules) make it easier to grow teams and codebases.
Testability: Built-in support for Jest and clear separation of concerns.
Extensibility: A pluggable module system makes it easy to integrate ORMs, WebSockets, GraphQL, microservices, and more.

Under the hood, NestJS embraces these principles:

Modularity: Everything lives in a module (AppModule, UsersModule, and so on), which can import other modules or export providers.
Dependency Injection: Services can be injected into controllers (and even into other services), which fosters loose coupling.
Decorators and Metadata: With TypeScript decorators (@Module(), @Controller(), @Injectable()), NestJS reads metadata at runtime to wire everything together.

Here’s a tiny example showing the interplay of these pieces:

// users.service.ts
import { Injectable } from '@nestjs/common';

@Injectable()
export class UsersService {
  private users = [{ id: 1, name: 'Alice' }];
  findAll() {
    return this.users;
  }
}

// users.controller.ts
import { Controller, Get } from '@nestjs/common';
import { UsersService } from './users.service';

@Controller('users')
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @Get()
  getUsers() {
    return this.usersService.findAll();
  }
}

// users.module.ts
import { Module } from '@nestjs/common';
import { UsersController } from './users.controller';
import { UsersService } from './users.service';

@Module({
  controllers: [UsersController],
  providers: [UsersService],
})
export class UsersModule {}

The @Module decorator groups controller + service
The controller injects the service via its constructor
A simple GET /users route returns an array of user objects

With that foundation laid, in the next section we’ll explore why you’d choose NestJS, comparing it to other popular Node frameworks and outlining common real-world use cases.

2. Why Choose NestJS?

NestJS isn’t just another Node.js framework – it brings a structured, enterprise-grade approach to building backend services. In this section we’ll cover benefits and real-world use cases, then compare NestJS to other popular Node frameworks so you can see where it fits best.

2.1 Benefits and Use Cases

Strong architectural patterns
- Modularity: You break your app into focused modules (AuthModule, ProductsModule, and so on), each responsible for a slice of functionality.
- Separation of concerns: Controllers handle HTTP, services encapsulate business logic, modules wire everything up.
- Scalability: Growing teams map naturally onto modules—new features rarely touch existing code.
Built-in dependency injection (DI)
- DI makes testing and swapping implementations trivial.
- You can easily mock a service in a unit test:

    // products.controller.spec.ts
    import { Test, TestingModule } from '@nestjs/testing';
    import { ProductsController } from './products.controller';
    import { ProductsService } from './products.service';

    describe('ProductsController', () => {
      let controller: ProductsController;
      const mockService = { findAll: () => ['apple', 'banana'] };

      beforeEach(async () => {
        const module: TestingModule = await Test.createTestingModule({
          controllers: [ProductsController],
          providers: [
            { provide: ProductsService, useValue: mockService },
          ],
        }).compile();

        controller = module.get(ProductsController);
      });

      it('returns a list of products', () => {
        expect(controller.getAll()).toEqual(['apple', 'banana']);
      });
    });

TypeScript-first
- Full type safety at compile time.
- Leverage interfaces and decorators (@Body(), @Param()) to validate and transform data.
Rich ecosystem and extensibility
- Official integrations for WebSockets, GraphQL, microservices (RabbitMQ, Kafka), and more.
- Hundreds of community modules (for example @nestjs/swagger for OpenAPI docs).
Production-grade tooling
- CLI generates boilerplate (nest g module, nest g service).
- Support for hot-reload in development (npm run start:dev).
- Built-in testing setup with Jest.

Real-World Use Cases:

Enterprise APIs with strict module boundaries and RBAC.
Microservices architectures, where each service is a self-contained NestJS app.
Real-time applications (chat, live dashboards) using Nest’s WebSocket gateways.
GraphQL backends with code-first schemas.
Event-driven systems connecting to message brokers.

2.2 Comparison with Other Frameworks

Feature	Express	Koa	NestJS
Architecture	Minimal, unopinionated	Minimal, middleware-based	Opinionated modules/controllers/services
Dependency Injection	Manual wiring	Manual wiring	Built-in, reflect-metadata
TypeScript Support	Via DefinitelyTyped	Via DefinitelyTyped	First-class, decorators
CLI Tooling	None (3rd-party)	None	`@nestjs/cli` generates code
Testing	User-configured	User-configured	Jest + DI makes mocking easy
Ecosystem	Middleware library	Middleware library	Official microservices, GraphQL, Swagger modules
Learning Curve	Low	Low	Medium (learning Nest idioms)

Express is great if you want minimal layers and full control, but you’ll end up hand-rolling a lot (DI, validation, folder structure).
Koa offers a more modern middleware approach, but still leaves architecture decisions to you.
NestJS provides the full stack: structure, DI, validation, testing, and official integrations, which is ideal if you value consistency, type safety, and out-of-the-box best practices.

When to choose NestJS:

NextJS is great for various use cases. It’s particularly effective if you’re building a large-scale API or microservice suite, if you want a solid architecture from day one, and if you prefer TypeScript and DI to keep code testable and maintainable.

With these advantages in mind, you’ll find that NestJS can dramatically speed up development, especially on projects that need robust structure and clear boundaries.

In the next section, we’ll dive into getting started: installing the CLI, creating a project, and exploring the generated folder layout.

3. Getting Started

Let’s jump into the basics: installing the CLI, scaffolding a new project, and exploring the default folder layout.

3.1 Installing the CLI

Nest ships with an official command-line tool that helps you generate modules, controllers, services, and more. Under the hood it uses Yeoman templates to keep everything consistent.

# Install the CLI globally (requires npm ≥ 6)
npm install -g @nestjs/cli

Once installed, you can run nest --help to see available commands:

nest --help
Usage: nest <command> [options]

Commands:
  new        Scaffold a new project
  generate|g  [options]  Generate artifacts (modules, controllers, ...)
  build            Build project with webpack
  ...

Options:
  -v, --version    Show version number
  -h, --help       Show help

3.2 Creating Your First Project

Scaffolding a new app is a single command. The CLI will ask whether to use npm or yarn, and whether to enable strict TypeScript settings.

# Create a new Nest app in the "my-nest-app" folder
nest new my-nest-app

After answering the prompts, you’ll have:

cd my-nest-app
npm run start:dev

This launches a development server on http://localhost:3000 with automatic reload on file changes.

3.3 Project Structure Overview

By default, you’ll see something like:

my-nest-app/
├── src/
│   ├── app.controller.ts      # example controller
│   ├── app.controller.spec.ts # unit test for controller
│   ├── app.module.ts          # root application module
│   ├── app.service.ts         # example provider
│   └── main.ts                # entry point (bootstraps Nest)
├── test/                      # end-to-end tests
├── node_modules/
├── package.json
├── tsconfig.json
└── nest-cli.json             # CLI configuration

src/main.ts
The “bootstrap” script. It creates a Nest application instance and starts listening on a port:

  import { NestFactory } from '@nestjs/core';
  import { AppModule } from './app.module';

  async function bootstrap() {
    const app = await NestFactory.create(AppModule);
    await app.listen(3000);
    console.log(`🚀 Application is running on: ${await app.getUrl()}`);
  }
  bootstrap();

src/app.module.ts
The root module. It ties together controllers and providers:

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

  @Module({
    imports: [],                 // other modules to import
    controllers: [AppController],
    providers: [AppService],
  })
  export class AppModule {}

src/app.controller.ts / app.service.ts
A simple example that shows dependency injection in action:

  // app.controller.ts
  import { Controller, Get } from '@nestjs/common';
  import { AppService } from './app.service';

  @Controller()
  export class AppController {
    constructor(private readonly appService: AppService) {}

    @Get()
    getHello(): string {
      return this.appService.getHello();
    }
  }

  // app.service.ts
  import { Injectable } from '@nestjs/common';

  @Injectable()
  export class AppService {
    getHello(): string {
      return 'Hello, NestJS!';
    }
  }

With this scaffold in place, you have a minimal – but fully functional – NestJS application. From here, you can generate new modules, controllers, and services:

# Generate a new module, controller, and service for "tasks"
nest g module tasks
nest g controller tasks
nest g service tasks

Each command will drop a new .ts file in the appropriate folder and update your module’s metadata. In the next section, we’ll dive into core Nest building blocks like modules, controllers, and providers in more detail.

4. Core NestJS Building Blocks

At the heart of every NestJS application are three pillars: Modules, Controllers, and Providers (often called Services). Let’s see what each one does, and how they fit together in theory and in practice.

4.1 Modules

A Module is a logical boundary – a container that groups related components (controllers, providers, and even other modules). Every NestJS app has at least one root module (usually AppModule), and you create feature modules (UsersModule, AuthModule, and so on) to organize code by domain.

@Module() Decorator

imports: other modules to use
controllers: controllers that handle incoming requests
providers: services or values available via DI
exports: providers that should be visible to importing modules

Here’s an example:

// cats.module.ts
import { Module } from '@nestjs/common';
import { CatsController } from './cats.controller';
import { CatsService } from './cats.service';

@Module({
  imports: [],            // e.g. TypeOrmModule.forFeature([Cat])
  controllers: [CatsController],
  providers: [CatsService],
  exports: [CatsService], // makes CatsService available to other modules
})
export class CatsModule {}

Then in your root module:

// app.module.ts
import { Module } from '@nestjs/common';
import { CatsModule } from './cats/cats.module';

@Module({
  imports: [CatsModule],
})
export class AppModule {}

Now anything that injects CatsService will resolve to the one defined inside CatsModule.

4.2 Controllers

A Controller maps incoming HTTP requests to handler methods. It’s responsible for extracting request data (query parameters, body, headers) and returning a response. Controllers should remain thin – delegating business logic to providers.

@Controller(path?): Defines a route prefix
@Get, @Post, @Put, @Delete, and so on: Define method-level routes
@Param(), @Query(), @Body(), @Headers(), @Req(), @Res(): Decorators to extract request details

Here’s an example:

// cats.controller.ts
import { Controller, Get, Post, Body, Param } from '@nestjs/common';
import { CatsService } from './cats.service';
import { CreateCatDto } from './dto/create-cat.dto';

@Controller('cats')                  // prefix: /cats
export class CatsController {
  constructor(private readonly catsService: CatsService) {}

  @Get()
  findAll() {
    return this.catsService.findAll();  // GET /cats
  }

  @Get(':id')
  findOne(@Param('id') id: string) {
    return this.catsService.findOne(+id);  // GET /cats/1
  }

  @Post()
  create(@Body() createCatDto: CreateCatDto) {
    return this.catsService.create(createCatDto);  // POST /cats
  }
}

// dto/create-cat.dto.ts
export class CreateCatDto {
  readonly name: string;
  readonly age: number;
  readonly breed?: string;
}

4.3 Providers (Services)

Providers are classes annotated with @Injectable() that contain your business logic or data access. Anything you want to inject elsewhere must be a provider. You can provide plain values, factory functions, or classes.

@Injectable(): Marks a class as available for DI
Scope: Default is singleton, but you can change to request or transient
Custom Providers: Use useClass, useValue, useFactory, or useExisting for more control

Here’s an example:

// cats.service.ts
import { Injectable, NotFoundException } from '@nestjs/common';
import { CreateCatDto } from './dto/create-cat.dto';

@Injectable()
export class CatsService {
  private cats = [];

  create(dto: CreateCatDto) {
    const newCat = { id: Date.now(), ...dto };
    this.cats.push(newCat);
    return newCat;
  }

  findAll() {
    return this.cats;
  }

  findOne(id: number) {
    const cat = this.cats.find(c => c.id === id);
    if (!cat) {
      throw new NotFoundException(`Cat #${id} not found`);
    }
    return cat;
  }
}

Injecting a Custom Value:

// logger.provider.ts
export const LOGGER = {
  provide: 'LOGGER',
  useValue: console,
};

// app.module.ts
import { Module } from '@nestjs/common';
import { LOGGER } from './logger.provider';

@Module({
  providers: [LOGGER],
  exports: [LOGGER],
})
export class AppModule {}

// some.service.ts
import { Inject, Injectable } from '@nestjs/common';

@Injectable()
export class SomeService {
  constructor(@Inject('LOGGER') private readonly logger: Console) {}

  logMessage(msg: string) {
    this.logger.log(`Custom log: ${msg}`);
  }
}

With modules wiring up controllers and providers, NestJS gives you a scalable, testable foundation. In the next section, we’ll explore Dependency Injection in depth – how it works under the hood and how to create custom providers and factory-based injections.

5. Dependency Injection

Nest’s built-in Dependency Injection (DI) system is the heart of how components (controllers, services, and so on) talk to each other in a loosely-coupled, testable way.

5.1 How DI Works in NestJS

When your application boots, Nest builds a module-based IoC container. Each @Injectable() provider is registered in the container under a token (by default, its class). When a class declares a dependency in its constructor, Nest looks up that token and injects the matching instance.

Singleton scope: One instance per application (default)
Request scope: New instance per incoming request
Transient scope: New instance every time it’s injected

Here’s an example:

// cats.service.ts
@Injectable()
export class CatsService {
  // ...
}

// cats.controller.ts
@Controller('cats')
export class CatsController {
  constructor(private readonly catsService: CatsService) {}
  // Nest sees CatsService in the constructor,
  // finds its singleton instance, and injects it.
}

Behind the scenes, Nest collects metadata from decorators (@Injectable(), @Controller()) and builds a graph of providers. When you call NestFactory.create(AppModule), it resolves that graph and wires everything together.

5.2 Custom Providers and Factory Providers

Sometimes you need to inject non-class values (APIs, constants) or run logic at registration time. Nest lets you define custom providers using the provide syntax.

`useValue`

Inject a plain value or object:

// config.constant.ts
export const APP_NAME = {
  provide: 'APP_NAME',
  useValue: 'MyAwesomeApp',
};

// app.module.ts
@Module({
  providers: [APP_NAME],
  exports: ['APP_NAME'],
})
export class AppModule {}

// some.service.ts
@Injectable()
export class SomeService {
  constructor(@Inject('APP_NAME') private readonly name: string) {}

  whoAmI() {
    return `Running in ${this.name}`;
  }
}

`useClass`

Swap implementations easily (useful for testing or feature flags):

// logger.interface.ts
export interface Logger {
  log(msg: string): void;
}

// console-logger.ts
@Injectable()
export class ConsoleLogger implements Logger {
  log(msg: string) { console.log(msg); }
}

// file-logger.ts
@Injectable()
export class FileLogger implements Logger {
  log(msg: string) { /* write to file */ }
}

// app.module.ts
@Module({
  providers: [
    { provide: 'Logger', useClass: FileLogger }, 
  ],
})
export class AppModule {}

// any.service.ts
@Injectable()
export class AnyService {
  constructor(@Inject('Logger') private readonly logger: Logger) {}
}

`useFactory`

Run arbitrary factory logic (for example, async initialization, dynamic config):

// database.provider.ts
export const DATABASE = {
  provide: 'DATABASE',
  useFactory: async (configService: ConfigService) => {
    const opts = configService.getDbOptions();
    const connection = await createConnection(opts);
    return connection;
  },
  inject: [ConfigService],
};

// app.module.ts
@Module({
  imports: [ConfigModule],
  providers: [DATABASE],
  exports: ['DATABASE'],
})
export class AppModule {}

// users.service.ts
@Injectable()
export class UsersService {
  constructor(@Inject('DATABASE') private readonly db: Connection) {}
}

With custom providers and the factory pattern, you can integrate external libraries, toggle implementations, or perform async setup – all while retaining the clear, testable structure NestJS provides.

In the next section we’ll look at Routing and Middleware, showing how to define route handlers, apply global or per-route middleware, and extend your HTTP pipeline.

6. Routing & Middleware

Routing in NestJS is built on top of your controllers and decorators, while middleware lets you hook into the request/response pipeline for cross-cutting concerns like logging, authentication checks, or CORS.

6.1 Defining Routes

First, a bit of theory:

@Controller(path?) sets a URL prefix for all routes in that class.
@Get, @Post, @Put, @Delete, etc. define HTTP-method handlers.
@Param(), @Query(), @Body(), @Headers(), @Req(), @Res() extract parts of the incoming request.

You can combine route decorators and parameter decorators to build expressive, type-safe endpoints.

Here’s an example:

// products.controller.ts
import { Controller, Get, Post, Param, Query, Body } from '@nestjs/common';
import { ProductsService } from './products.service';
import { CreateProductDto } from './dto/create-product.dto';

@Controller('products')                // all routes here start with /products
export class ProductsController {
  constructor(private readonly productsService: ProductsService) {}

  @Get()                              // GET /products
  findAll(
    @Query('limit') limit = '10',     // optional query ?limit=20
  ) {
    return this.productsService.findAll(+limit);
  }

  @Get(':id')                         // GET /products/123
  findOne(@Param('id') id: string) {
    return this.productsService.findOne(+id);
  }

  @Post()                             // POST /products
  create(@Body() dto: CreateProductDto) {
    return this.productsService.create(dto);
  }
}

You can also nest controllers by importing a feature module, and use @Patch, @Put, @Delete, @Head, and so on for full RESTful coverage.

6.2 Applying Middleware

Middleware are functions that run before your routes handle a request. They’re useful for logging, body-parsing (though Nest provides built-ins), authentication guards at a lower level, rate limiting, and so on.

You can implement them either as a functional middleware or a class implementing NestMiddleware.

Here’s an example (Functional Middleware):

// logger.middleware.ts
import { Request, Response, NextFunction } from 'express';

export function logger(req: Request, res: Response, next: NextFunction) {
  console.log(`[${new Date().toISOString()}] ${req.method} ${req.url}`);
  next();
}

// app.module.ts
import { Module, NestModule, MiddlewareConsumer } from '@nestjs/common';
import { logger } from './logger.middleware';
import { ProductsModule } from './products/products.module';

@Module({
  imports: [ProductsModule],
})
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer
      .apply(logger)                 // apply logger
      .forRoutes('products');        // only for /products routes
  }
}

And here’s another example (Class-based Middleware):

// auth.middleware.ts
import { Injectable, NestMiddleware } from '@nestjs/common';
import { Request, Response, NextFunction } from 'express';

@Injectable()
export class AuthMiddleware implements NestMiddleware {
  use(req: Request, res: Response, next: NextFunction) {
    if (!req.headers.authorization) {
      return res.status(401).send('Unauthorized');
    }
    // validate token...
    next();
  }
}

// security.module.ts
import { Module, NestModule, MiddlewareConsumer } from '@nestjs/common';
import { AuthMiddleware } from './auth.middleware';
import { UsersController } from './users.controller';

@Module({
  controllers: [UsersController],
})
export class SecurityModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer
      .apply(AuthMiddleware)
      .forRoutes(UsersController);    // apply to all routes in UsersController
  }
}

Tip: Global middleware can be applied in your main.ts before the app.listen() call via app.use(logger) if you want it on every request.

With routing and middleware set up, you have full control over how requests flow through your application. Next up, we’ll dive into Request Lifecycle and Pipes, exploring how data transforms and validations happen as part of each request.

7. Request Lifecycle & Pipes

NestJS processes each incoming request through a defined “lifecycle” of steps – routing to the correct handler, applying pipes, guards, interceptors, and finally invoking your controller method. Pipes sit between the incoming request and your handler, transforming or validating data before it reaches your business logic.

7.1 What Are Pipes?

A Pipe is a class annotated with @Injectable() that implements the PipeTransform interface. It has a single method:

transform(value: any, metadata: ArgumentMetadata): any

Transformation: Convert input data (for example, a string "123") into the desired type (number 123).
Validation: Check that incoming data meets certain rules and throw an exception (usually a BadRequestException) if it doesn’t.

By default, pipes run after middleware and before guards/interceptors, for each decorated parameter (@Body(), @Param(), and so on).

Here’s how it works:
Nest ships with a handy global validation pipe that integrates with class-validator:

// main.ts
import { ValidationPipe } from '@nestjs/common';
import { NestFactory }    from '@nestjs/core';
import { AppModule }      from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  // Automatically validate and strip unknown properties
  app.useGlobalPipes(new ValidationPipe({ whitelist: true, forbidNonWhitelisted: true }));
  await app.listen(3000);
}
bootstrap();

With this in place, any DTO annotated with validation decorators will be checked before your handler runs:

// dto/create-user.dto.ts
import { IsEmail, IsString, MinLength } from 'class-validator';

export class CreateUserDto {
  @IsEmail()           // must be a valid email
  email: string;

  @IsString()          // must be a string
  @MinLength(8)        // at least 8 characters
  password: string;
}

// users.controller.ts
@Post()
createUser(@Body() dto: CreateUserDto) {
  // If body.email isn't an email, or password is shorter,
  // Nest throws a 400 Bad Request with details.
  return this.usersService.create(dto);
}

7.2 Built-In vs. Custom Pipes

Built-In Pipes

Nest provides several out-of-the-box pipes:

ValidationPipe: Integrates with class-validator for DTO validation (shown above).
ParseIntPipe: Converts a route parameter to number or throws BadRequestException.
ParseBoolPipe, ParseUUIDPipe, ParseFloatPipe, and so on.

@Get(':id')
getById(@Param('id', ParseIntPipe) id: number) {
  // id is guaranteed to be a number here
  return this.itemsService.findOne(id);
}

Custom Pipes

You can write your own to handle any transformation or validation logic:

import { PipeTransform, Injectable, BadRequestException } from '@nestjs/common';

@Injectable()
export class ParsePositiveIntPipe implements PipeTransform<string, number> {
  transform(value: string): number {
    const val = parseInt(value, 10);
    if (isNaN(val) || val <= 0) {
      throw new BadRequestException(`"${value}" is not a positive integer`);
    }
    return val;
  }
}

Use it just like a built-in pipe:

@Get('order/:orderId')
getOrder(
  @Param('orderId', ParsePositiveIntPipe) orderId: number
) {
  // orderId is a validated, positive integer
  return this.ordersService.findById(orderId);
}

With pipes you ensure that every piece of data entering your handlers is correctly typed and valid, keeping your business logic clean and focused. In the next section, we’ll explore Guards and Authorization to control access to your endpoints.

8. Guards & Authorization

Guards sit in the request lifecycle after pipes and before interceptors/controllers. They determine whether a given request should be allowed to proceed based on custom logic. This is ideal for authentication, role checks, or feature flags.

8.1 Implementing Guards

A Guard is a class that implements the CanActivate interface, with a single method:

canActivate(context: ExecutionContext): boolean | Promise<boolean> | Observable<boolean>;

ExecutionContext gives you access to the underlying request/response and route metadata.
If canActivate returns true, the request continues. Returning false or throwing an exception (for example, UnauthorizedException) blocks it.

You register guards either globally, at the controller level, or on individual routes with the @UseGuards() decorator.

Here’s how guards work:

Creating a simple auth guard:

// auth.guard.ts
import { Injectable, CanActivate, ExecutionContext, UnauthorizedException } from '@nestjs/common';

@Injectable()
export class AuthGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean {
    const req = context.switchToHttp().getRequest();
    const authHeader = req.headers.authorization;
    if (!authHeader || !authHeader.startsWith('Bearer ')) {
      throw new UnauthorizedException('Missing or invalid authorization header');
    }
    // Basic token check (replace with real validation)
    const token = authHeader.split(' ')[1];
    if (token !== 'valid-token') {
      throw new UnauthorizedException('Invalid token');
    }
    // Attach user info if needed:
    req.user = { id: 1, name: 'Alice' };
    return true;
  }
}

Applying the guard

Globally (in main.ts):

  import { NestFactory } from '@nestjs/core';
  import { AppModule } from './app.module';
  import { AuthGuard } from './auth.guard';

  async function bootstrap() {
    const app = await NestFactory.create(AppModule);
    // every incoming request passes through AuthGuard
    app.useGlobalGuards(new AuthGuard());
    await app.listen(3000);
  }
  bootstrap();

Controller-Level:

  import { Controller, Get, UseGuards } from '@nestjs/common';
  import { AuthGuard } from './auth.guard';

  @Controller('profile')
  @UseGuards(AuthGuard)       // applies to all routes in this controller
  export class ProfileController {
    @Get()
    getProfile(@Req() req) {
      return req.user;
    }
  }

Route-Level:

  @Get('admin')
  @UseGuards(AdminGuard, AuthGuard)  // chain multiple guards
  getAdminData() { /* ... */ }

8.2 Role-Based Access Control

Beyond plain authentication, you often need authorization – ensuring a user has the correct role or permission. You can build a guard that reads metadata (for example, required roles) and verifies user claims.

Here’s how it works:

Define a roles decorator:

// roles.decorator.ts
import { SetMetadata } from '@nestjs/common';
export const Roles = (...roles: string[]) => SetMetadata('roles', roles);

Create a roles guard:

// roles.guard.ts
import { Injectable, CanActivate, ExecutionContext, ForbiddenException } from '@nestjs/common';
import { Reflector } from '@nestjs/core';

@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    const requiredRoles = this.reflector.get<string[]>('roles', context.getHandler());
    if (!requiredRoles) {
      return true; // no roles metadata => open route
    }
    const { user } = context.switchToHttp().getRequest();
    const hasRole = requiredRoles.some(role => user.roles?.includes(role));
    if (!hasRole) {
      throw new ForbiddenException('You do not have permission (roles)');
    }
    return true;
  }
}

Apply roles metadata and guard:

@Controller('projects')
@UseGuards(AuthGuard, RolesGuard)
export class ProjectsController {
  @Get()
  @Roles('user', 'admin')         // route requires either 'user' or 'admin'
  findAll() { /* ... */ }

  @Post()
  @Roles('admin')                 // only 'admin' can create
  create() { /* ... */ }
}

With this setup:

AuthGuard ensures the request is authenticated and populates req.user.
RolesGuard reads the @Roles() metadata to enforce role-based access.

Guards give you a powerful, declarative way to enforce security and authorization policies. In the next section, we’ll cover Exception Filters – how to catch and format errors centrally, keeping your controllers clean.

9. Exception Filters

Exception filters let you centralize error handling, transforming thrown exceptions into consistent HTTP responses or other formats. You can rely on Nest’s built-in behavior for many cases, but custom filters give you control over logging, response shape, or handling non-HTTP errors.

9.1 Handling Errors Gracefully

By default, if a controller or service throws an HttpException (or one of Nest’s built-in exceptions like NotFoundException, BadRequestException, and so on), Nest catches it and sends an appropriate HTTP response with status code and JSON body containing statusCode, message, and error.

If an unexpected error (for example, a runtime error) bubbles up, Nest uses its default exception filter to return a 500 Internal Server Error with a generic message.

Controllers/services should throw exceptions rather than return error codes manually, so the framework can format consistently.

Here’s how it works:

// users.service.ts
import { Injectable, NotFoundException } from '@nestjs/common';

@Injectable()
export class UsersService {
  private users = [{ id: 1, name: 'Alice' }];

  findOne(id: number) {
    const user = this.users.find(u => u.id === id);
    if (!user) {
      // results in 404 with JSON { statusCode: 404, message: 'User #2 not found', error: 'Not Found' }
      throw new NotFoundException(`User #${id} not found`);
    }
    return user;
  }
}

// users.controller.ts
import { Controller, Get, Param, ParseIntPipe } from '@nestjs/common';

@Controller('users')
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @Get(':id')
  getUser(@Param('id', ParseIntPipe) id: number) {
    return this.usersService.findOne(id);
  }
}

If findOne throws, Nest’s default filter sends a structured JSON error. For unexpected errors (like a thrown Error), Nest wraps it into a 500 response.

9.2 Creating Custom Filters

You can implement the ExceptionFilter interface or extend BaseExceptionFilter. Just use the @Catch() decorator to target specific exception types (or leave empty to catch all).

In catch(exception, host), you can extract context (HTTP request/response) and shape your response (for example, add metadata, custom fields, or a uniform envelope). You can also log exceptions or report to external systems here.

You can apply filters globally, to a controller, or to an individual route.

Here’s how it works:

Simple logging filter
Catch all exceptions, log details, then delegate to default behavior:

 // logging-exception.filter.ts
 import {
   ExceptionFilter,
   Catch,
   ArgumentsHost,
   HttpException,
   HttpStatus,
   Logger,
 } from '@nestjs/common';
 import { BaseExceptionFilter } from '@nestjs/core';

 @Catch() // no args = catch every exception
 export class LoggingExceptionFilter extends BaseExceptionFilter {
   private readonly logger = new Logger(LoggingExceptionFilter.name);

   catch(exception: unknown, host: ArgumentsHost) {
     const ctx = host.switchToHttp();
     const req = ctx.getRequest();
     const res = ctx.getResponse();

     // Log stack or message
     if (exception instanceof Error) {
       this.logger.error(`Error on ${req.method} ${req.url}`, exception.stack);
     } else {
       this.logger.error(`Unknown exception on ${req.method} ${req.url}`);
     }

     // Delegate to default filter for HTTP exceptions or generic 500
     super.catch(exception, host);
   }
 }

Apply globally in main.ts:

 async function bootstrap() {
   const app = await NestFactory.create(AppModule);
   app.useGlobalFilters(new LoggingExceptionFilter(app.get(HttpAdapterHost)));
   await app.listen(3000);
 }

(If extending BaseExceptionFilter, pass the adapter host to the constructor or super as needed.)

Custom response shape
Suppose you want all errors to return { success: false, error: { code, message } }:

 // custom-response.filter.ts
 import {
   ExceptionFilter,
   Catch,
   ArgumentsHost,
   HttpException,
   HttpStatus,
 } from '@nestjs/common';

 @Catch()
 export class CustomResponseFilter implements ExceptionFilter {
   catch(exception: unknown, host: ArgumentsHost) {
     const ctx = host.switchToHttp();
     const response = ctx.getResponse();
     const request = ctx.getRequest();

     let status: number;
     let message: string | object;

     if (exception instanceof HttpException) {
       status = exception.getStatus();
       const res = exception.getResponse();
       // res might be a string or object
       message = typeof res === 'string' ? { message: res } : res;
     } else {
       status = HttpStatus.INTERNAL_SERVER_ERROR;
       message = { message: 'Internal server error' };
     }

     response.status(status).json({
       success: false,
       error: {
         statusCode: status,
         ...(
           typeof message === 'object'
             ? message
             : { message }
         ),
       },
       timestamp: new Date().toISOString(),
       path: request.url,
     });
   }
 }

Apply at controller or route level:

 @Controller('orders')
 @UseFilters(CustomResponseFilter)
 export class OrdersController {
   // ...
 }

Catching specific exceptions
If you have a custom exception class:

 export class PaymentFailedException extends HttpException {
   constructor(details: string) {
     super({ message: 'Payment failed', details }, HttpStatus.PAYMENT_REQUIRED);
   }
 }

You can write a filter that only catches that:

 @Catch(PaymentFailedException)
 export class PaymentFailedFilter implements ExceptionFilter {
   catch(exception: PaymentFailedException, host: ArgumentsHost) {
     const ctx = host.switchToHttp();
     const res = ctx.getResponse();
     const status = exception.getStatus();
     const { message, details } = exception.getResponse() as any;
     res.status(status).json({
       error: {
         message,
         details,
       },
       help: 'Please verify your payment method and retry.',
     });
   }
 }

Then apply only where payments occur:

 @Post('charge')
 @UseFilters(PaymentFailedFilter)
 charge() {
   // ...
 }

With exception filters in place, you ensure a consistent error contract, centralized logging or reporting, and tailored handling of different error types. Next up: Interceptors and Logging, where we’ll see how to transform responses, measure performance, and hook around method execution.

10. Interceptors & Logging

Interceptors wrap around method execution, letting you transform responses, bind extra logic before/after method calls, or measure performance. They’re ideal for cross-cutting concerns like logging, response shaping, caching, or timing metrics.

10.1 Transforming Responses

An Interceptor implements the NestInterceptor interface with an intercept(context, next) method.

Inside intercept, you typically call next.handle() which returns an Observable of the handler’s result. You can then apply RxJS operators (like map) to modify the data before it’s sent to the client.

Common uses are wrapping all responses in a uniform envelope, filtering out certain fields, or adding metadata.

Here’s how it works:

Basic response wrapper
Suppose you want every successful response to be { success: true, data: }.

 // response.interceptor.ts
 import {
   Injectable,
   NestInterceptor,
   ExecutionContext,
   CallHandler,
 } from '@nestjs/common';
 import { Observable } from 'rxjs';
 import { map } from 'rxjs/operators';

 @Injectable()
 export class ResponseInterceptor implements NestInterceptor {
   intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
     return next.handle().pipe(
       map(data => ({
         success: true,
         data,
       })),
     );
   }
 }

Apply globally in main.ts:

 import { NestFactory } from '@nestjs/core';
 import { AppModule } from './app.module';
 import { ResponseInterceptor } from './common/response.interceptor';

 async function bootstrap() {
   const app = await NestFactory.create(AppModule);
   app.useGlobalInterceptors(new ResponseInterceptor());
   await app.listen(3000);
 }
 bootstrap();

Now, if a controller method returns { id: 1, name: 'Alice' }, the client sees:

 {
   "success": true,
   "data": { "id": 1, "name": "Alice" }
 }

Filtering sensitive fields
You might want to strip out fields like password before sending a user object:

 // sanitize.interceptor.ts
 import {
   Injectable,
   NestInterceptor,
   ExecutionContext,
   CallHandler,
 } from '@nestjs/common';
 import { Observable } from 'rxjs';
 import { map } from 'rxjs/operators';

 @Injectable()
 export class SanitizeInterceptor implements NestInterceptor {
   intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
     return next.handle().pipe(
       map(data => {
         if (data && typeof data === 'object') {
           const { password, ...rest } = data;
           return rest;
         }
         return data;
       }),
     );
   }
 }

Apply at controller or route:

 @Controller('users')
 @UseInterceptors(SanitizeInterceptor)
 export class UsersController {
   @Get(':id')
   getUser(@Param('id') id: string) {
     // returns a user object with a password field internally,
     // but interceptor strips it before sending to client
     return this.usersService.findOne(+id);
   }
 }

Serializing with class-transformer
If you use classes with decorators, you can integrate with class-transformer:

 // user.entity.ts
 import { Exclude, Expose } from 'class-transformer';

 export class User {
   id: number;
   name: string;

   @Exclude()
   password: string;

   @Expose()
   get displayName(): string {
     return `${this.name} (#${this.id})`;
   }
 }

 // class-transform.interceptor.ts
 import {
   Injectable,
   NestInterceptor,
   ExecutionContext,
   CallHandler,
 } from '@nestjs/common';
 import { plainToInstance } from 'class-transformer';
 import { Observable } from 'rxjs';
 import { map } from 'rxjs/operators';

 @Injectable()
 export class ClassTransformInterceptor implements NestInterceptor {
   constructor(private dto: new (...args: any[]) => T) {}

   intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
     return next.handle().pipe(
       map(data => {
         return plainToInstance(this.dto, data, {
           excludeExtraneousValues: true,
         });
       }),
     );
   }
 }

Apply with a DTO:

 @Controller('users')
 export class UsersController {
   @Get(':id')
   @UseInterceptors(new ClassTransformInterceptor(User))
   getUser(@Param('id') id: string) {
     // service returns a plain object; interceptor transforms to User instance
     return this.usersService.findOne(+id);
   }
 }

10.2 Logging and Performance Metrics

Interceptors can also measure execution time or log request/response details. You capture timestamps before and after next.handle(), logging the difference. This helps monitor slow endpoints. Combined with a logging framework or Nest’s Logger, you can standardize logs.

Here’s how it works:

Timing interceptor
Logs how long each request-handler takes:

 // logging.interceptor.ts
 import {
   Injectable,
   NestInterceptor,
   ExecutionContext,
   CallHandler,
   Logger,
 } from '@nestjs/common';
 import { Observable } from 'rxjs';
 import { tap } from 'rxjs/operators';

 @Injectable()
 export class LoggingInterceptor implements NestInterceptor {
   private readonly logger = new Logger(LoggingInterceptor.name);

   intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
     const req = context.switchToHttp().getRequest();
     const method = req.method;
     const url = req.url;
     const now = Date.now();
     return next.handle().pipe(
       tap(() => {
         const elapsed = Date.now() - now;
         this.logger.log(`${method} ${url} - ${elapsed}ms`);
       }),
     );
   }
 }

Apply globally:

 async function bootstrap() {
   const app = await NestFactory.create(AppModule);
   app.useGlobalInterceptors(new LoggingInterceptor());
   await app.listen(3000);
 }

Now each request logs something like:

 [LoggingInterceptor] GET /users/1 - 35ms

Detailed request/response logging
For more detail, log request body or response size (careful with sensitive data):

 // detailed-logging.interceptor.ts
 import {
   Injectable,
   NestInterceptor,
   ExecutionContext,
   CallHandler,
   Logger,
 } from '@nestjs/common';
 import { Observable } from 'rxjs';
 import { tap, map } from 'rxjs/operators';

 @Injectable()
 export class DetailedLoggingInterceptor implements NestInterceptor {
   private readonly logger = new Logger('HTTP');

   intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
     const ctx = context.switchToHttp();
     const req = ctx.getRequest();
     const { method, url, body } = req;
     const now = Date.now();

     this.logger.log(`Incoming ${method} ${url} - body: ${JSON.stringify(body)}`);

     return next.handle().pipe(
       map(data => {
         const elapsed = Date.now() - now;
         this.logger.log(`Response ${method} ${url} - ${elapsed}ms - data: ${JSON.stringify(data)}`);
         return data;
       }),
     );
   }
 }

Apply conditionally: perhaps only in development:

 if (process.env.NODE_ENV !== 'production') {
   app.useGlobalInterceptors(new DetailedLoggingInterceptor());
 }

Combining with guards/pipes
Since interceptors run after guards and before the response is sent, logging time captures the full handler including service calls, but after validation/authorization. That ensures you measure only authorized requests and valid data flows.

Interceptors offer a flexible way to wrap your handlers with extra behavior: transforming outputs, sanitizing data, timing execution, or adding headers. In the next section, we’ll explore Database integration to see how you can integrate your data layer in Nest.

11. Database Integration

In many real-world applications, persisting data is essential. NestJS offers first-class support and integrations for several database technologies. In this section we cover three common approaches:

TypeORM with NestJS (relational databases, Active Record/Data Mapper style)
Mongoose (MongoDB) (NoSQL document store)
Prisma (Type-safe query builder/ORM alternative)

For each, we’ll explain the theory – when and why to choose it – and show concise practical examples of setup and usage in a NestJS context.

11.1 TypeORM with NestJS

TypeORM is a popular ORM for Node.js that supports multiple relational databases (PostgreSQL, MySQL, SQLite, SQL Server, and so on), offering both Active Record and Data Mapper patterns.

In NestJS, the @nestjs/typeorm package wraps TypeORM to provide:

Automatic connection management via TypeOrmModule.forRoot()
Module-scoped repositories/entities via TypeOrmModule.forFeature()
Dependency injection for repositories and the DataSource/Connection
Entity decorators (@Entity(), @Column(), and so on) for schema definition
Migrations and advanced features via TypeORM CLI or programmatic usage

When to choose TypeORM

Type ORM is useful in several scenarios. Use it when your data is relational and you want a full-featured ORM with decorators and built-in migrations. It’s also great if you prefer to work with classes/entities and automatically map them to tables. And it’s a great choice if you value built-in features like eager/lazy relations, cascading, query builders, and repository patterns.

Here’s how to use it:

Install dependencies:

 npm install --save @nestjs/typeorm typeorm reflect-metadata
 # Also install the database driver; e.g., for Postgres:
 npm install --save pg

Configure the root module:

In app.module.ts, import TypeOrmModule.forRoot() with connection options. These can come from environment variables (discussed later in Configuration Management).

 // src/app.module.ts
 import { Module } from '@nestjs/common';
 import { TypeOrmModule } from '@nestjs/typeorm';
 import { UsersModule } from './users/users.module';

 @Module({
   imports: [
     TypeOrmModule.forRoot({
       type: 'postgres',
       host: process.env.DB_HOST || 'localhost',
       port: +process.env.DB_PORT || 5432,
       username: process.env.DB_USER || 'postgres',
       password: process.env.DB_PASS || 'password',
       database: process.env.DB_NAME || 'mydb',
       entities: [__dirname + '/**/*.entity{.ts,.js}'],
       synchronize: false, // recommended false in production; use migrations
       // logging: true,
     }),
     UsersModule,
     // ...other modules
   ],
 })
 export class AppModule {}

synchronize: true can auto-sync schema in development, but in production prefer migrations.
Entities are auto-loaded via glob. Ensure path matches compiled output.

Define an entity:

Create an entity class with decorators:

 // src/users/user.entity.ts
 import { Entity, PrimaryGeneratedColumn, Column, CreateDateColumn, UpdateDateColumn } from 'typeorm';

 @Entity({ name: 'users' })
 export class User {
   @PrimaryGeneratedColumn()
   id: number;

   @Column({ unique: true })
   email: string;

   @Column()
   password: string;

   @Column({ nullable: true })
   name?: string;

   @CreateDateColumn()
   createdAt: Date;

   @UpdateDateColumn()
   updatedAt: Date;
 }

Set up the feature module:

 // src/users/users.module.ts
 import { Module } from '@nestjs/common';
 import { TypeOrmModule } from '@nestjs/typeorm';
 import { UsersService } from './users.service';
 import { UsersController } from './users.controller';
 import { User } from './user.entity';

 @Module({
   imports: [TypeOrmModule.forFeature([User])],
   providers: [UsersService],
   controllers: [UsersController],
   exports: [UsersService], // if other modules need UsersService
 })
 export class UsersModule {}

Inject the repository:

In the service, inject the Repository:

 // src/users/users.service.ts
 import { Injectable, NotFoundException } from '@nestjs/common';
 import { InjectRepository } from '@nestjs/typeorm';
 import { Repository } from 'typeorm';
 import { User } from './user.entity';
 import { CreateUserDto } from './dto/create-user.dto';

 @Injectable()
 export class UsersService {
   constructor(
     @InjectRepository(User)
     private readonly userRepository: Repository,
   ) {}

   async create(dto: CreateUserDto): Promise {
     const user = this.userRepository.create(dto); // maps DTO fields to entity
     return this.userRepository.save(user);
   }

   async findAll(): Promise {
     return this.userRepository.find();
   }

   async findOne(id: number): Promise {
     const user = await this.userRepository.findOne({ where: { id } });
     if (!user) {
       throw new NotFoundException(`User #${id} not found`);
     }
     return user;
   }

   async update(id: number, dto: Partial): Promise {
     const user = await this.findOne(id);
     Object.assign(user, dto);
     return this.userRepository.save(user);
   }

   async remove(id: number): Promise<void> {
     await this.userRepository.delete(id);
   }
 }

Use in controller:

 // src/users/users.controller.ts
 import { Controller, Get, Post, Body, Param, ParseIntPipe, Put, Delete } from '@nestjs/common';
 import { UsersService } from './users.service';
 import { CreateUserDto } from './dto/create-user.dto';

 @Controller('users')
 export class UsersController {
   constructor(private readonly usersService: UsersService) {}

   @Post()
   create(@Body() dto: CreateUserDto) {
     return this.usersService.create(dto);
   }

   @Get()
   findAll() {
     return this.usersService.findAll();
   }

   @Get(':id')
   findOne(@Param('id', ParseIntPipe) id: number) {
     return this.usersService.findOne(id);
   }

   @Put(':id')
   update(
     @Param('id', ParseIntPipe) id: number,
     @Body() dto: Partial,
   ) {
     return this.usersService.update(id, dto);
   }

   @Delete(':id')
   remove(@Param('id', ParseIntPipe) id: number) {
     return this.usersService.remove(id);
   }
 }

Migrations (optional but recommended)
- Use TypeORM CLI or programmatic migrations.
- Configure a separate ormconfig or supply options in code.
- Generate and run migrations to evolve schema without data loss.

11.2 Mongoose (MongoDB)

Mongoose is a widely used ODM (Object Document Mapper) for MongoDB. In NestJS, @nestjs/mongoose integrates Mongoose to:

Define schemas via classes and decorators (@Schema(), @Prop())
Register models in modules with MongooseModule.forFeature()
Manage the MongoDB connection with MongooseModule.forRoot()
Inject Mongoose Model instances into services
Work with documents in a type-safe way (with interfaces/types)
Leverage features like hooks, virtuals, and validation at schema level

When to choose Mongoose

Mongoose is a good choice if you need a document-oriented, schema-less/ schematized NoSQL store. It’s also great if your data shapes may vary, or you prefer MongoDB’s flexible schema. And it’s helpful if you want features like middleware hooks in schema (pre/post save), virtuals, and so on.

Here’s how to use it:

Install dependencies:

 npm install --save @nestjs/mongoose mongoose

Configure root module:

 // src/app.module.ts
 import { Module } from '@nestjs/common';
 import { MongooseModule } from '@nestjs/mongoose';
 import { CatsModule } from './cats/cats.module';

 @Module({
   imports: [
     MongooseModule.forRoot(process.env.MONGO_URI || 'mongodb://localhost/nest'),
     CatsModule,
     // ...other modules
   ],
 })
 export class AppModule {}

Define a schema and document:

Use decorators and interfaces:

 // src/cats/schemas/cat.schema.ts
 import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose';
 import { Document } from 'mongoose';

 @Schema({ timestamps: true })
 export class Cat extends Document {
   @Prop({ required: true })
   name: string;

   @Prop()
   age: number;

   @Prop()
   breed: string;
 }

 export const CatSchema = SchemaFactory.createForClass(Cat);

Extending Document gives the Mongoose document methods and properties.
timestamps: true auto-adds createdAt and updatedAt.

You can add hooks:

  CatSchema.pre('save', function (next) {
    // e.g., modify data or log before saving
    next();
  });

Set up feature module:

 // src/cats/cats.module.ts
 import { Module } from '@nestjs/common';
 import { MongooseModule } from '@nestjs/mongoose';
 import { CatsService } from './cats.service';
 import { CatsController } from './cats.controller';
 import { Cat, CatSchema } from './schemas/cat.schema';

 @Module({
   imports: [
     MongooseModule.forFeature([{ name: Cat.name, schema: CatSchema }]),
   ],
   controllers: [CatsController],
   providers: [CatsService],
 })
 export class CatsModule {}

Inject the model:

In the service, inject Model:

 // src/cats/cats.service.ts
 import { Injectable, NotFoundException } from '@nestjs/common';
 import { InjectModel } from '@nestjs/mongoose';
 import { Model } from 'mongoose';
 import { Cat } from './schemas/cat.schema';
 import { CreateCatDto } from './dto/create-cat.dto';
 import { UpdateCatDto } from './dto/update-cat.dto';

 @Injectable()
 export class CatsService {
   constructor(
     @InjectModel(Cat.name) private readonly catModel: Model,
   ) {}

   async create(dto: CreateCatDto): Promise {
     const created = new this.catModel(dto);
     return created.save();
   }

   async findAll(): Promise {
     return this.catModel.find().exec();
   }

   async findOne(id: string): Promise {
     const cat = await this.catModel.findById(id).exec();
     if (!cat) {
       throw new NotFoundException(`Cat ${id} not found`);
     }
     return cat;
   }

   async update(id: string, dto: UpdateCatDto): Promise {
     const updated = await this.catModel
       .findByIdAndUpdate(id, dto, { new: true })
       .exec();
     if (!updated) {
       throw new NotFoundException(`Cat ${id} not found`);
     }
     return updated;
   }

   async remove(id: string): Promise<void> {
     const res = await this.catModel.findByIdAndDelete(id).exec();
     if (!res) {
       throw new NotFoundException(`Cat ${id} not found`);
     }
   }
 }

Use in controller:

 // src/cats/cats.controller.ts
 import { Controller, Get, Post, Body, Param, Put, Delete } from '@nestjs/common';
 import { CatsService } from './cats.service';
 import { CreateCatDto } from './dto/create-cat.dto';
 import { UpdateCatDto } from './dto/update-cat.dto';

 @Controller('cats')
 export class CatsController {
   constructor(private readonly catsService: CatsService) {}

   @Post()
   create(@Body() dto: CreateCatDto) {
     return this.catsService.create(dto);
   }

   @Get()
   findAll() {
     return this.catsService.findAll();
   }

   @Get(':id')
   findOne(@Param('id') id: string) {
     return this.catsService.findOne(id);
   }

   @Put(':id')
   update(
     @Param('id') id: string,
     @Body() dto: UpdateCatDto,
   ) {
     return this.catsService.update(id, dto);
   }

   @Delete(':id')
   remove(@Param('id') id: string) {
     return this.catsService.remove(id);
   }
 }

Advanced Mongoose features
- Virtuals: define computed properties not stored in DB.
- Indexes: via schema options or @Prop({ index: true }).
- Populate: reference other collections with @Prop({ type: Types.ObjectId, ref: 'OtherModel' }).
- Transactions: use MongoDB sessions for multi-document atomic operations.

11.3 Prisma

Prisma is a modern ORM/Query Builder that generates a type-safe client based on a schema definition. It supports relational databases (PostgreSQL, MySQL, SQLite, SQL Server, and more).

Here are some of its key features:

Type-safe queries: Autogenerated TypeScript definitions prevent many runtime errors.
Prisma schema: A declarative .prisma file to define models, relations, and enums.
Migrations: prisma migrate for evolving schema.
Performance: Lean query builder without heavy runtime overhead.
Flexibility: Supports raw queries when needed.

When to choose Prisma

Prisma is a great choice if you prefer a schema-first approach with a clear DSL and auto-generated type-safe client. It’s also great if you want modern features like efficient migrations, rich type inference, and a straightforward developer experience. And it’s a solid choice if you don’t need Active Record pattern. Instead, you use the Prisma client in services.

Here’s how it works:

Install dependencies and initialize:
```
 npm install @prisma/client
 npm install -D prisma
 npx prisma init
```
This creates a prisma/schema.prisma file and a .env with DATABASE_URL.

Define the schema:

In prisma/schema.prisma:

 datasource db {
   provider = "postgresql"
   url      = env("DATABASE_URL")
 }

 generator client {
   provider = "prisma-client-js"
 }

 model User {
   id        Int      @id @default(autoincrement())
   email     String   @unique
   name      String?
   posts     Post[]
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt
 }

 model Post {
   id        Int      @id @default(autoincrement())
   title     String
   content   String?
   author    User     @relation(fields: [authorId], references: [id])
   authorId  Int
   published Boolean  @default(false)
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt
 }

Run migrations and generate client:
```
 npx prisma migrate dev --name init
 npx prisma generate
```
This updates the database schema and regenerates the TypeScript client.

Create a PrismaService in NestJS:

A common pattern is to wrap the PrismaClient in an injectable service, handling lifecycle hooks.

 // src/prisma/prisma.service.ts
 import { Injectable, OnModuleInit, OnModuleDestroy } from '@nestjs/common';
 import { PrismaClient } from '@prisma/client';

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

   async onModuleDestroy() {
     await this.$disconnect();
   }
 }

Register PrismaService in a module:

 // src/prisma/prisma.module.ts
 import { Module } from '@nestjs/common';
 import { PrismaService } from './prisma.service';

 @Module({
   providers: [PrismaService],
   exports: [PrismaService],
 })
 export class PrismaModule {}

Then import PrismaModule in any feature module needing DB access.

Use in a feature service:

 // src/users/users.service.ts
 import { Injectable } from '@nestjs/common';
 import { PrismaService } from '../prisma/prisma.service';
 import { CreateUserDto } from './dto/create-user.dto';

 @Injectable()
 export class UsersService {
   constructor(private readonly prisma: PrismaService) {}

   async create(dto: CreateUserDto) {
     return this.prisma.user.create({ data: dto });
   }

   async findAll() {
     return this.prisma.user.findMany();
   }

   async findOne(id: number) {
     return this.prisma.user.findUnique({ where: { id } });
   }

   async update(id: number, dto: Partial) {
     return this.prisma.user.update({
       where: { id },
       data: dto,
     });
   }

   async remove(id: number) {
     await this.prisma.user.delete({ where: { id } });
     return { deleted: true };
   }
 }

Note: DTO fields must align with Prisma schema types. Prisma client methods return typed results.

Inject in controller:

 // src/users/users.controller.ts
 import { Controller, Get, Post, Body, Param, ParseIntPipe, Put, Delete } from '@nestjs/common';
 import { UsersService } from './users.service';
 import { CreateUserDto } from './dto/create-user.dto';

 @Controller('users')
 export class UsersController {
   constructor(private readonly usersService: UsersService) {}

   @Post()
   create(@Body() dto: CreateUserDto) {
     return this.usersService.create(dto);
   }

   @Get()
   findAll() {
     return this.usersService.findAll();
   }

   @Get(':id')
   findOne(@Param('id', ParseIntPipe) id: number) {
     return this.usersService.findOne(id);
   }

   @Put(':id')
   update(
     @Param('id', ParseIntPipe) id: number,
     @Body() dto: Partial,
   ) {
     return this.usersService.update(id, dto);
   }

   @Delete(':id')
   remove(@Param('id', ParseIntPipe) id: number) {
     return this.usersService.remove(id);
   }
 }

Advanced Prisma usage
- Relations and nested writes: for example, create a post with nested author connect/create.
- Transactions: this.prisma.$transaction([...]) for atomic operations.
- Raw queries: this.prisma.$queryRaw when needed.
- Middleware: Prisma supports middlewares on the client side.
- Performance tuning: select only needed fields, use pagination patterns.

With these three approaches, you can choose the database integration strategy that best fits your application’s needs:

TypeORM for a full-fledged ORM with decorators and migrations support in relational databases.
Mongoose for flexible document schemas in MongoDB.
Prisma for a modern, type-safe query builder/ORM alternative with excellent developer ergonomics.

In the next section, we’ll cover Configuration Management – how to handle environment variables and config modules in NestJS.

12. Configuration Management

Managing configuration cleanly is crucial for applications to behave correctly across environments (development, staging, production). NestJS provides the @nestjs/config module to centralize configuration loading, validation, and injection.

12.1 @nestjs/config Module

The @nestjs/config module is a powerful utility for managing application configuration settings. Here are some of its key features:

Centralized config: Instead of sprinkling process.env throughout your code, it uses a dedicated service that loads and validates configuration once at startup.
Environment agnostic: It loads variables from .env files, environment variables, or other sources, with support for different files per environment.
Validation: It integrates a schema (for example, via Joi) to ensure required variables are present and correctly typed, failing fast if misconfigured.
Config Namespacing: It organizes related settings into logical groups (for example, database, auth, third-party APIs) via configuration factories.
Injection: It injects a ConfigService to read config values in services or modules, with type safety when using custom typed wrappers.

Here’s how it works:

Install the package

 npm install @nestjs/config
 npm install joi    # if you plan to validate via Joi schemas

Import and initialize ConfigModule

In your root module (AppModule), import ConfigModule.forRoot(). Typical options:

 // src/app.module.ts
 import { Module } from '@nestjs/common';
 import { ConfigModule } from '@nestjs/config';
 import configuration from './config/configuration';
 import { validationSchema } from './config/validation';

 @Module({
   imports: [
     ConfigModule.forRoot({
       // Load .env automatically; specify envFilePath if custom:
       isGlobal: true,           // makes ConfigService available app-wide
       envFilePath: ['.env.development.local', '.env.development', '.env'], 
       load: [configuration],    // optional: load custom config factory(s)
       validationSchema,         // optional: Joi schema to validate env vars
       validationOptions: {
         allowUnknown: true,
         abortEarly: true,
       },
     }),
     // ...other modules
   ],
 })
 export class AppModule {}

isGlobal: true avoids importing ConfigModule in every feature module.
envFilePath: an array lets you try multiple files (for example, local overrides before default).
load: array of functions returning partial config objects – see next step.
validationSchema: a Joi schema ensuring required variables exist and are correct type/format.

Define a configuration factory

Organize related settings into a typed object:

 // src/config/configuration.ts
 export default () => ({
   port: parseInt(process.env.PORT, 10) || 3000,
   database: {
     host: process.env.DB_HOST,
     port: parseInt(process.env.DB_PORT, 10) || 5432,
     user: process.env.DB_USER,
     pass: process.env.DB_PASS,
     name: process.env.DB_NAME,
   },
   jwt: {
     secret: process.env.JWT_SECRET,
     expiresIn: process.env.JWT_EXPIRES_IN || '1h',
   },
   // add other namespaces as needed
 });

Validate environment variables

Using Joi for validation:

 // src/config/validation.ts
 import * as Joi from 'joi';

 export const validationSchema = Joi.object({
   NODE_ENV: Joi.string()
     .valid('development', 'production', 'test', 'staging')
     .default('development'),
   PORT: Joi.number().default(3000),
   DB_HOST: Joi.string().required(),
   DB_PORT: Joi.number().default(5432),
   DB_USER: Joi.string().required(),
   DB_PASS: Joi.string().required(),
   DB_NAME: Joi.string().required(),
   JWT_SECRET: Joi.string().min(32).required(),
   JWT_EXPIRES_IN: Joi.string().default('1h'),
   // add other variables...
 });

If validation fails at startup, the application will error out with details, preventing misconfigured deployments.

Inject ConfigService

Anywhere you need config, inject ConfigService:

 // src/some/some.service.ts
 import { Injectable } from '@nestjs/common';
 import { ConfigService } from '@nestjs/config';

 @Injectable()
 export class SomeService {
   constructor(private readonly configService: ConfigService) {}

   getDbConfig() {
     const host = this.configService.get<string>('database.host');
     const port = this.configService.get<number>('database.port');
     // Use these values to configure a database client, etc.
     return { host, port };
   }
 }

Use dot notation for nested config: for example, 'jwt.secret'.
You can also read raw env vars via configService.get('DB_HOST') if needed, but preferring structured config is clearer.

Typed wrapper for ConfigService (optional)

For stronger typing, create an interface matching your configuration and a wrapper:

 // src/config/config.interface.ts
 export interface AppConfig {
   port: number;
   database: {
     host: string;
     port: number;
     user: string;
     pass: string;
     name: string;
   };
   jwt: {
     secret: string;
     expiresIn: string;
   };
 }

 // src/config/typed-config.service.ts
 import { Injectable } from '@nestjs/common';
 import { ConfigService } from '@nestjs/config';
 import { AppConfig } from './config.interface';

 @Injectable()
 export class TypedConfigService {
   constructor(private readonly configService: ConfigService) {}

   get appConfig(): AppConfig {
     return {
       port: this.configService.get<number>('port'),
       database: {
         host: this.configService.get<string>('database.host'),
         port: this.configService.get<number>('database.port'),
         user: this.configService.get<string>('database.user'),
         pass: this.configService.get<string>('database.pass'),
         name: this.configService.get<string>('database.name'),
       },
       jwt: {
         secret: this.configService.get<string>('jwt.secret'),
         expiresIn: this.configService.get<string>('jwt.expiresIn'),
       },
     };
   }
 }

Dynamic module registration using config

Many Nest modules accept dynamic options. For example, TypeORM:

 // src/database/database.module.ts
 import { Module } from '@nestjs/common';
 import { TypeOrmModule } from '@nestjs/typeorm';
 import { ConfigService } from '@nestjs/config';

 @Module({
   imports: [
     TypeOrmModule.forRootAsync({
       inject: [ConfigService],
       useFactory: (config: ConfigService) => ({
         type: 'postgres',
         host: config.get<string>('database.host'),
         port: config.get<number>('database.port'),
         username: config.get<string>('database.user'),
         password: config.get<string>('database.pass'),
         database: config.get<string>('database.name'),
         entities: [__dirname + '/../**/*.entity{.ts,.js}'],
         synchronize: config.get('NODE_ENV') !== 'production',
       }),
     }),
   ],
 })
 export class DatabaseModule {}

Using forRootAsync with useFactory ensures config is loaded before the module initializes.

12.2 Environment Variables

Environment variables serve as the bridge between code and its runtime environment, letting you decouple configuration (like database URLs, API keys, or feature flags) from your source.

By relying on environment variables, you ensure that the same application bundle can run safely across development, staging, and production – each providing its own sensitive or environment-specific settings without changing code. This is how it works:

12-Factor app principle: Stores config in the environment. Avoids hard-coding secrets or environment-specific settings in code.
Separation of concerns: Code remains the same across environments. Behavior is driven by env vars or config files.
Security: Keeps secrets (API keys, DB passwords) out of source control. Uses environment variables or secure vaults.
Overrides and precedence: You may have multiple .env files (for example, .env, .env.local, .env.production) or CI/CD provided vars. It controls the order of loading.
Defaults and fallbacks: Provides sensible defaults in code or config factories so the app can run in development without requiring every variable.

Here’s how to use it:

.env files
- Create a .env file at project root with key-value pairs:
```
  PORT=3000
  DB_HOST=localhost
  DB_PORT=5432
  DB_USER=postgres
  DB_PASS=secret
  DB_NAME=mydb
  JWT_SECRET=supersecretjwtkey
  JWT_EXPIRES_IN=2h
```
- Optionally create .env.development, .env.test, .env.production, and load them based on NODE_ENV.
- Ensure .env files are in .gitignore to avoid committing secrets.
Loading order
- With @nestjs/config, specify envFilePath as an array, for example:
```
  ConfigModule.forRoot({
    envFilePath: [
      `.env.${process.env.NODE_ENV}.local`,
      `.env.${process.env.NODE_ENV}`,
      `.env`,
    ],
    isGlobal: true,
  });
```
- This tries .env.development.local, then .env.development, then .env. CI/CD can set actual environment variables that override values in files.
Accessing raw environment variables
- While structured config is preferred, sometimes you need direct access:
```
  const raw = process.env.SOME_VAR;
```
- Avoid scattering process.env in multiple places. Instead, prefer reading once in configuration factory and injecting via ConfigService.

Default values

In configuration factory or when reading via ConfigService, provide defaults:

  const port = configService.get<number>('PORT', 3000);

or in factory:

  port: parseInt(process.env.PORT, 10) || 3000

Type coercion

Environment variables are strings by default. Convert to numbers or booleans as needed:

  const isProd = configService.get<string>('NODE_ENV') === 'production';
  const enableFeature = configService.get<string>('FEATURE_FLAG') === 'true';
  const timeout = parseInt(configService.get<string>('TIMEOUT_MS'), 10) || 5000;

Secret management
- For sensitive data in production, consider using secret managers (AWS Secrets Manager, Vault) instead of plain .env. In that case, load secrets at startup (for example, via a custom provider or factory) and merge into the configuration.
- Example: in useFactory, asynchronously fetch secrets and return a config object including them.
Runtime configuration changes
- Generally configs are static at startup. If you need to reload config without restarting, implement a custom mechanism (for example, read from a database or remote config service periodically). Inject a service that fetches and caches values, but note this departs from 12-factor principles.
Validation in production
- Always validate required env vars at startup so misconfigurations fail early. Use validationSchema with Joi or another validator.
- Example error: if JWT_SECRET is missing or too short, the app should refuse to start, logging a clear error.

With configuration managed via @nestjs/config and environment variables, your NestJS app can adapt seamlessly across environments, keep secrets secure, and avoid environment-specific code changes. In the next section, we’ll cover Authentication strategies (JWT, OAuth2/social login).

13. Authentication

Handling authentication securely is a common requirement. In NestJS, you typically use Passport strategies alongside the @nestjs/jwt module for JWT-based flows, or OAuth2 strategies for social login.

Here, we’ll cover two common approaches:

JWT Strategy: token-based authentication for APIs.
OAuth2 / Social Login: integrating providers like Google or GitHub.

13.1 JWT Strategy

JSON Web Tokens (JWTs) are a compact, URL-safe means of representing claims between two parties. In an authentication context, the server issues a signed token containing user identity and possibly other claims, while the client stores and sends this token on subsequent requests (typically in the Authorization: Bearer header).

Because the token is signed (and optionally encrypted), the server can verify its integrity and authenticity without needing to maintain session state in memory or a database. This stateless nature simplifies scaling and decouples services.

Tokens include an expiration (exp) so they automatically become invalid after a certain time. For longer-lived sessions, you can layer a refresh-token pattern on top.

In NestJS, we leverage @nestjs/jwt to sign and verify tokens and @nestjs/passport with passport-jwt to integrate a guard that checks incoming tokens. Below is how it works.

JWT (JSON Web Token): a signed token containing claims (for example, user ID) that clients send in the Authorization header.
Stateless: the server verifies the token signature without storing session state.
Expiration: embed expiry (exp) so tokens auto-expire; possibly use refresh tokens for long-lived sessions.
In NestJS, you use @nestjs/jwt to sign/verify tokens and @nestjs/passport with passport-jwt to implement the guard.

Here’s how to use it:

Install dependencies

 npm install @nestjs/jwt passport-jwt @nestjs/passport passport

Configuration

Use ConfigService (from previous section) to load secrets and TTL:

 // src/auth/auth.config.ts
 export default () => ({
   jwt: {
     secret: process.env.JWT_SECRET || 'default-secret',
     expiresIn: process.env.JWT_EXPIRES_IN || '1h',
   },
 });

Ensure ConfigModule.forRoot({ load: [authConfig], isGlobal: true, validationSchema: ... }) is set in AppModule.

AuthModule setup

 // src/auth/auth.module.ts
 import { Module } from '@nestjs/common';
 import { JwtModule } from '@nestjs/jwt';
 import { PassportModule } from '@nestjs/passport';
 import { ConfigService, ConfigModule } from '@nestjs/config';
 import { JwtStrategy } from './jwt.strategy';
 import { AuthService } from './auth.service';
 import { UsersModule } from '../users/users.module'; // assumes a UsersService

 @Module({
   imports: [
     UsersModule,
     PassportModule.register({ defaultStrategy: 'jwt' }),
     JwtModule.registerAsync({
       imports: [ConfigModule],
       inject: [ConfigService],
       useFactory: (config: ConfigService) => ({
         secret: config.get<string>('jwt.secret'),
         signOptions: { expiresIn: config.get<string>('jwt.expiresIn') },
       }),
     }),
   ],
   providers: [AuthService, JwtStrategy],
   exports: [AuthService],
 })
 export class AuthModule {}

AuthService

Responsible for validating credentials and issuing tokens:

 // src/auth/auth.service.ts
 import { Injectable, UnauthorizedException } from '@nestjs/common';
 import { JwtService } from '@nestjs/jwt';
 import { UsersService } from '../users/users.service';
 import * as bcrypt from 'bcrypt';

 @Injectable()
 export class AuthService {
   constructor(
     private readonly usersService: UsersService,
     private readonly jwtService: JwtService,
   ) {}

   // Validate user credentials (email/password)
   async validateUser(email: string, pass: string) {
     const user = await this.usersService.findByEmail(email);
     if (user && (await bcrypt.compare(pass, user.password))) {
       // exclude password before returning
       const { password, ...result } = user;
       return result;
     }
     return null;
   }

   // Called after validateUser succeeds
   async login(user: any) {
     const payload = { sub: user.id, email: user.email };
     return {
       access_token: this.jwtService.sign(payload),
     };
   }
 }

JwtStrategy

 // src/auth/jwt.strategy.ts
 import { Injectable } from '@nestjs/common';
 import { PassportStrategy } from '@nestjs/passport';
 import { ExtractJwt, Strategy } from 'passport-jwt';
 import { ConfigService } from '@nestjs/config';

 @Injectable()
 export class JwtStrategy extends PassportStrategy(Strategy) {
   constructor(private readonly configService: ConfigService) {
     super({
       jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
       ignoreExpiration: false,
       secretOrKey: configService.get<string>('jwt.secret'),
     });
   }

   async validate(payload: any) {
     // payload.sub is user ID
     return { userId: payload.sub, email: payload.email };
     // returned value is assigned to req.user
   }
 }

Auth Controller

Expose login endpoint:

 // src/auth/auth.controller.ts
 import { Controller, Post, Body, Request, UseGuards } from '@nestjs/common';
 import { AuthService } from './auth.service';
 import { LocalAuthGuard } from './local-auth.guard'; // optional if using local strategy

 @Controller('auth')
 export class AuthController {
   constructor(private readonly authService: AuthService) {}

   // Example: using a local strategy for email/password
   @UseGuards(LocalAuthGuard)
   @Post('login')
   async login(@Request() req) {
     // LocalAuthGuard attaches user to req.user
     return this.authService.login(req.user);
   }

   // Alternatively, implement login logic directly:
   @Post('login-basic')
   async loginBasic(@Body() body: { email: string; password: string }) {
     const user = await this.authService.validateUser(body.email, body.password);
     if (!user) {
       throw new UnauthorizedException('Invalid credentials');
     }
     return this.authService.login(user);
   }
 }

LocalAuthGuard would use a LocalStrategy to validate credentials via Passport.

Protecting routes

Use the JwtAuthGuard:

 // src/auth/jwt-auth.guard.ts
 import { Injectable } from '@nestjs/common';
 import { AuthGuard } from '@nestjs/passport';

 @Injectable()
 export class JwtAuthGuard extends AuthGuard('jwt') {}

Apply to controllers or routes:

 // src/profile/profile.controller.ts
 import { Controller, Get, UseGuards, Request } from '@nestjs/common';
 import { JwtAuthGuard } from '../auth/jwt-auth.guard';

 @Controller('profile')
 export class ProfileController {
   @UseGuards(JwtAuthGuard)
   @Get()
   getProfile(@Request() req) {
     return req.user; // { userId, email }
   }
 }

Refresh Tokens (optional)
- Issue a refresh token (longer expiry) and store it (for example, in DB or as HTTP-only cookie).
- Create a separate endpoint to issue new access token when the access token expires.
- Verify refresh token validity (for example, compare stored token or a hashed version).
- Implementation details vary – consider security best practices (rotate tokens, revoke on logout).

Social login via OAuth2 lets users authenticate with third-party providers (Google, GitHub, Facebook, and so on) without creating a separate password for your service.

Under the Authorization Code Flow, the user is redirected to the provider’s consent screen. After granting permission, the provider redirects back with a temporary code. The backend exchanges this code for access (and optionally refresh) tokens, fetches the user’s profile, and then you can link or create a local user record. Finally, you typically issue your own JWT (or session) so the client can call your secured APIs.

Keeping OAuth client IDs/secrets in environment variables (via ConfigService) ensures security and flexibility. Here’s how it works:

OAuth2 Authorization Code Flow: Redirect the user to the provider’s consent screen. The provider redirects back with a code. The back-end exchanges code for tokens and retrieves user info.
In server-side (NestJS) you use Passport strategies (for example, passport-google-oauth20, passport-github2).
After getting user profile from provider, you look up or create a matching local user record, then issue your own JWT or session.
Keep secrets (client ID/secret) in environment variables and load via ConfigService.

Here’s how to use it:

Install dependencies

 npm install @nestjs/passport passport passport-google-oauth20
 # or passport-facebook, passport-github2, etc.

Configuration

Add OAuth credentials to env and ConfigModule:

 GOOGLE_CLIENT_ID=your-google-client-id
 GOOGLE_CLIENT_SECRET=your-google-client-secret
 GOOGLE_CALLBACK_URL=http://localhost:3000/auth/google/callback

OAuth Strategy

Example: Google

 // src/auth/google.strategy.ts
 import { Injectable } from '@nestjs/common';
 import { PassportStrategy } from '@nestjs/passport';
 import { Strategy, VerifyCallback } from 'passport-google-oauth20';
 import { ConfigService } from '@nestjs/config';
 import { AuthService } from './auth.service';

 @Injectable()
 export class GoogleStrategy extends PassportStrategy(Strategy, 'google') {
   constructor(configService: ConfigService, private readonly authService: AuthService) {
     super({
       clientID: configService.get<string>('GOOGLE_CLIENT_ID'),
       clientSecret: configService.get<string>('GOOGLE_CLIENT_SECRET'),
       callbackURL: configService.get<string>('GOOGLE_CALLBACK_URL'),
       scope: ['email', 'profile'],
     });
   }

   async validate(accessToken: string, refreshToken: string, profile: any, done: VerifyCallback): Promise<any> {
     const { id, emails, displayName } = profile;
     const email = emails && emails[0]?.value;
     // Delegate to AuthService to find or create local user
     const user = await this.authService.validateOAuthLogin('google', id, email, displayName);
     done(null, user);
   }
 }

In AuthService:

 // src/auth/auth.service.ts (add method)
 async validateOAuthLogin(provider: string, providerId: string, email: string, name?: string) {
   // Find existing user by provider+providerId or email
   let user = await this.usersService.findByProvider(provider, providerId);
   if (!user) {
     // Optionally check by email: if exists, link accounts; otherwise create new
     user = await this.usersService.createOAuthUser({ provider, providerId, email, name });
   }
   // Issue JWT or return user object; here we return minimal payload for login
   return user;
 }

AuthController endpoints

 // src/auth/auth.controller.ts
 import { Controller, Get, Req, UseGuards } from '@nestjs/common';
 import { AuthGuard } from '@nestjs/passport';
 import { AuthService } from './auth.service';

 @Controller('auth')
 export class AuthController {
   constructor(private readonly authService: AuthService) {}

   @Get('google')
   @UseGuards(AuthGuard('google'))
   async googleAuth(@Req() req) {
     // Initiates Google OAuth2 flow
   }

   @Get('google/callback')
   @UseGuards(AuthGuard('google'))
   async googleAuthRedirect(@Req() req) {
     // Google redirects here after consent; req.user set by GoogleStrategy.validate
     const user = req.user;
     // Issue JWT or set a cookie, then redirect or return token
     const jwt = await this.authService.login(user);
     // E.g., redirect with token as query, or set cookie:
     // res.redirect(`http://frontend-app.com?token=${jwt.access_token}`);
     return { access_token: jwt.access_token };
   }
 }

The first endpoint (/auth/google) triggers redirect to Google.
The callback endpoint handles the response, then issues your JWT.

Session vs. Stateless
- Many examples use sessions and @nestjs/passport session support, but for APIs you often skip sessions: Passport still invokes validate, returns user, and you issue JWT immediately.
- Ensure you disable sessions in PassportModule registration: PassportModule.register({ session: false }).
Multiple Providers
- Repeat strategy setup for each provider (for example, GitHubStrategy).
- In validateOAuthLogin, handle provider parameter to distinguish logic.
- You can store in your user entity fields like googleId, githubId, and so on, or a separate table for OAuth accounts.
Protecting routes post-login
- Clients use the issued JWT in Authorization: Bearer to access protected endpoints via JwtAuthGuard.
- If you prefer sessions/cookies, configure Nest to use sessions and Passport's session features, but for SPAs or mobile clients JWT is common.
Frontend considerations
- Redirect URIs must match those configured in the OAuth provider console.
- After receiving JWT, store it securely (for example, HTTP-only cookie or secure storage on client).
- Handle token expiry: possibly combine OAuth refresh tokens or your own refresh token flow.

With JWT and OAuth2 strategies set up, your NestJS backend can support secured endpoints, user registration/login flows, and social logins.

Conclusion & Further Resources

Summary

We’ve walked through key aspects of building a NestJS application: its architectural patterns, core building blocks (modules, controllers, providers), dependency injection, routing and middleware, request lifecycle with pipes, guards, exception filters, interceptors, database integration options (TypeORM, Mongoose, Prisma), configuration management, authentication strategies (JWT, OAuth2), and strategies for migrating existing apps.

NestJS provides a structured, TypeScript-first framework that accelerates development of scalable, maintainable backends. By leveraging its module system and built-in integrations, you get consistency, testability, and clear separation of concerns out of the box.

Whether you choose a relational database via TypeORM, a document store with Mongoose, or Prisma’s type-safe client, you can plug these into Nest’s DI container and configuration module. Authentication flows – both JWT-based and social login – fit naturally into Nest’s Passport integration.

Overall, NestJS is well-suited for APIs, microservices, real-time apps, and enterprise backends where maintainability and developer experience matter.

Official Docs and Community Links

NestJS Official Documentation: Comprehensive guide and API reference for all core features.
- https://docs.nestjs.com
GitHub Repository: Source code, issue tracker, and community contributions.
- https://github.com/nestjs/nest

How to Create an npm Library

German Cocca — Fri, 07 Feb 2025 15:33:19 +0000

In the world of JavaScript development, npm (Node Package Manager) has become an essential tool for managing dependencies and sharing reusable code. Whether you're building a simple website or a complex web application, npm libraries help streamline development by providing pre-built solutions to common problems.

Another popular package manager is Yarn, which offers faster and more reliable dependency management while maintaining compatibility with the npm ecosystem.

In this article, we'll explore what npm libraries are, their benefits, and how they enhance the JavaScript and React ecosystem. We'll also go through a practical step-by-step guide on creating, publishing, and using your own npm library in a React project. We’ll also compare npm and Yarn, showing how you can use either of them effectively in your workflow.

By the end of this tutorial, you'll have a clear understanding of how to package and distribute your own code, making it reusable across multiple projects and even available to the wider developer community.

What is npm?
Why Use npm Libraries?
Introducing Yarn: An Alternative to npm
How to Create Your Own npm Library
How to Publish Your Library to npm
How to Use Your npm Library in a React Project
Best Practices for npm and Yarn Libraries
Conclusion & Next Steps

What is npm?

npm (Node Package Manager) is the default package manager for JavaScript and Node.js. It allows developers to install, share, and manage libraries or dependencies that make building applications easier and more efficient.

npm provides access to a vast ecosystem of open-source packages hosted on the npm registry, making it one of the largest software repositories in the world.

npm comes bundled with Node.js, meaning that once you install Node.js, you automatically have access to npm. You can check if npm is installed by running the following command in your terminal:

npm -v

This command should return the version of npm installed on your system.

How npm Works

npm operates through three key components:

The npm Registry – A public repository that hosts open-source JavaScript packages.
The npm CLI (Command Line Interface) – A tool that allows developers to install, update, and manage packages from the command line.
The package.json File – A metadata file that keeps track of dependencies, scripts, and project configurations.

When you install a package using npm, it pulls the package from the registry and saves it in the node_modules folder within your project.

For example, to install Lodash, a popular utility library, you would run:

npm install lodash

This will:

Download the latest version of lodash from the npm registry
Add it to your node_modules folder
Update the package.json and package-lock.json files to reflect the new dependency

The Role of `package.json`

The package.json file is the heart of any npm project. It serves as a blueprint, containing information about the project, including:

Project metadata (name, version, description)
Dependencies (external packages required for the project)
Scripts (commands to automate tasks like starting a server or running tests)
Versioning information (ensuring compatibility between different versions of dependencies)

A typical package.json file looks like this:

{
  "name": "my-awesome-project",
  "version": "1.0.0",
  "description": "A sample project demonstrating npm usage",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "test": "echo \"No tests specified\" && exit 0"
  },
  "dependencies": {
    "lodash": "^4.17.21"
  },
  "devDependencies": {
    "eslint": "^8.0.0"
  },
  "author": "Your Name",
  "license": "MIT"
}

dependencies – Lists essential packages required for the application to function.
devDependencies – Includes development-only dependencies (for example, testing and linting tools).
scripts – Defines CLI commands for automating tasks.

To install all dependencies listed in package.json, simply run:

npm install

This ensures all required packages are downloaded and ready for use.

Key npm Commands

Here are some essential npm commands you’ll use frequently:

Command	Description
`npm init -y`	Creates a default `package.json` file
`npm install`	Installs a package and adds it to `dependencies`
`npm install --save-dev`	Installs a package and adds it to `devDependencies`
`npm uninstall`	Removes a package from the project
`npm update`	Updates all installed dependencies
`npm outdated`	Checks for outdated dependencies
`npm run`	Runs a script defined in `package.json`

Why Use npm Libraries?

As modern web development grows in complexity, using npm libraries has become essential for building scalable and maintainable applications. Instead of writing everything from scratch, you can leverage pre-built, tested, and optimized libraries to speed up development and ensure reliability.

In this section, we’ll explore the key advantages of using npm libraries and why they are crucial in JavaScript and React development.

Code Reuse and Modularization

One of the biggest benefits of npm libraries is code reuse. Instead of repeatedly writing the same functions or utilities in different projects, developers can:

✅ Use existing open-source packages for common functionalities (for example, date formatting, HTTP requests, UI components).
✅ Create and publish their own reusable libraries to share across multiple projects.

For example, instead of manually implementing a function to format dates, you can install a well-maintained package like date-fns:

npm install date-fns

Then, you can use it in your project:

import { format } from "date-fns";

const formattedDate = format(new Date(), "yyyy-MM-dd");
console.log(formattedDate); // Outputs: 2024-02-04 (or the current date)

This modular approach saves time and ensures consistency across projects.

Simplified Dependency Management

npm makes it easy to manage dependencies in a project. Instead of manually downloading and maintaining different versions of external libraries, npm automates this process through the package.json and package-lock.json files.

Some key features include:

🔹 Automatic installation – Run npm install, and all dependencies are set up.
🔹 Version control – Specify package versions to avoid breaking changes.
🔹 Peer dependencies – Ensure compatibility between different libraries.

For example, here’s how npm helps manage dependency versions in package.json:

"dependencies": {
  "react": "^18.0.0",
  "axios": "^1.5.0"
}

^18.0.0 – Allows minor updates but prevents major breaking changes.
axios – Ensures HTTP requests are handled consistently across different projects.

To update all dependencies safely, run:

npm update

This ensures your project is always running on the latest stable versions.

Community-Driven Ecosystem

npm has an active and growing community, meaning developers around the world contribute and maintain thousands of useful libraries. This results in:

🌎 Faster development – No need to reinvent the wheel.
🛠️ Well-tested solutions – Many libraries are battle-tested in production environments.
📚 Rich documentation – Most npm packages come with clear usage instructions and examples.

Popular npm libraries include:

Library	Purpose
React (`react`)	UI library for building web applications
Axios (`axios`)	HTTP client for making API requests
Lodash (`lodash`)	Utility functions for working with arrays, objects, and strings
Express (`express`)	Web framework for building backend services
Jest (`jest`)	JavaScript testing framework

For example, using Axios to make an API request:

import axios from "axios";

axios.get("https://jsonplaceholder.typicode.com/posts/1")
  .then(response => console.log(response.data))
  .catch(error => console.error(error));

This replaces the need for writing complex fetch requests with error handling manually.

Introducing Yarn: An Alternative to npm

While npm is the default package manager for Node.js, another powerful alternative exists: Yarn. Developed by Facebook in 2016, Yarn was created to improve speed, security, and reliability in dependency management.

In this section, we’ll explore what Yarn is, how it differs from npm, and when you might prefer using Yarn over npm.

What is Yarn?

Yarn (Yet Another Resource Negotiator) is a package manager that works similarly to npm but with a focus on performance, security, and consistency. It offers:

🚀 Faster dependency installation thanks to parallel downloads
🔐 More secure package management using checksum verification
📦 Reliable dependency resolution with an offline cache

To check if you have Yarn installed, run:

yarn -v

If you don’t have it yet, you can install it globally using npm:

npm install --global yarn

Once installed, you can use it just like npm to manage dependencies.

Differences Between npm and Yarn

Although npm and Yarn serve the same purpose, they have some key differences:

Feature	npm	Yarn
Speed	Installs packages one at a time	Installs multiple packages in parallel (faster)
Lock File	`package-lock.json`	`yarn.lock`
Offline Cache	Not available (by default)	Can install packages from local cache
Security	Verifies package integrity but lacks checksum enforcement	Uses checksum verification for security
Monorepo Support	Supports workspaces but not optimized	Built-in support for monorepos with `workspaces`

Performance Comparison

When installing dependencies, Yarn is often faster because it downloads packages in parallel, while npm installs them sequentially.

For example, to install all dependencies in a project:

# With npm
npm install

# With Yarn
yarn install

Yarn can also install packages from a local cache, meaning it doesn't always need to fetch dependencies from the internet.

Common Yarn Commands vs. npm

Many npm commands have an equivalent in Yarn:

Action	npm Command	Yarn Command
Initialize a new project	`npm init`	`yarn init`
Install all dependencies	`npm install`	`yarn install`
Install a package	`npm install package-name`	`yarn add package-name`
Install a dev dependency	`npm install package-name --save-dev`	`yarn add package-name --dev`
Remove a package	`npm uninstall package-name`	`yarn remove package-name`
Update all packages	`npm update`	`yarn upgrade`
Run a script	`npm run script-name`	`yarn script-name`

For example, installing axios using Yarn:

yarn add axios

When to Use Yarn Instead of npm

Yarn is a great choice when:

You want faster installations – Yarn installs multiple packages in parallel, making it faster than npm.
You need better dependency consistency – The yarn.lock file ensures that all developers use the same dependency versions.
You're working with monorepos – Yarn’s built-in workspaces make it easier to manage multiple projects within the same repository.
You want improved security – Yarn’s checksum verification prevents corrupted packages from being installed.

Still, npm has improved significantly in recent years, especially with npm v7+, making it a viable choice for most projects.

Switching Between npm and Yarn

If your project was originally set up using npm but you want to switch to Yarn, you can:

1️⃣ Delete node_modules and package-lock.json

rm -rf node_modules package-lock.json

2️⃣ Run Yarn to install dependencies

yarn install

This will generate a yarn.lock file, ensuring all dependencies are managed by Yarn moving forward.

Both npm and Yarn are powerful tools for package management. Choosing between them depends on your project’s needs:

✔️ Use npm if you want the default, widely used package manager that works well with most projects.
✔️ Use Yarn if you need faster installs, better security, and monorepo support.

Ultimately, both tools allow you to install, manage, and publish JavaScript packages efficiently.

How to Create Your Own npm Library

Creating your own npm library is a great way to share reusable code, contribute to the open-source community, or even streamline development across multiple projects. In this section, we’ll walk through the step-by-step process of setting up, coding, and preparing a library for publishing on npm.

Setting Up a New Package

Before writing code, you need to set up an npm package. Follow these steps:

Step 1: Create a New Project Folder

mkdir my-awesome-library
cd my-awesome-library

Step 2: Initialize npm

Run the following command to create a package.json file:

npm init

You will be prompted to enter details such as:

Package name
Version
Description
Entry point (default: index.js)
Author
License

💡 To skip the prompts and create a default package.json, use:

npm init -y

Writing Modular and Reusable Code

Now, let’s create a simple utility library that provides a function to format dates.

Step 3: Create an `index.js` File

Inside the project folder, create a file named index.js and add the following code:

function formatDate(date) {
  if (!(date instanceof Date)) {
    throw new Error("Invalid date");
  }
  return date.toISOString().split("T")[0];
}

module.exports = { formatDate };

Adding Dependencies and Peer Dependencies

Your library might depend on external packages. For example, let’s use date-fns for better date formatting.

To install it as a dependency, run:

npm install date-fns

Then, modify index.js to use date-fns:

const { format } = require("date-fns");

function formatDate(date) {
  if (!(date instanceof Date)) {
    throw new Error("Invalid date");
  }
  return format(date, "yyyy-MM-dd");
}

module.exports = { formatDate };

If you're creating a React-specific library, you should add React as a peer dependency:

npm install react --save-peer

This ensures users of your library install React separately, preventing version conflicts.

Before publishing, you should test how your package works when installed as a dependency.

Step 4: Link the Package Locally

Run the following command in your package folder:

npm link

Then, in another project where you want to use your package, navigate to that project and run:

npm link my-awesome-library

Now, you can import and use your function:

const { formatDate } = require("my-awesome-library");

console.log(formatDate(new Date())); // Output: 2025-02-04 (or the current date)

Once you're happy with your package, it's time to publish it on npm.

How to Publish Your Library to npm

Now that we’ve created our npm package, the next step is publishing it to the npm registry so others can install and use it. In this section, we’ll cover how to publish the package step by step.

Creating an npm Account

Before publishing, you need an npm account.

Go to https://www.npmjs.com/signup and create an account.
Verify your email address.

Step 2: Log in to npm from the Terminal

Run the following command in your terminal:

npm login

You will be prompted to enter:

Your npm username
Your password
Your email (associated with your npm account)

If the login is successful, you’ll see a message:

Logged in as your-username on https://registry.npmjs.org/

Configuring package.json for Publishing

Step 3: Ensure Your Package Name is Unique

Every npm package needs a unique name. Run the following command to check if your desired name is available:

npm search my-awesome-library

If the name is already taken, you’ll need to modify package.json and change the "name" field.

Step 4: Add Metadata and Keywords

Open package.json and ensure it includes useful metadata:

{
  "name": "my-awesome-library",
  "version": "1.0.0",
  "description": "A simple npm package for formatting dates",
  "main": "index.js",
  "repository": {
    "type": "git",
    "url": "https://github.com/yourusername/my-awesome-library.git"
  },
  "keywords": ["date", "formatter", "utility", "npm package"],
  "author": "Your Name ",
  "license": "MIT"
}

🔹 repository – Useful if you plan to host the project on GitHub.
🔹 keywords – Helps people discover your package on npm.
🔹 license – Specifies how others can use your package (for example, MIT, GPL, and so on).

Publishing the Package

Step 5: Publish Your Package to npm

Run the following command inside your project folder:

npm publish

If successful, you’ll see output similar to:

+ my-awesome-library@1.0.0

Your package is now available at:

📌 https://www.npmjs.com/package/my-awesome-library

Step 6: Making Changes and Updating the Package

If you want to release a new version, update the version field in package.json. npm follows Semantic Versioning (SemVer):

Patch: Bug fixes (1.0.0 → 1.0.1)
Minor: New features, backward-compatible (1.0.0 → 1.1.0)
Major: Breaking changes (1.0.0 → 2.0.0)

Instead of manually updating package.json, use:

npm version patch   # 1.0.0 → 1.0.1
npm version minor   # 1.0.0 → 1.1.0
npm version major   # 1.0.0 → 2.0.0

Then, publish the new version:

npm publish

If you accidentally publish a package and need to remove it:

npm unpublish my-awesome-library --force

⚠️ Note: You can only unpublish packages within 72 hours of publishing.

🎯 You’ve successfully published your own npm library! Now, other developers can install it using:

npm install my-awesome-library

By following Semantic Versioning, writing clear documentation, and maintaining your package, you contribute to the open-source ecosystem and make your code reusable.

How to Use Your npm Library in a React Project

Now that we’ve published our npm package, let’s see how to install, import, and use it inside a React project created with Vite. This section will guide you through the process using both npm and Yarn.

Installing Your Package

Step 1: Create a New React Project with Vite (if needed)

If you don’t have an existing React project, create one using Vite:

Using npm

npm create vite@latest my-react-app --template react
cd my-react-app
npm install

Using Yarn

yarn create vite@latest my-react-app --template react
cd my-react-app
yarn install

Once the installation is complete, you can start the development server:

npm run dev

yarn dev

Step 2: Install Your npm Package

Now, install the npm library we created earlier (my-awesome-library).

Using npm

npm install my-awesome-library

Using Yarn

yarn add my-awesome-library

Importing and Using the Library in a React Component

Once installed, you can use the library inside a React component.

Open src/App.jsx and modify it as follows:

import React from "react";
import { formatDate } from "my-awesome-library";

function App() {
  const today = new Date();
  return (
    <div>
      <h1>Formatted Dateh1>
      <p>{formatDate(today)}p>
    div>
  );
}

export default App;

Now, run your Vite React app:

npm run dev

Or with Yarn:

yarn dev

This will display a formatted date on the webpage, confirming that our library is working!

Handling Package Updates and Versioning

To update your npm package in your project:

Using npm

npm update my-awesome-library

Using Yarn

yarn upgrade my-awesome-library

If you want to check outdated dependencies:

npm outdated

yarn outdated

Using a Local Version of Your Package in Development

If you’re still making changes to your npm package and want to test it in your React project before publishing, you can use npm link or yarn link.

Step 1: Link Your Package Locally

Go to your package’s project folder:

cd ~/path-to-my-awesome-library
npm link

yarn link

Step 2: Use It in Your React Project

Navigate to your React app and link the package:

cd ~/path-to-my-react-app
npm link my-awesome-library

yarn link my-awesome-library

Now, when you import and use my-awesome-library, it will use the local version instead of the published one.

Publishing an Update to Your Package

If you’ve made changes to your package and want to publish a new version:

1️⃣ Update the version number in package.json (use npm version patch for small updates).
2️⃣ Run npm publish to upload the new version.
3️⃣ Run npm update my-awesome-library in your React project to get the latest version.

Final Thoughts on Using npm Libraries in React (Vite Edition)

By now, you should have a fully functional npm package and know how to install, use, and update it in a React project using Vite.

✔️ Vite is faster than Create React App and provides better performance for development.
✔️ npm and Yarn make dependency management easy.
✔️ npm link allows local testing before publishing.
✔️ Keeping dependencies updated ensures stability.

This workflow is essential for developers looking to create, maintain, and distribute reusable React components or JavaScript utilities.

Best Practices for npm and Yarn Libraries

Now that you've created, published, and used your own npm package, it's essential to follow best practices to ensure your package is reliable, maintainable, and easy to use. This section will cover key principles and techniques to make your npm library as professional as possible.

Write Meaningful Documentation

A well-documented library helps other developers understand how to use it effectively.

What to Include in Your Documentation

📌 Installation instructions
📌 Usage examples
📌 API reference (functions, parameters, return values)
📌 Versioning and update history
📌 Contributions guide (if open-source)

For example, a simple README.md file for my-awesome-library:

# my-awesome-library

A simple npm package for formatting dates.

## Installation

### Using npm
```sh
npm install my-awesome-library

Using Yarn

yarn add my-awesome-library

Usage

import { formatDate } from "my-awesome-library";

console.log(formatDate(new Date())); // Outputs: 2025-02-04

Follow Semantic Versioning (SemVer)

Versioning helps maintain compatibility and informs users of changes. npm follows Semantic Versioning (SemVer):

MAJOR.MINOR.PATCH

Change Type	Example	Meaning
Patch	`1.0.0 → 1.0.1`	Bug fixes, no breaking changes
Minor	`1.0.0 → 1.1.0`	New features, no breaking changes
Major	`1.0.0 → 2.0.0`	Breaking changes

💡 To bump versions automatically, use:

```sh
npm version patch   # Small bug fix
npm version minor   # New feature added
npm version major   # Breaking changes

Then, publish the new version:

npm publish

👉 Use proper versioning to prevent breaking projects that depend on your library.

Keep Dependencies Up to Date

Regularly updating dependencies improves security, performance, and compatibility.

Check for outdated dependencies:

npm outdated

yarn outdated

Update dependencies:

npm update

yarn upgrade

Write Unit Tests for Your Library

Testing ensures your package works correctly before publishing updates.

Install a Testing Framework (Jest)

npm install --save-dev jest

Create a Test File (`index.test.js`)

const { formatDate } = require("./index");

test("formats a date correctly", () => {
  expect(formatDate(new Date("2025-02-04"))).toBe("2025-02-04");
});

test("throws an error if input is not a date", () => {
  expect(() => formatDate("not a date")).toThrow("Invalid date");
});

Run Tests

shCopyEditnpm test

👉 You can use CI/CD (for example, GitHub Actions) to run tests automatically on every push.

Using CI/CD for Automated Publishing

Automate Publishing with GitHub Actions

Create a .github/workflows/publish.yml file:

ymlCopyEditname: Publish to npm
on:
  push:
    branches:
      - main

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
          registry-url: "https://registry.npmjs.org/"
      - run: npm install
      - run: npm test
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

1️⃣ Create an npm token:
Run:

shCopyEditnpm token create

Copy the token and add it to GitHub Secrets (NPM_TOKEN).

2️⃣ Push code to GitHub → Auto-publish on npm!

👉 Automating publishing prevents human errors and ensures quality control.

Ensure Cross-Platform Compatibility

Use ES modules (import/export) for modern compatibility.
Include CommonJS (require/module.exports) support for older environments.
Test with different Node.js versions using CI/CD.

Example package.json for dual compatibility:

jsonCopyEdit"type": "module",
"main": "index.cjs",
"exports": {
  "import": "./index.mjs",
  "require": "./index.cjs"
}

👉 This ensures your package works everywhere (Node.js, React, Next.js, and so on).

Conclusion

Congratulations! 🎉 You’ve successfully learned how to create, publish, and use your own npm package, while also understanding the benefits of both npm and Yarn for package management.

Throughout this guide, we covered:

✔️ What npm is and why it’s important
✔️ How to use npm and Yarn to manage dependencies
✔️ How to create a reusable npm package
✔️ How to publish and update your package on npm
✔️ How to integrate your package into a React project with Vite
✔️ Best practices for writing, testing, and maintaining your library

By following these steps, you've taken an important step toward open-source development and modular programming, making your code reusable for both yourself and the developer community.

How to Learn Python for JavaScript Developers [Full Handbook]

German Cocca — Fri, 22 Nov 2024 14:54:46 +0000

As a developer with experience in JavaScript, you likely know how versatile the language is, especially when it comes to web development. JavaScript powers both frontend and backend development (thanks to Node.js) and has grown to become one of the most widely used programming languages.

But while JavaScript is powerful, there are other languages that shine in specific areas where JavaScript may not be the most efficient choice. One of those languages is Python.

This handbook aims to introduce Python to experienced JavaScript developers, not merely as an alternative but as a complementary tool that can broaden your development capabilities.

Python is renowned for its simplicity, readability, and extensive libraries, which make it particularly useful in domains like data science, machine learning, automation, and backend development. By understanding Python’s core features and how they compare to JavaScript, you can leverage the strengths of both languages, choosing the right tool for each task.

Brief Overview of JavaScript and Python
Language Paradigms and Use Cases
Syntax and Language Features
Data Structures and Collections
Functions and Scope
Object-Oriented Programming (OOP)
Asynchronous Programming
Modules, Packages, and Dependency Management
Error Handling and Debugging
Testing and Frameworks
Practical Applications and Examples
Community, Libraries, and Ecosystem
Conclusion

1. Brief Overview of JavaScript and Python

Before diving into the details, let’s take a high-level look at the origins and purposes of both languages.

JavaScript was initially created as a scripting language for web browsers, designed to make web pages interactive. Over the years, JavaScript has evolved significantly and is now used on the server side (thanks to Node.js) and in a variety of application environments beyond the browser.

JavaScript is event-driven, and it’s often praised for its versatility and asynchronous capabilities, which are essential for building modern, responsive web applications.

Python, on the other hand, was developed with a focus on simplicity and readability. Created in the late 1980s and gaining popularity in the early 2000s, Python is known for its clear and concise syntax that emphasizes readability. It is widely used in scientific research, data analysis, machine learning, and web development.

Python’s extensive standard library and vibrant ecosystem of third-party libraries make it highly productive for developers working in various fields, from scripting to full-scale application development.

While both languages are high-level and dynamically typed, they cater to different paradigms and have distinct strengths. For example, Python is often seen as more beginner-friendly due to its readable syntax, while JavaScript is more commonly encountered in the web development ecosystem.

Why JavaScript Developers Should Learn Python

As a JavaScript developer, learning Python can significantly enhance your versatility and open up new opportunities. Here are some reasons why learning Python might be a worthwhile addition to your skill set:

Expanded Career Opportunities
While JavaScript jobs are abundant, Python’s rise in popularity has created many roles in fields like data science, artificial intelligence, machine learning, and DevOps. By adding Python to your skillset, you can tap into these growing job markets.
Enhanced Development Speed and Readability
Python’s syntax is famously concise and readable. Python code often resembles pseudocode, which makes it not only faster to write but also easier to understand and maintain. This can be a significant advantage when building prototypes or handling complex algorithms, as you’ll see more of your time spent on problem-solving rather than syntax management.
Versatile Applications
While JavaScript dominates web development, Python is widely used in fields like automation, web scraping, and scientific computing. For example, if you’re looking to automate repetitive tasks, Python provides a straightforward approach with powerful libraries like os, shutil, and sys for system operations. In web scraping, libraries like BeautifulSoup and Scrapy make data extraction a breeze.
Rich Ecosystem for Data Science and Machine Learning
If you’re interested in working with data, machine learning, or AI, Python is the language to know. Python’s ecosystem for data science includes libraries such as Pandas, NumPy, and Matplotlib, which enable sophisticated data manipulation and visualization with relatively little code. Machine learning frameworks like TensorFlow, Keras, and PyTorch also have deep Python integration, making Python a top choice for data-intensive applications.
Better Interoperability in Multilingual Projects
Many large projects utilize multiple languages, selecting the best language for each part of the system. JavaScript and Python can work well together, with Python handling backend processes, data analysis, or automation, while JavaScript powers the user interface. Understanding both languages allows you to contribute across the stack and enhances your ability to collaborate on diverse codebases.
Increasing Role in Web Development
Though JavaScript is still the primary language for frontend development, Python is becoming more prominent in backend web development through frameworks like Django and Flask. These frameworks make it easy to build scalable and secure web applications, and Python’s ease of use can lead to faster development cycles.

By learning Python, JavaScript developers can enjoy a more complete toolkit that covers everything from frontend to backend development, data science, and beyond. As you progress through this article, we’ll explore how Python’s features and syntax compare to JavaScript, providing you with a strong foundation to get started with Python.

2. Language Paradigms and Use Cases

JavaScript vs. Python: Scripting, Backend, and Full-Stack

Both JavaScript and Python are high-level, interpreted languages, but they were initially created with distinct purposes in mind. Over the years, they have evolved to expand their applications, making them popular choices for both general-purpose and specialized development tasks.

Understanding these differences in paradigms and common use cases helps clarify when to use each language and the kind of projects they are best suited for.

JavaScript

Known primarily as the language of the web, JavaScript was originally designed to add interactivity to HTML documents within browsers. Today, with the advent of frameworks like React, Angular, and Vue, JavaScript is at the core of modern, interactive frontend web development.

The language’s reach expanded even further with Node.js, which brought JavaScript to the server side. Now, JavaScript is a full-stack language that powers single-page applications (SPAs), RESTful APIs, and server-side rendering.

JavaScript is event-driven and asynchronous by design, making it ideal for real-time applications such as chat apps, collaborative tools, and streaming services.

Python

Initially created with a focus on readability and simplicity, Python has become one of the most versatile languages in the world. While JavaScript is often tied to web applications, Python is more commonly used in fields like scientific computing, data analysis, machine learning, and artificial intelligence. Its readability and simplicity make it a great choice for scripting, automation, and rapid prototyping.

Also, Python’s rich ecosystem of libraries and frameworks, such as Django and Flask, allow it to be used for backend web development.

Unlike JavaScript, Python is synchronous by default, which makes it better suited for tasks that don’t require real-time interaction but benefit from efficiency, such as data processing and batch operations.

Core Differences in Approach: Dynamic Typing, Functional Programming, and OOP

Both JavaScript and Python are dynamically typed, meaning that variables do not need to be declared with a specific type and can hold different types of data at runtime. But the two languages implement this dynamic typing in slightly different ways, and they each approach functional programming and object-oriented programming (OOP) differently.

Dynamic Typing: Both languages allow flexibility in declaring variables without specifying types, making them highly flexible. But Python’s strict indentation requirements and clear error messages provide a more structured approach to dynamic typing.

JavaScript, on the other hand, has a looser syntax, which sometimes leads to quirks, such as type coercion, that can result in unexpected behavior (for example, 0 == '' evaluates to true).

Functional Programming: Both languages support functional programming techniques, but JavaScript leans heavily on it. Functions are first-class citizens in JavaScript, allowing developers to pass functions as arguments, return them from other functions, and store them in variables. Higher-order functions, such as map, reduce, and filter, are commonly used in JavaScript to process arrays and data collections.

Python also supports functional programming, and it includes a lambda feature for anonymous functions as well as map, filter, and reduce functions. But functional programming is less central in Python, which encourages readability and simplicity over deeply functional constructs.

Object-Oriented Programming (OOP): JavaScript’s OOP model is prototype-based, meaning that objects can inherit directly from other objects without the need for classes. Since ES6, JavaScript has also included support for class syntax, making it easier for developers coming from class-based languages to work with objects.

Python, on the other hand, uses a class-based model that is more in line with traditional OOP languages like Java and C++. Classes, inheritance, and polymorphism in Python are straightforward, making it an excellent choice for developers who prefer a clear and well-structured approach to OOP.

Typical Use Cases for JavaScript and Python

To understand the strengths of each language, it’s helpful to consider the types of projects that developers commonly use JavaScript and Python for:

Common Use Cases for JavaScript:

Frontend Web Development: JavaScript is essential for building interactive user interfaces in web browsers. With libraries and frameworks like React, Vue, and Angular, developers can build rich, responsive applications that run entirely in the browser.
Full-Stack Web Development: Node.js allows JavaScript to be used on the backend, enabling full-stack development with JavaScript across the entire application. Express, NestJS, and other frameworks provide the tools for creating RESTful APIs, real-time applications, and server-side rendering.
Real-Time Applications: JavaScript’s asynchronous and non-blocking nature makes it ideal for applications that require real-time updates, such as chat applications, live streaming, and collaborative tools.
Mobile App Development: With frameworks like React Native, JavaScript can also be used to build cross-platform mobile applications. This allows JavaScript developers to leverage their web development skills to create mobile apps that work on both iOS and Android devices.

Common Use Cases for Python:

Data Science and Analysis: Python’s popularity in data science is unparalleled, with libraries like Pandas, NumPy, and Matplotlib providing robust tools for data manipulation, analysis, and visualization. Python is the go-to language for data scientists and analysts.
Machine Learning and Artificial Intelligence: Python’s machine learning libraries, such as TensorFlow, Keras, and PyTorch, make it an ideal language for building machine learning models and neural networks. Python’s readability is especially useful when experimenting with complex algorithms.
Automation and Scripting: Python’s simplicity and versatility make it a popular choice for automation. Tasks like file manipulation, batch processing, and web scraping can be accomplished with Python scripts, using libraries like BeautifulSoup, Selenium, and Requests.
Backend Web Development: Python’s web frameworks, such as Django and Flask, provide powerful tools for creating scalable and secure web applications. Python is widely used for backend development, particularly in projects that require quick prototyping, as its concise syntax speeds up development.
Scientific Computing and Research: Python is commonly used in scientific research due to its extensive scientific libraries, such as SciPy and SymPy, and its compatibility with environments like Jupyter notebooks.

By understanding the typical use cases and paradigms that each language supports, JavaScript developers can better appreciate Python’s unique strengths.

JavaScript is inherently event-driven, making it ideal for interactive applications, while Python’s strengths lie in readability and a well-defined structure, making it an excellent choice for projects that demand clarity and precision, like data science, scripting, and backend development.

3. Syntax and Language Features

While both JavaScript and Python are dynamically typed, high-level languages, they have distinct syntax rules and language features that can affect code readability, structure, and maintenance.

This section highlights some of the core syntactical differences and introduces language features that will be especially relevant for a JavaScript developer learning Python.

Comparison of Syntax Simplicity and Readability

One of Python’s main selling points is its clear, readable syntax. Often described as “executable pseudocode,” Python emphasizes simplicity, aiming for code that’s easy to write and, perhaps more importantly, easy to read.

Unlike JavaScript, which uses braces ({}) to define code blocks, Python uses indentation to enforce structure, which naturally encourages clean, organized code.

Example: Hello World and Simple Loops

In both languages, the "Hello, World!" example highlights the difference in syntax:

Python:

print("Hello, World!")

JavaScript:

console.log("Hello, World!");

Python’s built-in print function makes printing straightforward without additional syntax. In JavaScript, console.log performs the same task but requires a more explicit object-method format.

Now, consider a simple loop that prints numbers from 0 to 4:

Python:

for i in range(5):
    print(i)

JavaScript:

for (let i = 0; i < 5; i++) {
    console.log(i);
}

The difference here is striking. Python’s for loop with range() is compact and highly readable, while JavaScript’s loop uses a more complex syntax with initialization, condition, and increment clauses. This is a minor but illustrative example of Python’s design philosophy: code should be intuitive and easy to follow.

Data Types and Variable Declaration

Both JavaScript and Python are dynamically typed, meaning that you don’t need to specify variable types explicitly. But there are differences in variable declaration and type handling that are worth noting.

Variable Declaration

JavaScript requires let, const, or var to declare variables. The use of let and const in modern JavaScript helps manage scope and constancy of variables, with const enforcing immutability.

In Python, there is no need to specify let, const, or var – you simply assign a value to a variable, and Python infers the type based on the value.

JavaScript:

let age = 25;  // Using 'let' for a block-scoped variable
const name = "Alice";  // Using 'const' for an immutable variable

Python:

age = 25  # Python infers type automatically
name = "Alice"  # No need to declare as const or let

Type Checking and Conversion

Python’s type-checking system is more consistent, while JavaScript sometimes has quirky behavior due to type coercion, where values of different types are implicitly converted for comparison. For example:

JavaScript:

console.log(0 == "");  // true due to type coercion
console.log(0 === ""); // false due to strict equality

Python:

print(0 == "")  # Raises a TypeError: 'int' and 'str' cannot be compared

Python does not allow implicit type coercion, reducing potential bugs related to unexpected type behavior. If type conversion is needed, Python requires explicit casting.

Working with Primitive Data Types

JavaScript and Python share some primitive types but also have unique types and handling:

Numbers: Both JavaScript and Python have number types, but Python distinguishes between int and float for integers and decimal numbers. JavaScript has only a single Number type for all numeric values (including NaN for “not-a-number”).
Strings: Both languages treat strings as sequences of characters, allowing methods like concatenation, splitting, and indexing. In Python, strings are immutable, meaning once created, they cannot be modified directly.
Booleans: Both languages have true and false values. But JavaScript’s type coercion can lead to unexpected results in conditions, which Python avoids with explicit boolean handling.
Null and Undefined: JavaScript distinguishes between null (an intentional absence of value) and undefined (an uninitialized variable). Python uses None as a single, consistent representation of “no value.”

Data Collections: Lists, Tuples, Sets, and Dictionaries

Both JavaScript and Python offer various data structures to handle collections, but Python has built-in types that allow for more specific data handling.

Lists and Arrays

Python’s list type is analogous to JavaScript’s array, but it’s more versatile, as Python lists can store elements of different types and support built-in functions for manipulation. In contrast, JavaScript arrays are specialized objects with numerical indices.

Python:

my_list = [1, "apple", 3.14]

JavaScript:

let myArray = [1, "apple", 3.14];

Tuples

Python offers tuple as an immutable version of a list, useful when data should not be modified. JavaScript has no direct equivalent, though const can create a similar effect by enforcing immutability.

Python:

my_tuple = (1, "apple", 3.14)

Sets

Both languages offer a set data type for collections of unique elements. Python has set, while JavaScript uses Set.

Python:

my_set = {1, 2, 3}

JavaScript:

let mySet = new Set([1, 2, 3]);

Dictionaries and Objects

Python’s dict and JavaScript’s objects are both key-value structures, but they differ in design and functionality.

In Python, dictionaries are optimized for hashable keys, whereas JavaScript objects are more flexible but can lead to type-related issues when keys are non-string values.

Python:

my_dict = {"name": "Alice", "age": 25}

JavaScript:

let myObject = { name: "Alice", age: 25 };

Control Structures: Conditionals and Loops

Both Python and JavaScript have similar control structures, such as if, for, and while loops. But Python's syntax is simplified due to its reliance on indentation.

Conditionals

Python:

if age > 18:
    print("Adult")
else:
    print("Minor")

JavaScript:

if (age > 18) {
    console.log("Adult");
} else {
    console.log("Minor");
}

Python’s syntax avoids the braces used in JavaScript, relying on indentation to signify code blocks. This makes code look cleaner but enforces strict formatting, which can be a learning curve for JavaScript developers.

Loops

For Loops: Python’s for loop is often simpler, especially with the range() function. JavaScript’s traditional for loop has more structure but allows for flexibility.

Python:

for i in range(5):
    print(i)

JavaScript:

for (let i = 0; i < 5; i++) {
    console.log(i);
}

While Loops: Both languages support while loops, and they’re functionally similar. But Python uses plain English for keywords and syntax, which some find more readable.

Python:

count = 0
while count < 5:
    print(count)
    count += 1

JavaScript:

let count = 0;
while (count < 5) {
    console.log(count);
    count++;
}

Key Takeaways:

Python’s syntax is minimalist and requires indentation, which encourages clean, readable code.
Variable declaration in Python is simpler due to inferred types, while JavaScript uses let, const, and var for scope management.
Python has built-in data structures like lists, tuples, sets, and dictionaries, each with specific use cases, while JavaScript relies on arrays and objects.
Control structures in Python focus on readability with fewer symbols, whereas JavaScript uses braces and parentheses to define blocks.

4. Data Structures and Collections

Data structures are foundational to any programming language, as they define how data is stored, accessed, and manipulated. Both JavaScript and Python offer a variety of built-in data structures, but each language provides different tools and features for handling collections.

In this section, we’ll explore Python’s main data structures and compare them with JavaScript’s corresponding structures.

Lists and Arrays

In Python, lists are versatile, mutable sequences that allow you to store elements of different types. They are comparable to JavaScript’s arrays but come with built-in methods and utilities that make them easier to manipulate for many use cases.

Python Lists:

Lists in Python are denoted by square brackets ([]) and support various built-in functions, such as appending, inserting, and removing elements.
They can store any type of data, including other lists, making them useful for nested data structures.

JavaScript Arrays:

Arrays in JavaScript are also denoted by square brackets ([]) and can hold elements of different types.
JavaScript arrays are technically objects, so they come with a range of methods for manipulation (push, pop, splice, map, etc.).

Example: Adding and removing elements in lists and arrays:

Python:

# Creating and manipulating a list
my_list = [1, 2, 3]
my_list.append(4)       # Adds 4 to the end
my_list.insert(1, 10)   # Inserts 10 at index 1
my_list.remove(2)       # Removes the first occurrence of 2
print(my_list)          # Output: [1, 10, 3, 4]

JavaScript:

// Creating and manipulating an array
let myArray = [1, 2, 3];
myArray.push(4);        // Adds 4 to the end
myArray.splice(1, 0, 10); // Inserts 10 at index 1
myArray.splice(myArray.indexOf(2), 1); // Removes the first occurrence of 2
console.log(myArray);   // Output: [1, 10, 3, 4]

Python’s list functions are often simpler and more intuitive, which is particularly beneficial for quick data manipulation.

Tuples

Python offers tuples as an immutable sequence type, meaning their elements cannot be changed once created. Tuples are useful when you need a sequence of items that should remain constant throughout the program’s execution.

JavaScript does not have an equivalent immutable sequence structure, though arrays declared with const can serve a similar purpose in restricting reassignment.

Python Tuple:

my_tuple = (1, 2, 3)
# Attempting to modify will raise an error:
# my_tuple[0] = 10  # Raises TypeError

Tuples are ideal for fixed collections, such as coordinates or configuration values, where data should not change.

Sets

Both JavaScript and Python offer sets as a way to store unique values. Sets are unordered and do not allow duplicates, making them ideal for collections where each item should be unique.

Python Sets:

In Python, sets are defined using curly braces ({}) or the set() function.
Python sets support set operations like union, intersection, and difference, which can be useful for tasks like finding common elements or removing duplicates.

JavaScript Sets:

JavaScript introduced the Set object in ES6.
Similar to Python, JavaScript sets can perform union and intersection operations with some extra syntax.

Example: Working with sets in Python and JavaScript:

Python:

# Creating and using a set
fruits = {"apple", "banana", "cherry"}
fruits.add("orange")           # Adds "orange" to the set
fruits.discard("banana")       # Removes "banana" from the set
print(fruits)                  # Output: {"apple", "cherry", "orange"}

JavaScript:

// Creating and using a set
let fruits = new Set(["apple", "banana", "cherry"]);
fruits.add("orange");           // Adds "orange" to the set
fruits.delete("banana");        // Removes "banana" from the set
console.log(fruits);            // Output: Set { "apple", "cherry", "orange" }

Python’s set functions (union, intersection, difference) make it easy to perform mathematical set operations directly, which is especially useful for data processing tasks.

Dictionaries and Objects

Python’s dict and JavaScript’s objects are both key-value pair data structures, but they have slightly different features and limitations.

Python Dictionaries: Python’s dictionaries are optimized for fast lookup and can use immutable types (for example, strings, numbers, tuples) as keys. Dictionaries are widely used in Python for data management, configuration, and lookups.
JavaScript Objects: JavaScript objects serve a similar purpose but are less restrictive in terms of key types. Objects can use strings and symbols as keys but lack some of the dictionary-specific functions found in Python.

Example: Creating and accessing elements in dictionaries and objects:

Python:

# Creating and manipulating a dictionary
person = {"name": "Alice", "age": 30}
person["city"] = "New York"     # Adding a new key-value pair
print(person["name"])           # Output: Alice
del person["age"]               # Removing a key-value pair
print(person)                   # Output: {"name": "Alice", "city": "New York"}

JavaScript:

// Creating and manipulating an object
let person = { name: "Alice", age: 30 };
person.city = "New York";       // Adding a new key-value pair
console.log(person.name);       // Output: Alice
delete person.age;              // Removing a key-value pair
console.log(person);            // Output: { name: "Alice", city: "New York" }

Python dictionaries also support powerful methods like get, keys, values, and items, which provide more direct ways to access and manipulate dictionary contents compared to JavaScript’s object handling.

Working with JSON Data

Both Python and JavaScript work well with JSON, a format frequently used for data interchange in web applications. JavaScript’s native compatibility with JSON is a natural fit for web APIs, while Python’s json module allows for easy parsing and generation of JSON data.

Example: Converting a dictionary/object to JSON and parsing JSON data:

Python:

import json

# Convert dictionary to JSON string
person_dict = {"name": "Alice", "age": 30}
person_json = json.dumps(person_dict)
print(person_json)  # Output: {"name": "Alice", "age": 30}

# Parse JSON string to dictionary
parsed_dict = json.loads(person_json)
print(parsed_dict)  # Output: {'name': 'Alice', 'age': 30}

JavaScript:

// Convert object to JSON string
let personObject = { name: "Alice", age: 30 };
let personJson = JSON.stringify(personObject);
console.log(personJson); // Output: {"name":"Alice","age":30}

// Parse JSON string to object
let parsedObject = JSON.parse(personJson);
console.log(parsedObject); // Output: { name: 'Alice', age: 30 }

Key Takeaways:

Lists and Arrays: Python’s lists are versatile and come with built-in manipulation methods. JavaScript arrays are flexible but less concise in syntax.
Tuples: Python’s tuples are immutable sequences ideal for fixed data collections, which JavaScript lacks an equivalent for.
Sets: Both Python and JavaScript offer sets for unique collections, but Python’s sets support more direct mathematical operations.
Dictionaries and Objects: Python’s dictionaries and JavaScript’s objects serve similar purposes, though Python offers additional methods specifically for dictionary manipulation.
JSON: Both languages handle JSON data, with JavaScript having native JSON support and Python using the json module.

5. Functions and Scope

Functions are the building blocks of any programming language. They allow you to encapsulate code for reuse, organization, and clarity.

Both Python and JavaScript support first-class functions, meaning functions can be assigned to variables, passed as arguments, and returned from other functions. But there are differences in how functions are defined, scoped, and used in each language.

Defining Functions in Python vs. JavaScript

Python Functions:
In Python, functions are defined using the def keyword, followed by the function name, parameters in parentheses, and a colon. Python uses indentation to define the function body, which makes the syntax clean and readable.

JavaScript Functions:
In JavaScript, functions can be defined in several ways: using the function keyword, as an arrow function (=>), or as a method within an object. Modern JavaScript commonly uses arrow functions for their brevity and lexical this behavior.

Example: Basic Function Definition

Python:

def greet(name):
    return f"Hello, {name}!"

print(greet("Alice"))  # Output: Hello, Alice!

JavaScript:

function greet(name) {
    return `Hello, ${name}!`;
}

console.log(greet("Alice")); // Output: Hello, Alice!

Arrow Functions in JavaScript:

const greet = (name) => `Hello, ${name}!`;
console.log(greet("Alice")); // Output: Hello, Alice!

Key Differences:

Python uses explicit keywords like def and return, while JavaScript has multiple ways to define functions, which can sometimes be overwhelming for beginners.
Arrow functions in JavaScript provide concise syntax but are not equivalent to Python’s lambda (more on that below).

Scope Rules: Closures in JavaScript vs. LEGB Rule in Python

Scope refers to where a variable is accessible in your code. Both Python and JavaScript have rules for variable scoping, but they are implemented differently.

Python’s LEGB Rule:
Python uses the LEGB rule to determine variable scope:

Local: Variables defined inside a function.
Enclosing: Variables in the nearest enclosing scope (for example, nested functions).
Global: Variables defined at the top level of the module.
Built-in: Predefined names in Python (for example, len, print).

Example of Python scope:

x = "global"

def outer_function():
    x = "enclosing"

    def inner_function():
        x = "local"
        print(x)

    inner_function()

outer_function()  # Output: local
print(x)          # Output: global

JavaScript Closures:
JavaScript handles scope using function-level and block-level scoping. Variables declared with let and const have block scope, while var has function scope.

Closures are an essential concept in JavaScript, allowing inner functions to access variables from their outer (enclosing) functions even after the outer function has executed.

Example of JavaScript closure:

function outerFunction() {
    let x = "enclosing";

    function innerFunction() {
        let x = "local";
        console.log(x);
    }

    innerFunction();
}

outerFunction(); // Output: local

Key Differences:

Python’s scope is determined by its LEGB rule, whereas JavaScript relies on closures and block scoping (with let and const).
Python has explicit mechanisms like the global and nonlocal keywords to modify variable scope, while JavaScript uses closures implicitly.

Anonymous Functions: Lambda Expressions vs. Arrow Functions

Python’s Lambda Expressions:
Python’s lambda allows you to define small, unnamed functions in a single line. They are typically used for short-lived operations, like filtering or mapping, where defining a full function would be unnecessary.

Example of a Python lambda:

square = lambda x: x ** 2
print(square(5))  # Output: 25

# Using lambda in a map function
numbers = [1, 2, 3, 4]
squared = map(lambda x: x ** 2, numbers)
print(list(squared))  # Output: [1, 4, 9, 16]

JavaScript’s Arrow Functions:
Arrow functions in JavaScript serve a similar purpose but are more versatile. They provide a concise way to define functions and automatically bind this to the enclosing context, which is particularly useful in object-oriented or asynchronous programming.

Example of a JavaScript arrow function:

const square = (x) => x ** 2;
console.log(square(5)); // Output: 25

// Using an arrow function in map
const numbers = [1, 2, 3, 4];
const squared = numbers.map((x) => x ** 2);
console.log(squared); // Output: [1, 4, 9, 16]

Key Differences:

Purpose: Python’s lambda is limited to single expressions and is primarily used for quick operations. Arrow functions in JavaScript are more flexible and can have multiple statements and explicit return values.
Scope Binding: Arrow functions inherit the this context of their enclosing block, while Python’s lambdas are independent functions with no context-related behavior.

Function Parameters and Default Values

Both Python and JavaScript support default parameter values, but Python offers additional features like keyword arguments and variable-length arguments (*args and **kwargs).

Python Default and Variable-Length Arguments:

def greet(name="World", *args, **kwargs):
    print(f"Hello, {name}!")
    print("Arguments:", args)
    print("Keyword Arguments:", kwargs)

greet("Alice", 1, 2, color="blue", age=30)
# Output:
# Hello, Alice!
# Arguments: (1, 2)
# Keyword Arguments: {'color': 'blue', 'age': 30}

JavaScript Default Parameters:

function greet(name = "World", ...args) {
    console.log(`Hello, ${name}!`);
    console.log("Arguments:", args);
}

greet("Alice", 1, 2, { color: "blue", age: 30 });
// Output:
// Hello, Alice!
// Arguments: [1, 2, { color: 'blue', age: 30 }]

Python’s keyword arguments (**kwargs) provide a more structured way to handle optional parameters compared to JavaScript’s arguments or rest parameters.

Key Takeaways:

Python’s function syntax (def) is straightforward and emphasizes readability, while JavaScript offers flexibility with function, arrow functions, and method definitions.
Python’s LEGB scope rule makes variable visibility predictable and explicit, while JavaScript’s closures offer powerful but implicit scoping.
Python’s lambda expressions are limited to simple operations, whereas JavaScript’s arrow functions provide greater flexibility and contextual this binding.
Python’s support for keyword and variable-length arguments adds flexibility and clarity when passing data to functions.

This section demonstrates that while both languages handle functions and scope effectively, Python’s approach prioritizes simplicity and readability, while JavaScript offers more flexibility and dynamic behavior. Both approaches have their advantages, depending on the task at hand.

6. Object-Oriented Programming (OOP)

Object-Oriented Programming (OOP) allows developers to create reusable and modular code by encapsulating data and behavior into objects. Both Python and JavaScript support OOP, but they implement it differently.

Python uses a class-based model, with clearly defined syntax for attributes and methods. JavaScript traditionally relied on prototype-based inheritance but has introduced class syntax (since ES6) that closely resembles traditional OOP languages, providing familiarity for developers transitioning from Python or Java.

Classes, Inheritance, and Polymorphism

At its core, OOP involves defining classes (blueprints for objects), creating instances of those classes, and implementing inheritance to extend or modify behavior. Both Python and JavaScript support these concepts, albeit with different syntax.

Example: Basic Class Definition

Python:

class Animal:
    def __init__(self, name):
        self.name = name

    def speak(self):
        return f"{self.name} makes a sound."

class Dog(Animal):
    def speak(self):
        return f"{self.name} barks."

# Using the classes
generic_animal = Animal("Generic Animal")
dog = Dog("Buddy")

print(generic_animal.speak())  # Output: Generic Animal makes a sound.
print(dog.speak())             # Output: Buddy barks.

JavaScript:

class Animal {
    constructor(name) {
        this.name = name;
    }

    speak() {
        return `${this.name} makes a sound.`;
    }
}

class Dog extends Animal {
    speak() {
        return `${this.name} barks.`;
    }
}

// Using the classes
const genericAnimal = new Animal("Generic Animal");
const dog = new Dog("Buddy");

console.log(genericAnimal.speak()); // Output: Generic Animal makes a sound.
console.log(dog.speak());           // Output: Buddy barks.

In both examples, you see:

Class Definition: class is used in both Python and JavaScript.
Inheritance: The Dog class extends the Animal class, overriding the speak method in both languages.

Differences in Constructors and the `this` vs. `self` Keyword

One key difference in OOP syntax between Python and JavaScript lies in how constructors are defined and how the instance is referenced within a class.

Python Constructor and self:

Python uses __init__ as a special method to initialize an object. It explicitly requires self as the first parameter in all instance methods to refer to the object itself.

Example:

class Person:
    def __init__(self, name, age):
        self.name = name
        self.age = age

    def greet(self):
        return f"My name is {self.name} and I am {self.age} years old."

person = Person("Alice", 30)
print(person.greet())  # Output: My name is Alice and I am 30 years old.

JavaScript Constructor and this:

JavaScript uses a constructor method to initialize an object. Inside methods, this is used to reference the current instance, but this can behave differently depending on the context.

Example:

class Person {
    constructor(name, age) {
        this.name = name;
        this.age = age;
    }

    greet() {
        return `My name is ${this.name} and I am ${this.age} years old.`;
    }
}

const person = new Person("Alice", 30);
console.log(person.greet()); // Output: My name is Alice and I am 30 years old.

Key Differences:

Explicit vs. Implicit Instance Reference: Python always requires self explicitly, while JavaScript implicitly uses this.
Context Sensitivity: In JavaScript, this can lose its binding in certain contexts (for example, when passing methods as callbacks). Arrow functions provide a way to avoid this issue by binding this to the lexical scope.

Polymorphism in Python and JavaScript

Polymorphism allows methods to behave differently depending on the object that calls them. This is a fundamental OOP concept and is supported in both Python and JavaScript.

Python Example:

class Bird:
    def fly(self):
        return "Birds can fly."

class Penguin(Bird):
    def fly(self):
        return "Penguins cannot fly."

def get_flight_ability(bird):
    print(bird.fly())

sparrow = Bird()
penguin = Penguin()

get_flight_ability(sparrow)  # Output: Birds can fly.
get_flight_ability(penguin)  # Output: Penguins cannot fly.

JavaScript Example:

class Bird {
    fly() {
        return "Birds can fly.";
    }
}

class Penguin extends Bird {
    fly() {
        return "Penguins cannot fly.";
    }
}

function getFlightAbility(bird) {
    console.log(bird.fly());
}

const sparrow = new Bird();
const penguin = new Penguin();

getFlightAbility(sparrow);  // Output: Birds can fly.
getFlightAbility(penguin);  // Output: Penguins cannot fly.

Prototypes in JavaScript vs. Classes in Python

JavaScript's OOP was initially based on prototypes, where objects could inherit properties and methods directly from other objects. Although ES6 introduced class, it is syntactic sugar over JavaScript's prototypal inheritance.

JavaScript Prototype Example:

function Calculator() {}

Calculator.prototype.add = function (a, b) {
    return a + b;
};

Calculator.prototype.multiply = function (a, b) {
    return a * b;
};

const calc = new Calculator();
console.log(calc.add(5, 3));       // Output: 8
console.log(calc.multiply(5, 3));  // Output: 15

Modern JavaScript Class Example:

class Calculator {
    add(a, b) {
        return a + b;
    }

    multiply(a, b) {
        return a * b;
    }
}

const calc = new Calculator();
console.log(calc.add(5, 3));       // Output: 8
console.log(calc.multiply(5, 3));  // Output: 15

Python, in contrast, always uses a class-based system for OOP, avoiding the confusion of prototypes.

Python Example:

class Calculator:
    def add(self, a, b):
        return a + b

    def multiply(self, a, b):
        return a * b

calc = Calculator()
print(calc.add(5, 3))       # Output: 8
print(calc.multiply(5, 3))  # Output: 15

Key Takeaways:

Python’s OOP model is straightforward, using class, __init__ for constructors, and self to refer to instance attributes.
JavaScript has both prototypal and class-based OOP. The modern class syntax simplifies prototypal inheritance but can lead to confusion with this.
Both languages support core OOP principles like encapsulation, inheritance, and polymorphism, but Python’s implementation is more explicit and traditional, while JavaScript’s flexibility stems from its prototypal roots.

7. Asynchronous Programming

Asynchronous programming is essential for handling tasks like network requests, file I/O, or any operation that takes time to complete.

Both Python and JavaScript support asynchronous programming, but their implementations differ significantly. JavaScript is inherently asynchronous and event-driven, while Python introduced asynchronous programming more recently with the asyncio library and async/await syntax.

Event Loop and Promises in JavaScript

JavaScript’s asynchronous model is based on the event loop, which processes tasks in a non-blocking manner. This makes it ideal for web applications where responsiveness is key. JavaScript uses callbacks, Promises, and async/await to handle asynchronous tasks.

Example: Fetching Data with Promises

A common asynchronous operation is fetching data from an API.

fetch('https://api.example.com/data')
    .then(response => response.json())
    .then(data => {
        console.log(data);
    })
    .catch(error => {
        console.error('Error:', error);
    });

How it works:

The fetch function returns a Promise.
The .then method is used to handle the resolved Promise, where response.json() parses the JSON data.
The .catch method handles errors, such as network issues.

Example: Using Async/Await

Async/await simplifies the syntax for working with Promises.

async function fetchData() {
    try {
        const response = await fetch('https://api.example.com/data');
        const data = await response.json();
        console.log(data);
    } catch (error) {
        console.error('Error:', error);
    }
}

fetchData();

In this example, await pauses the execution of the fetchData function until the Promise is resolved or rejected, providing a more synchronous-like flow.

Asyncio and Await Syntax in Python

Python’s asynchronous programming revolves around the asyncio library, which introduced the async and await keywords to handle asynchronous operations. Unlike JavaScript, Python does not have a built-in event loop – it relies on asyncio to create and manage one.

Example: Fetching Data with Asyncio

Using Python’s aiohttp library for asynchronous HTTP requests:

import asyncio
import aiohttp

async def fetch_data():
    async with aiohttp.ClientSession() as session:
        async with session.get('https://api.example.com/data') as response:
            data = await response.json()
            print(data)

asyncio.run(fetch_data())

How it works:

The async def syntax defines an asynchronous function.
await is used to pause execution until the get request completes.
asyncio.run() starts the event loop and runs the asynchronous function.

Key Differences from JavaScript:

Python explicitly defines asynchronous functions with async def.
The asyncio library is required to run the event loop.
Python’s async/await syntax is more structured but requires more setup compared to JavaScript.

Use Cases and Performance Considerations

Asynchronous programming is suitable for tasks that involve waiting, such as network requests, file I/O, or database queries. Here’s how Python and JavaScript handle common use cases:

Real-Time Applications (JavaScript): JavaScript’s event-driven model makes it ideal for real-time applications like chat systems, live streaming, or collaborative tools.

Example: WebSocket in JavaScript

const socket = new WebSocket('ws://example.com/socket');

socket.onmessage = (event) => {
    console.log('Message from server:', event.data);
};

I/O-Bound Tasks (Python): Python’s asynchronous model excels at handling I/O-bound tasks such as file processing, web scraping, or database queries.

Example: Asynchronous File Reading in Python

import aiofiles
import asyncio

async def read_file():
    async with aiofiles.open('example.txt', mode='r') as file:
        content = await file.read()
        print(content)

asyncio.run(read_file())

Performance Considerations:

Concurrency: Both languages handle concurrency well, but JavaScript’s event loop and non-blocking I/O model are better suited for high-throughput, real-time applications.
Threading: Python’s asyncio works best for I/O-bound tasks. For CPU-bound tasks, Python relies on multi-threading or multi-processing.
Ease of Use: JavaScript’s async/await is simpler to implement for beginners, while Python requires familiarity with asyncio for similar functionality.

Key Takeaways:

JavaScript: Asynchronous programming is central to JavaScript’s design. Its event loop and Promises make it highly efficient for real-time, event-driven applications.
Python: Asynchronous programming is a newer addition to Python, focused on handling I/O-bound tasks efficiently with asyncio.
Syntax: Both languages use async/await, but Python requires explicit setup with asyncio, while JavaScript integrates it natively.

8. Modules, Packages, and Dependency Management

Both Python and JavaScript encourage modular programming, allowing developers to divide code into reusable and maintainable components.

Managing modules, packages, and dependencies is essential for any non-trivial project, and both languages provide robust systems to handle these needs. But the tools and ecosystems differ significantly.

Node.js Modules vs. Python Packages

JavaScript: JavaScript uses the Node.js module system, which allows developers to organize code into modules. Modules can be imported using require (CommonJS) or import (ES6 modules).

Example: Exporting and Importing Modules in JavaScript

Exporting from a module (utils.js):

export function add(a, b) {
    return a + b;
}

export function multiply(a, b) {
    return a * b;
}

Importing in another file (main.js):

import { add, multiply } from './utils.js';

console.log(add(2, 3));       // Output: 5
console.log(multiply(2, 3));  // Output: 6

CommonJS uses module.exports and require():

// utils.js
module.exports = {
    add: (a, b) => a + b,
    multiply: (a, b) => a * b,
};

// main.js
const { add, multiply } = require('./utils');
console.log(add(2, 3));       // Output: 5
console.log(multiply(2, 3));  // Output: 6

Python: Python organizes reusable code into modules and packages. A module is simply a .py file, and a package is a directory containing a special __init__.py file, which can include one or more modules.

Example: Exporting and Importing Modules in Python

Exporting from a module (utils.py):

def add(a, b):
    return a + b

def multiply(a, b):
    return a * b

Importing in another file (main.py):

from utils import add, multiply

print(add(2, 3))       # Output: 5
print(multiply(2, 3))  # Output: 6

Python uses import for loading modules and supports relative imports for packages.

Package Managers: NPM vs. pip

Both languages provide package managers for installing and managing third-party libraries and dependencies.

NPM (JavaScript):

Node Package Manager (NPM) is JavaScript’s default package manager, and it comes bundled with Node.js.
It uses a package.json file to define dependencies, scripts, and metadata for a project.

Example: Installing a Library with NPM

npm install express

Example: Defining Dependencies in package.json

{
    "dependencies": {
        "express": "^4.18.2"
    }
}

pip (Python):

Python uses pip (Python Installer Package) to manage libraries and frameworks.
Python projects commonly use a requirements.txt file to list dependencies.

Example: Installing a Library with pip

pip install flask

Example: Defining Dependencies in requirements.txt

flask==2.3.0
requests==2.31.0

To install all dependencies in requirements.txt:

bashCopy codepip install -r requirements.txt

Comparison:

NPM allows version ranges and automatically creates node_modules to manage dependencies. It also supports both development (--save-dev) and production dependencies.
pip installs libraries globally or in a virtual environment but lacks the automatic distinction between dev and production dependencies, which must be handled manually.

Managing Dependencies in Python with Virtual Environments

Python has a unique feature for isolating dependencies: virtual environments. Virtual environments ensure that dependencies for one project don’t interfere with another, avoiding conflicts.

Creating a Virtual Environment:

python -m venv myenv

Activating the Virtual Environment:

Windows:

myenv\Scripts\activate

macOS/Linux:

source myenv/bin/activate

Installing Libraries in the Virtual Environment:

pip install flask

Deactivating the Virtual Environment:

deactivate

JavaScript Alternative: While JavaScript does not require virtual environments, tools like nvm (Node Version Manager) can be used to manage different Node.js versions for projects.

Project Structures and Best Practices

JavaScript Project Structure: A typical Node.js project includes:

my-node-project/
├── node_modules/  # Installed dependencies
├── src/           # Source code
│   ├── app.js     # Entry point
│   ├── utils.js   # Utility module
├── package.json   # Dependency and project metadata
├── package-lock.json  # Dependency tree for consistency

Python Project Structure: A typical Python project includes:

my-python-project/
├── venv/            # Virtual environment
├── src/             # Source code
│   ├── __init__.py  # Package initializer
│   ├── app.py       # Entry point
│   ├── utils.py     # Utility module
├── requirements.txt # Dependency list

Key Takeaways:

Modules: Both languages support modular programming. Python modules are simple .py files, while JavaScript has both CommonJS and ES6 modules.
Package Managers: NPM and pip serve similar purposes but have different approaches. NPM is more feature-rich, supporting scripts and version management, while pip is simpler but relies on virtual environments for isolation.
Dependency Isolation: Python’s virtual environments ensure clean project separation, a feature not natively required in JavaScript due to its global Node.js architecture.

9. Error Handling and Debugging

Error handling and debugging are critical for writing robust and maintainable code. Both Python and JavaScript provide mechanisms for catching and managing errors, but they handle these tasks differently. Understanding these mechanisms is essential for developers transitioning between the two languages.

Exception Handling in Python vs. Error Handling in JavaScript

Both Python and JavaScript use try-except (or try-catch in JavaScript) blocks to handle errors. These constructs allow developers to catch exceptions, manage them gracefully, and prevent program crashes.

Python Exception Handling: Python uses try, except, and finally to handle exceptions. The else clause can also be used to execute code only if no exceptions occur.

Example: Python Exception Handling

try:
    result = 10 / 0
except ZeroDivisionError as e:
    print(f"Error: {e}")
else:
    print("No errors occurred!")
finally:
    print("Execution complete.")
# Output:
# Error: division by zero
# Execution complete.

Key Features of Python Exception Handling:

Specific Exceptions: Python allows catching specific exceptions like ZeroDivisionError, making error handling more precise.
Optional Else Block: The else block runs if no exceptions are raised, which can simplify code logic.

JavaScript Error Handling: JavaScript uses try, catch, and finally for error handling. Errors can be thrown manually using the throw keyword.

Example: JavaScript Error Handling

try {
    const result = 10 / 0;
    if (!isFinite(result)) {
        throw new Error("Division by zero is not allowed.");
    }
} catch (error) {
    console.log(`Error: ${error.message}`);
} finally {
    console.log("Execution complete.");
}
// Output:
// Error: Division by zero is not allowed.
// Execution complete.

Key Features of JavaScript Error Handling:

Generic Catch Block: JavaScript's catch block catches all errors by default. To handle specific error types, manual checks are needed.
Error Object: JavaScript provides an Error object with properties like message, name, and stack for debugging.

Common Errors and How to Debug Them

Both Python and JavaScript have common runtime errors, but their debugging tools and techniques differ.

Python Common Errors:

SyntaxError: Occurs when code violates Python's syntax rules.
```
 print("Hello World"  # Missing closing parenthesis
```
TypeError: Raised when an operation is applied to an object of inappropriate type.
```
 print("Hello" + 5)  # Cannot concatenate str and int
```
ValueError: Raised when a function receives an argument of the correct type but invalid value.
```
 int("abc")  # Cannot convert string to int
```

Debugging in Python:

Stack Trace: Python provides a detailed stack trace when an exception occurs, showing the file, line number, and call stack.

Logging: Python’s logging module helps record errors and program state.

  import logging
  logging.basicConfig(level=logging.ERROR)
  logging.error("An error occurred.")

Debuggers: Tools like pdb (Python Debugger) allow stepping through code to inspect variables.
```
  import pdb; pdb.set_trace()
```

JavaScript Common Errors:

SyntaxError: Thrown when code violates JavaScript's syntax rules.
```
 console.log("Hello World" // Missing closing parenthesis
```

TypeError: Occurs when an operation is performed on an undefined or incompatible type.

 console.log("Hello" + 5); // Allowed, but accessing a method on null is a TypeError

ReferenceError: Thrown when accessing a variable that hasn’t been declared.
```
 console.log(x); // x is not defined
```

Debugging in JavaScript:

Stack Trace: JavaScript errors include a stack trace, showing the error type and line number.

Console Logging: The console.log and console.error methods are often used for debugging.

  console.log("Variable value:", myVar);
  console.error("An error occurred.");

Browser DevTools: Modern browsers include developer tools with JavaScript debuggers, allowing you to set breakpoints, step through code, and inspect variables.
Debugging with Node.js: Use the --inspect flag to debug Node.js applications with Chrome DevTools.
```
  node --inspect app.js
```

Tools for Debugging

Both Python and JavaScript have robust tools for debugging, ranging from built-in modules to integrated development environments (IDEs).

Python Debugging Tools:

Built-In Debugger (pdb): A command-line tool for inspecting and controlling execution.
IDE Debugging: IDEs like PyCharm and VS Code provide graphical debugging with breakpoints and variable inspection.
Logging: The logging module can be configured to capture detailed runtime information.

JavaScript Debugging Tools:

Browser Developer Tools: Chrome DevTools, Firefox Developer Tools, and Edge DevTools are indispensable for frontend debugging.
Node.js Debugger: Debug Node.js applications using node inspect or --inspect with a compatible debugger like Chrome DevTools.
Third-Party Tools: Tools like ESLint help catch errors before runtime by enforcing coding standards and highlighting potential issues.

Key Takeaways:

Error Handling Syntax: Both Python and JavaScript use try-catch constructs, but Python’s except supports catching specific exception types.
Debugging Approaches: Python relies heavily on logging and the pdb debugger, while JavaScript benefits from browser DevTools and real-time inspection.
Common Errors: Syntax and type-related errors are common in both languages, but Python’s explicit type system provides clearer error messages compared to JavaScript’s looser type handling.
Tools: Each language has a rich ecosystem of debugging tools tailored to its common use cases.

10. Testing and Frameworks

Testing is an integral part of software development, ensuring that applications behave as expected and reducing the likelihood of bugs. Both Python and JavaScript have robust ecosystems for testing, offering various frameworks and tools to streamline the process.

Popular Testing Frameworks: Mocha/Chai vs. Pytest/Unittest

Both Python and JavaScript have multiple testing frameworks, each tailored to specific needs. For JavaScript, Mocha and Chai are popular choices, while Python developers often use Pytest or the built-in Unittest module.

JavaScript: Mocha and Chai
Mocha is a flexible testing framework for JavaScript, and Chai is often paired with it to provide assertion libraries for more readable test cases.

Example: Mocha and Chai

const { expect } = require('chai');

// Function to test
function add(a, b) {
    return a + b;
}

// Mocha test
describe('Add Function', () => {
    it('should return the sum of two numbers', () => {
        expect(add(2, 3)).to.equal(5);
    });

    it('should handle negative numbers', () => {
        expect(add(-2, -3)).to.equal(-5);
    });
});

Python: Pytest
Pytest is a widely used framework in Python that emphasizes simplicity and flexibility. Tests can be written as plain functions, and Pytest’s built-in fixtures streamline setup and teardown.

Example: Pytest

import pytest

# Function to test
def add(a, b):
    return a + b

# Pytest functions
def test_add_positive_numbers():
    assert add(2, 3) == 5

def test_add_negative_numbers():
    assert add(-2, -3) == -5

Key Differences:

Syntax: Mocha/Chai uses JavaScript syntax with chaining assertions (expect), while Pytest relies on Python’s assert keyword.
Fixtures: Pytest fixtures simplify test setup, whereas Mocha relies on manual setup functions (before, beforeEach).

Writing Unit Tests and Test Coverage

Unit testing focuses on verifying individual components or functions in isolation. Both Python and JavaScript frameworks support unit tests, but the tools for measuring test coverage differ.

JavaScript: nyc (Istanbul)
The nyc tool, built on Istanbul, is commonly used to measure test coverage in JavaScript projects.

Example: Generating Coverage Reports with Mocha and nyc

npm install --save-dev mocha nyc

Add a test script to package.json:

"scripts": {
    "test": "mocha",
    "coverage": "nyc mocha"
}

Run the coverage command:

npm run coverage

This generates a report showing which parts of the code were covered during tests.

Python: Coverage.py
In Python, coverage.py is the standard tool for measuring test coverage.

Example: Generating Coverage Reports with Pytest and Coverage.py

pip install pytest coverage

Run tests with coverage:

coverage run -m pytest
coverage report

This displays coverage percentages for each file and highlights untested lines.

Key Differences:

JavaScript tools like nyc integrate easily with CI/CD pipelines, while coverage.py provides detailed line-by-line reports.

Automation and CI/CD Compatibility

Modern development workflows often include automated testing integrated into CI/CD pipelines. Both Python and JavaScript testing frameworks are compatible with CI/CD tools like Jenkins, GitHub Actions, and GitLab CI.

Example: Automating Tests in a CI/CD Pipeline

JavaScript (GitHub Actions):

name: Node.js CI

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - uses: actions/setup-node@v2
      with:
        node-version: '14'
    - run: npm install
    - run: npm test
    - run: npm run coverage

Python (GitHub Actions):

name: Python CI

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - uses: actions/setup-python@v2
      with:
        python-version: '3.9'
    - run: pip install -r requirements.txt
    - run: pytest --cov=.

Integration and End-to-End Testing

In addition to unit testing, both languages support integration and end-to-end (E2E) testing.

JavaScript: Cypress for E2E Testing
Cypress is a popular tool for E2E testing of web applications, providing a developer-friendly interface and real-time browser interaction.

Example: Cypress Test

describe('Login Page', () => {
    it('should log in with valid credentials', () => {
        cy.visit('/login');
        cy.get('#username').type('user');
        cy.get('#password').type('password');
        cy.get('button[type="submit"]').click();
        cy.url().should('include', '/dashboard');
    });
});

Python: Selenium for Browser Automation
Selenium is commonly used in Python for E2E testing of web applications, automating browser interactions.

Example: Selenium Test

from selenium import webdriver

def test_login():
    driver = webdriver.Chrome()
    driver.get("http://example.com/login")
    driver.find_element_by_id("username").send_keys("user")
    driver.find_element_by_id("password").send_keys("password")
    driver.find_element_by_css_selector("button[type='submit']").click()
    assert "dashboard" in driver.current_url
    driver.quit()

Key Takeaways:

Unit Testing: JavaScript (Mocha/Chai) and Python (Pytest) frameworks are highly flexible, but Pytest’s concise syntax makes it particularly beginner-friendly.
Test Coverage: Both nyc (JavaScript) and coverage.py (Python) are effective for measuring test coverage and identifying gaps.
E2E Testing: JavaScript developers can leverage Cypress for browser testing, while Python offers Selenium for automation.
CI/CD Compatibility: Both languages integrate seamlessly with modern CI/CD pipelines, enabling automated testing at every stage of development.

11. Practical Applications and Examples

Both Python and JavaScript excel in various practical applications, but their strengths shine in different domains. This section explores common use cases for each language, providing hands-on examples to showcase their capabilities and differences.

Writing a Simple Web Scraper

Python: Using BeautifulSoup
Python’s libraries, such as BeautifulSoup and Requests, make web scraping straightforward and efficient.

Example: Web Scraper in Python

import requests
from bs4 import BeautifulSoup

# Fetch the webpage
url = "https://example.com"
response = requests.get(url)

# Parse the HTML content
soup = BeautifulSoup(response.content, "html.parser")

# Extract specific data
titles = soup.find_all("h2")
for title in titles:
    print(title.text)

JavaScript: Using Puppeteer
JavaScript can also scrape web content using libraries like Puppeteer, which allows headless browsing.

Example: Web Scraper in JavaScript

const puppeteer = require('puppeteer');

(async () => {
    const browser = await puppeteer.launch();
    const page = await browser.newPage();
    await page.goto('https://example.com');

    // Extract specific data
    const titles = await page.$$eval('h2', elements => elements.map(el => el.textContent));
    console.log(titles);

    await browser.close();
})();

Key Differences:

Python’s BeautifulSoup is simpler for static pages, while Puppeteer provides more flexibility for dynamic content rendered by JavaScript.

Creating a REST API

Python: Flask
Python’s Flask framework is lightweight and ideal for quickly building APIs.

Example: REST API in Python

from flask import Flask, jsonify

app = Flask(__name__)

@app.route('/api/data', methods=['GET'])
def get_data():
    return jsonify({"message": "Hello, World!"})

if __name__ == '__main__':
    app.run(debug=True)

JavaScript: Express
Express is a popular framework for creating REST APIs in JavaScript.

Example: REST API in JavaScript

const express = require('express');
const app = express();

app.get('/api/data', (req, res) => {
    res.json({ message: 'Hello, World!' });
});

app.listen(3000, () => {
    console.log('Server running on port 3000');
});

Key Differences:

Flask offers built-in simplicity with decorators for routing.
Express requires more explicit configuration but is better suited for large-scale Node.js projects.

Automation Scripts: File Handling, Network Requests, and Scripting

Python: Automation with os and shutil
Python excels at automation tasks, making file and system operations straightforward.

Example: File Automation in Python

import os
import shutil

# Create a directory
os.makedirs("example_dir", exist_ok=True)

# Move a file
shutil.move("source.txt", "example_dir/destination.txt")

# List files in a directory
for file in os.listdir("example_dir"):
    print(file)

JavaScript: File System Module (fs)
JavaScript’s fs module allows file handling, but it requires more boilerplate.

Example: File Automation in JavaScript

const fs = require('fs');
const path = require('path');

// Create a directory
fs.mkdirSync('example_dir', { recursive: true });

// Move a file
fs.renameSync('source.txt', path.join('example_dir', 'destination.txt'));

// List files in a directory
fs.readdirSync('example_dir').forEach(file => {
    console.log(file);
});

Key Differences:

Python’s os and shutil modules provide concise methods for file and system operations.
JavaScript requires more explicit handling for similar tasks using Node.js modules.

Data Processing and Visualization

Python: Data Science with Pandas and Matplotlib
Python dominates data processing and visualization with libraries like Pandas and Matplotlib.

Example: Data Analysis in Python

import pandas as pd
import matplotlib.pyplot as plt

# Create a DataFrame
data = {'Name': ['Alice', 'Bob', 'Charlie'], 'Age': [25, 30, 35]}
df = pd.DataFrame(data)

# Plot the data
df.plot(x='Name', y='Age', kind='bar')
plt.show()

JavaScript: Data Visualization with D3.js
JavaScript excels at interactive web-based visualizations with D3.js.

Example: Data Visualization in JavaScript

const d3 = require('d3');
const data = [
    { name: 'Alice', age: 25 },
    { name: 'Bob', age: 30 },
    { name: 'Charlie', age: 35 }
];

const svg = d3.create("svg")
    .attr("width", 500)
    .attr("height", 300);

svg.selectAll("rect")
    .data(data)
    .enter()
    .append("rect")
    .attr("x", (d, i) => i * 100)
    .attr("y", d => 300 - d.age * 5)
    .attr("width", 50)
    .attr("height", d => d.age * 5);

console.log(svg.node().outerHTML);

Key Differences:

Python’s data libraries are geared toward analysis and are simpler for static visualizations.
JavaScript’s D3.js creates highly interactive visualizations for web applications.

Machine Learning and AI

Python: TensorFlow
Python’s TensorFlow library simplifies building machine learning models.

Example: Machine Learning in Python

import tensorflow as tf

# Define a simple model
model = tf.keras.Sequential([
    tf.keras.layers.Dense(units=1, input_shape=[1])
])

model.compile(optimizer='sgd', loss='mean_squared_error')

# Train the model
xs = [1, 2, 3, 4]
ys = [2, 4, 6, 8]
model.fit(xs, ys, epochs=500, verbose=0)

# Predict
print(model.predict([5]))  # Output: [[10]]

JavaScript: TensorFlow.js
TensorFlow.js brings machine learning capabilities to JavaScript.

Example: Machine Learning in JavaScript

const tf = require('@tensorflow/tfjs-node');

// Define a simple model
const model = tf.sequential();
model.add(tf.layers.dense({ units: 1, inputShape: [1] }));
model.compile({ optimizer: 'sgd', loss: 'meanSquaredError' });

// Train the model
const xs = tf.tensor([1, 2, 3, 4]);
const ys = tf.tensor([2, 4, 6, 8]);
model.fit(xs, ys, { epochs: 500 }).then(() => {
    // Predict
    model.predict(tf.tensor([5])).print();  // Output: [[10]]
});

Key Differences:

Python dominates in machine learning due to its mature ecosystem and extensive documentation.
TensorFlow.js allows machine learning in JavaScript, but it is less mature compared to Python’s TensorFlow.

Key Takeaways:

Web Scraping: Python excels with BeautifulSoup for static content, while Puppeteer is better for dynamic content.
REST APIs: Python’s Flask is lightweight and easy to use, while JavaScript’s Express offers flexibility and scalability.
Automation: Python simplifies file and system operations with os and shutil, while JavaScript achieves similar results with Node.js modules.
Data Visualization: Python’s libraries focus on analysis, while JavaScript’s D3.js creates interactive, web-based visualizations.
Machine Learning: Python leads with TensorFlow and other ML frameworks, while TensorFlow.js brings ML capabilities to JavaScript.

12. Community, Libraries, and Ecosystem

The strength of a programming language often lies in its community, ecosystem, and the libraries available for solving common problems. Both Python and JavaScript have vast ecosystems supported by active communities, but they cater to different domains and developer needs.

Open Source Libraries: NPM vs. PyPI

Both Python and JavaScript have centralized repositories for distributing and installing open-source libraries: PyPI (Python Package Index) for Python and NPM (Node Package Manager) for JavaScript.

Python: PyPI

PyPI hosts over 400,000 packages, supporting fields like data science, web development, machine learning, and automation.
Popular libraries include:
- Pandas for data manipulation.
- NumPy for numerical computing.
- Django and Flask for web development.
- BeautifulSoup and Scrapy for web scraping.

Example: Installing and Using a PyPI Library

pip install requests

import requests

response = requests.get("https://api.example.com/data")
print(response.json())

JavaScript: NPM

NPM is the world’s largest software registry, with over 2 million packages for frontend, backend, and full-stack development.
Popular libraries include:
- React and Vue for frontend development.
- Express for backend services.
- Lodash for utility functions.
- Axios for HTTP requests.

Example: Installing and Using an NPM Library

npm install axios

const axios = require('axios');

axios.get('https://api.example.com/data')
    .then(response => console.log(response.data));

Comparison:

Breadth: NPM focuses on web development, while PyPI covers a wider range of domains, including data science and scientific research.
Tools: NPM’s CLI offers additional functionality like scripts and versioning, while pip focuses purely on library installation.

Key Libraries for Data Science, Web Development, and Automation

Both ecosystems excel in their respective strengths:

Data Science:

Python dominates with libraries like Pandas, Matplotlib, and TensorFlow, making it the top choice for data manipulation, visualization, and machine learning.
JavaScript has D3.js for interactive visualizations and TensorFlow.js for machine learning, though its ecosystem for data science is less mature.

Web Development:

JavaScript is unrivaled in frontend development with React, Vue, and Angular. For backend services, Node.js with Express is a common choice.
Python excels in backend web development with frameworks like Django and Flask, offering rapid development and scalability.

Automation:

Python is widely used for scripting and automation, with libraries like os, shutil, and schedule.
JavaScript, while less focused on automation, can handle automation tasks effectively with Node.js and tools like Puppeteer for browser automation.

Python's Strengths in Data Science and Machine Learning

Python has established itself as the go-to language for data science and machine learning due to its extensive ecosystem and user-friendly syntax.

Popular Python Libraries for Data Science:

Pandas: Data manipulation and analysis.
NumPy: Numerical computing and arrays.
Matplotlib/Seaborn: Data visualization.
Scikit-learn: Machine learning algorithms.
TensorFlow/Keras: Deep learning frameworks.

Example: Data Analysis with Pandas

import pandas as pd

data = {'Name': ['Alice', 'Bob', 'Charlie'], 'Age': [25, 30, 35]}
df = pd.DataFrame(data)

print(df.describe())

Machine Learning with TensorFlow

import tensorflow as tf

model = tf.keras.Sequential([tf.keras.layers.Dense(units=1, input_shape=[1])])
model.compile(optimizer='sgd', loss='mean_squared_error')
model.fit([1, 2, 3, 4], [2, 4, 6, 8], epochs=500)
print(model.predict([5]))

Python’s simplicity makes it easy for non-programmers, such as data analysts and researchers, to leverage these powerful tools.

JavaScript's Strengths in Web Development

JavaScript’s dominance in web development stems from its ability to run natively in the browser and its wide array of frontend frameworks.

Popular JavaScript Libraries for Web Development:

React: Component-based UI development.
Vue: Simple and progressive framework for building UIs.
Angular: Comprehensive framework for large-scale applications.
Express: Lightweight framework for creating REST APIs.
Next.js: Full-stack framework for React applications with server-side rendering.

Example: Creating a Frontend with React

import React from 'react';
import ReactDOM from 'react-dom';

function App() {
    return <h1>Hello, World!h1>;
}

ReactDOM.render(<App />, document.getElementById('root'));

Example: Creating a Backend with Express

const express = require('express');
const app = express();

app.get('/', (req, res) => {
    res.send('Hello, World!');
});

app.listen(3000, () => {
    console.log('Server running on port 3000');
});

JavaScript’s ecosystem allows developers to build full-stack applications using a single language, streamlining development workflows.

Community Support and Contribution

Both Python and JavaScript have vibrant communities that contribute to their continuous growth and evolution:

Python:
- Python Software Foundation (PSF) drives the language's development.
- Annual events like PyCon foster collaboration and learning.
- Strong academic adoption ensures its popularity in education and research.
JavaScript:
- Backed by major organizations like Node.js Foundation and open-source communities.
- Events like JSConf and React Conf promote innovation.
- A highly active GitHub community ensures frequent updates and new libraries.

13. Conclusion

Python and JavaScript are two of the most popular and versatile programming languages in the world. Each language has its own strengths, use cases, and ecosystems, making them ideal for different types of projects.

For experienced JavaScript developers, learning Python can open up new opportunities in fields like data science, machine learning, and automation, complementing their existing skills in web development and real-time applications.

Summary of Key Comparisons

Syntax:
- Python emphasizes simplicity and readability with its indentation-based syntax, making it easier to learn and maintain.
- JavaScript’s flexibility allows multiple paradigms, but its quirks, like type coercion, require careful handling.
Asynchronous Programming:
- JavaScript is inherently asynchronous, with its event-driven model excelling in real-time applications.
- Python’s asyncio library is newer but powerful for handling I/O-bound tasks.
OOP:
- Python’s class-based system is more traditional and explicit.
- JavaScript offers both prototypal inheritance and class-based syntax, providing flexibility.
Modules and Dependency Management:
- Python’s pip and virtual environments excel at dependency isolation.
- JavaScript’s NPM is more versatile, with integrated features like script management.
Testing:
- Python’s Pytest emphasizes simplicity and readability.
- JavaScript’s Mocha/Chai is highly flexible and integrates well with modern development pipelines.
Ecosystem and Community:
- Python dominates in data science, machine learning, and scripting.
- JavaScript is unmatched in web development, particularly for full-stack and frontend applications.

How Python Complements JavaScript Skills

For JavaScript developers, Python can expand your horizons in several ways:

Data Science and Machine Learning: Python’s libraries like Pandas, TensorFlow, and Scikit-learn allow you to explore fields beyond traditional programming.
Backend Development: Frameworks like Flask and Django provide a new perspective on backend services compared to Node.js.
Automation and Scripting: Python’s simplicity makes it ideal for automating repetitive tasks, from file handling to web scraping.

By adding Python to your skill set, you can become a more versatile developer, capable of tackling projects that require both web development expertise and computational power.

Resources and Next Steps for Learning Python

Here are some recommended resources to start learning Python:

Official Python Documentation: Comprehensive guides and tutorials for all skill levels: https://docs.python.org/
Books:
- Automate the Boring Stuff with Python by Al Sweigart (great for automation and scripting).
- Python Crash Course by Eric Matthes (a beginner-friendly introduction).
Online Courses:
- Python for Everybody from Dr. Chuck on freeCodeCamp’s YouTube channel
- Check out freeCodeCamp’s Python certs
Practice Platforms:
- Solve Python problems on platforms like LeetCode, HackerRank, and Codewars.
Communities:
- Join Python forums and communities such as r/Python on Reddit or the Python Discord server.

Final Thoughts

As a JavaScript developer, you already have a strong foundation in programming. Python’s clean syntax, extensive libraries, and focus on readability make it an excellent language to learn next.

By understanding how Python complements JavaScript, you can choose the best tool for each task and position yourself as a well-rounded developer in today’s competitive landscape.

The journey to mastering Python will not only broaden your technical skills but also open doors to exciting domains like data science, machine learning, and automation, allowing you to tackle diverse challenges with confidence.

How to Style a React Application – Different Options Compared

German Cocca — Mon, 05 Jun 2023 21:52:46 +0000

Styling plays a vital role in creating visually appealing and user-friendly web applications. When it comes to React applications, there are numerous ways to style components and UI elements.

In this article, we will explore several popular options, including pure CSS, CSS modules, CSS preprocessors, Tailwind CSS, CSS-in-JS libraries like Styled Components, and pre-built component libraries like Chakra UI, Material-UI, and Bootstrap.

We'll delve into each option's main characteristics, advantages, and disadvantages to help you choose the right styling approach for your React projects.

You'll learn how to style your React apps using:

Pure CSS
CSS modules
CSS preprocessors
Tailwind CSS
CSS-in-JS
Component libraries
Conclusion

How to Style Your React Apps Using Pure CSS

Pure CSS involves writing stylesheets using standard CSS syntax and linking them to your React components.

This approach is simple and widely supported, making it an excellent choice for small-scale projects. But it can become challenging to manage and scale as the application grows.

Pros:

Familiarity: Developers with CSS expertise can quickly adapt to this approach.
Browser Support: Pure CSS is supported by all modern browsers.
Lightweight: CSS files can be cached by the browser, resulting in faster page loading times.

Cons:

Global Scope: Styles defined in CSS are global by default, which can lead to naming conflicts and style leakages.
Limited Reusability: Reusing styles across components requires manually maintaining class names and selectors.

Example:

import React from 'react';
import './MyComponent.css';

const MyComponent = () => {
  return (
    <div className="my-component">
      <h1 className="title">Hello, World!h1>
      <p className="description">This is a styled React component.p>
      <button className="btn">Click Mebutton>
    div>
  );
};

export default MyComponent;

In this example, we have a component called MyComponent. To apply styles using pure CSS, we import an external CSS file called MyComponent.css. Here's how the CSS file might look:

.my-component {
  background-color: #f2f2f2;
  padding: 20px;
  border-radius: 5px;
  text-align: center;
}

.title {
  font-size: 24px;
  color: #333;
  margin-bottom: 10px;
}

.description {
  font-size: 16px;
  color: #777;
}

.btn {
  background-color: #007bff;
  color: #fff;
  border: none;
  padding: 10px 20px;
  border-radius: 4px;
  cursor: pointer;
  transition: background-color 0.3s ease;
}

.btn:hover {
  background-color: #0056b3;
}

In this CSS file, we define styles for the different classes used in the component. The my-component class styles the container div, the title class styles the heading, the description class styles the paragraph, and the btn class styles the button.

When the MyComponent is rendered, it will have the defined styles applied. The container div will have a light gray background with padding and border-radius. The heading will have a larger font size and a dark gray color, while the paragraph will have a smaller font size and a light gray color. The button will have a blue background with white text, and it will transition to a darker blue on hover.

Remember to import the CSS file correctly, ensuring that the path is accurate based on your project structure.

How to Style Your React Apps Using CSS Modules

CSS Modules aim to solve the global scope and reusability issues of pure CSS. They allow you to write modular stylesheets, where class names are scoped to specific components.

Pros:

Scoped Styles: CSS Modules generate unique class names for each component, avoiding style clashes.
Reusability: Styles defined in CSS Modules can be easily reused across components.
Clear Dependencies: Stylesheets are imported and linked directly to the components that use them.

Cons:

Learning Curve: Developers must learn and understand the CSS Modules syntax and import mechanism.
Additional Configuration: Integrating CSS Modules into a React project often requires extra configuration setup.

Example

import React from 'react';
import styles from './MyComponent.module.css';

const MyComponent = () => {
  return (
    <div className={styles.myComponent}>
      <h1 className={styles.title}>Hello, World!h1>
      <p className={styles.description}>This is a styled React component.p>
      <button className={styles.btn}>Click Mebutton>
    div>
  );
};

export default MyComponent;

In this example, we import an external CSS module file called MyComponent.module.css and assign it to the styles object. The styles object contains mappings of CSS class names to unique generated class names specific to the component.

Here's how the CSS module file might look:

.myComponent {
  background-color: #f2f2f2;
  padding: 20px;
  border-radius: 5px;
  text-align: center;
}

.title {
  font-size: 24px;
  color: #333;
  margin-bottom: 10px;
}

.description {
  font-size: 16px;
  color: #777;
}

.btn {
  background-color: #007bff;
  color: #fff;
  border: none;
  padding: 10px 20px;
  border-radius: 4px;
  cursor: pointer;
  transition: background-color 0.3s ease;
}

.btn:hover {
  background-color: #0056b3;
}

In the CSS module file, you define styles as you would in regular CSS, but instead of using global class names, you use local class names. These local class names are scoped to the component and have unique names generated during the build process.

When the MyComponent is rendered, the CSS module styles are applied using the corresponding class names from the styles object. The component's container div, heading, paragraph, and button will have the respective styles applied.

Make sure to use the className attribute and reference the CSS module class names from the styles object in your component's JSX. The CSS module system will automatically map these class names to the unique generated class names, ensuring style encapsulation and preventing class name collisions.

Note that the CSS module file should have the .module.css file extension for the module to work correctly.

How to Style Your React Apps Using CSS preprocessors

CSS preprocessors like SASS, LESS or Stylus provide additional features like variables, nesting, mixins, and more. It enhances the productivity and maintainability of CSS code.

Pros:

Advanced Features: SCSS introduces powerful features that simplify CSS writing and management.
Code Reusability: SCSS allows creating reusable code snippets using mixins and variables.
Easy Migration: Existing CSS files can be gradually converted to SCSS without significant refactoring.

Cons:

Compilation Step: SCSS files need to be compiled into regular CSS before they can be used.
Learning Curve: Developers must learn SCSS syntax and its specific features.

Example

Here's an example of how you can use Sass to style a React component. First, make sure you have Sass installed in your project by running npm install node-sass or yarn add node-sass.

import React from 'react';
import './MyComponent.scss';

const MyComponent = () => {
  return (
    <div className="my-component">
      <h1 className="title">Hello, World!h1>
      <p className="description">This is a styled React component.p>
      <button className="btn">Click Mebutton>
    div>
  );
};

export default MyComponent;

In this example, we import an external SCSS file called MyComponent.scss. Make sure the file extension is .scss for Sass files. Here's how the SCSS file might look:

.my-component {
  background-color: #f2f2f2;
  padding: 20px;
  border-radius: 5px;
  text-align: center;

  .title {
    font-size: 24px;
    color: #333;
    margin-bottom: 10px;
  }

  .description {
    font-size: 16px;
    color: #777;
  }

  .btn {
    background-color: #007bff;
    color: #fff;
    border: none;
    padding: 10px 20px;
    border-radius: 4px;
    cursor: pointer;
    transition: background-color 0.3s ease;

    &:hover {
      background-color: #0056b3;
    }
  }
}

How to Style Your React Apps Using Tailwind CSS

Tailwind CSS is a utility-first CSS framework that offers a vast set of pre-defined utility classes. It promotes rapid development and consistent styling across an application.

Pros:

Rapid Prototyping: Tailwind CSS provides an extensive collection of utility classes, enabling quick UI development.
Highly Customizable: The framework allows customization through a configuration file, enabling tailored styling.
Consistent Styling: By using predefined utility classes, styling consistency can be easily maintained.

Cons:

File Size: Including the entire Tailwind CSS framework can result in a larger bundle size.
Class Overload: Over-reliance on utility classes may lead to bloated HTML markup.

Example:

First, make sure you have Tailwind CSS installed in your project by following the installation guide in the official Tailwind CSS documentation.

import React from 'react';

const MyComponent = () => {
  return (
    <div className="bg-gray-200 p-4 rounded-lg text-center">
      <h1 className="text-2xl text-gray-800 mb-2">Hello, World!h1>
      <p className="text-base text-gray-600">This is a styled React component.p>
      <button className="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded">
        Click Me
      button>
    div>
  );
};

export default MyComponent;

In this example, we don't import any external CSS or SCSS files. Instead, we directly use Tailwind CSS utility classes within the component's JSX. The utility classes provide ready-to-use styles for various aspects of the component.

The utility classes used in the example (bg-gray-200, p-4, rounded-lg, text-center, text-2xl, text-gray-800, mb-2, text-base, text-gray-600, bg-blue-500, hover:bg-blue-700, text-white, font-bold, py-2, px-4, rounded) define the background color, padding, border radius, text alignment, text size, text color, margins, button styling, and more.

When the MyComponent is rendered, the respective utility classes from Tailwind CSS will be applied to the corresponding elements, resulting in the desired styles.

Ensure that your project is properly configured to use Tailwind CSS, including importing the necessary Tailwind CSS stylesheets and applying the required build process (such as running npm run build or yarn build to generate the production-ready CSS file).

Tailwind CSS provides a wide range of utility classes, and you can mix and match them to create the desired styling for your React components. Refer to the official Tailwind CSS documentation for more information on available utility classes and customization options.

How to Style Your React Apps Using CSS-in-JS

CSS-in-JS libraries like Styled Components offer a unique approach to styling by allowing developers to write CSS directly in their JavaScript code. Styled Components offer a way to create reusable and scoped styles within React components.

Pros:

Component-Based Styling: Styles are written within the component, enhancing code organization and reusability.
Dynamic Styling: Styled Components enable dynamic styling based on component props or state.
Easy Theme Integration: Themes can be easily incorporated, providing consistent styling throughout the application.

Cons:

Build Complexity: CSS-in-JS solutions often require additional build tools and dependencies.
Performance Impact: Generating dynamic styles at runtime can impact the application's performance.

Example

First, make sure you have the Styled Components library installed in your project by running npm install styled-components or yarn add styled-components.

import React from 'react';
import styled from 'styled-components';

const StyledDiv = styled.div`
  background-color: #f2f2f2;
  padding: 20px;
  border-radius: 5px;
  text-align: center;
`;

const StyledTitle = styled.h1`
  font-size: 24px;
  color: #333;
  margin-bottom: 10px;
`;

const StyledDescription = styled.p`
  font-size: 16px;
  color: #777;
`;

const StyledButton = styled.button`
  background-color: #007bff;
  color: #fff;
  border: none;
  padding: 10px 20px;
  border-radius: 4px;
  cursor: pointer;
  transition: background-color 0.3s ease;

  &:hover {
    background-color: #0056b3;
  }
`;

const MyComponent = () => {
  return (
    <StyledDiv>
      <StyledTitle>Hello, World!StyledTitle>
      <StyledDescription>This is a styled React component.StyledDescription>
      <StyledButton>Click MeStyledButton>
    StyledDiv>
  );
};

export default MyComponent;

In this example, we import the styled function from the styled-components library. We then create styled components by assigning the result of calling styled with the desired HTML element to variables (StyledDiv, StyledTitle, StyledDescription, StyledButton).

Within the backticks (`) of each styled component, we define the CSS rules specific to that component.

When the MyComponent is rendered, the styled components are used in place of the regular HTML elements. The styles defined within the respective styled components will be applied to the corresponding elements.

Styled Components allow you to write CSS directly within your JavaScript code, making it easy to encapsulate styles and create reusable components. You can also pass props to styled components and use them in your CSS rules to create dynamic styles.

Make sure to import the styled function from styled-components and define your styled components before using them in your component.

Remember to install and configure Styled Components in your project before using them.

How to Style Your React Apps Using Component Libraries

Component libraries like Chakra UI, Material-UI, and Bootstrap offer pre-built and styled React components along with accompanying styles. These libraries provide a consistent and cohesive UI design language.

Pros:

Rapid Development: Ready-to-use components speed up the development process.
Consistent Styling: Components within a library adhere to a unified design system, ensuring visual consistency.
Extensive Documentation: Popular component libraries have well-documented APIs and guidelines.

Cons:

Customization Limitations: While these libraries offer customization options, they may not fulfill every design requirement.
Bundle Size: Including an entire component library can increase the application's bundle size.

Example

First, make sure you have Material-UI installed in your project by running npm install @mui/material or yarn add @mui/material.

import React from 'react';
import { styled } from '@mui/system';
import { Button, Paper, Typography } from '@mui/material';

const StyledPaper = styled(Paper)(({ theme }) => ({
  backgroundColor: '#f2f2f2',
  padding: theme.spacing(2),
  borderRadius: theme.spacing(1),
  textAlign: 'center',
}));

const StyledTitle = styled(Typography)(({ theme }) => ({
  fontSize: 24,
  color: '#333',
  marginBottom: theme.spacing(1),
}));

const StyledDescription = styled(Typography)(({ theme }) => ({
  fontSize: 16,
  color: '#777',
}));

const StyledButton = styled(Button)(({ theme }) => ({
  backgroundColor: '#007bff',
  color: '#fff',
  borderRadius: theme.spacing(1),
  padding: theme.spacing(1, 2),
  transition: 'background-color 0.3s ease',

  '&:hover': {
    backgroundColor: '#0056b3',
  },
}));

const MyComponent = () => {
  return (
    <StyledPaper>
      <StyledTitle variant="h1">Hello, World!StyledTitle>
      <StyledDescription variant="body1">This is a styled React component.StyledDescription>
      <StyledButton variant="contained">Click MeStyledButton>
    StyledPaper>
  );
};

export default MyComponent;

In this example, we import the necessary components from Material-UI (Button, Paper, Typography) and the styled function from @mui/system. We then create styled components using the styled function, assigning the result to variables (StyledPaper, StyledTitle, StyledDescription, StyledButton).

Within the function passed to styled, we define the CSS rules specific to each styled component using the Material-UI theme object (theme) for consistent theming.

When the MyComponent is rendered, the styled components are used in place of the regular Material-UI components. The styles defined within the respective styled components will be applied to the corresponding elements.

Styled components in Material-UI follow a similar approach to Styled Components, allowing you to encapsulate styles within your components using the styled function and the Material-UI theme object.

Make sure to import the necessary components and functions from Material-UI and define your styled components before using them in your component.

Remember to install and configure Material-UI in your project before using it.

Conclusion

Based on what we've seen, here's a quick comparison table between different options for styling a React app:

Option	Main Characteristics	Pros	Cons	When to Use
Pure CSS	Traditional approach with global CSS files	Simple and familiar	Lack of encapsulation and potential for class name collisions	Small projects or when CSS customization is the main focus
CSS Modules	CSS files with locally scoped class names	Scoped styles and prevents class name clashes	Requires importing and referencing unique class names	Medium-sized projects requiring style encapsulation
CSS Preprocessors (e.g., Sass, Less)	Enhanced CSS syntax with variables, mixins, etc.	Reusable code, modular and maintainable styles	Build process needed for compilation	Projects that benefit from enhanced CSS syntax
Tailwind CSS	Utility-based CSS framework	Rapid development, consistent styling, extensive utility classes	Large file size due to utility classes	Prototyping or projects where rapid development is crucial
CSS-in-JS	Writing CSS directly in JavaScript using libraries like Styled Components or Emotion	Component-based styles, dynamic styling, props-based styles	Increased bundle size, additional learning curve	Projects with complex or dynamic styling requirements
Component Libraries (e.g., MUI, Chakra)	Pre-styled and customizable UI components	Consistent design, extensive component library, theming support	Limited customization options, larger bundle size	Projects requiring ready-to-use UI components with theming support

Each option has its own strengths and weaknesses, and the choice depends on the specific project requirements and preferences. Here's a breakdown of when each option may be more convenient:

Pure CSS: Suitable for small projects or when CSS customization is the main focus. It is simple and familiar but lacks encapsulation and can lead to class name collisions in larger projects.
CSS Modules: Ideal for medium-sized projects that require style encapsulation. It offers scoped styles, prevents class name clashes, and requires importing and referencing unique class names.
CSS Preprocessors: Recommended for projects that benefit from enhanced CSS syntax with variables, mixins, and other features. They promote reusable and maintainable styles but require a build process for compilation.
Tailwind CSS: Perfect for rapid development and prototyping. It provides an extensive set of utility classes for consistent styling but can result in a large file size due to the number of utility classes.
CSS-in-JS: Well-suited for projects with complex or dynamic styling requirements. Writing CSS directly in JavaScript offers component-based styles and dynamic styling capabilities, but it may increase the bundle size and has an additional learning curve.
Component Libraries: Useful when you need ready-to-use UI components with consistent design and theming support. They offer extensive component libraries but may have limited customization options and result in a larger bundle size.

Consider the project's size, styling needs, development speed, and customization requirements when choosing the appropriate styling option. It's also worth considering the team's familiarity with the chosen option and its ecosystem.

Well everyone, as always, I hope you enjoyed the article and learned something new.

If you want, you can also follow me on LinkedIn or Twitter. See you in the next one!

How to Write Clean Code – Tips and Best Practices (Full Handbook)

German Cocca — Mon, 15 May 2023 14:43:44 +0000

Hi everyone! In this handbook we're going to talk about writing "clean" code. It's a topic that used to confuse me a bit when I was starting out as a programmer, and I find that it has many nuances and possible interpretations.

So in this article we'll talk about what the term "clean code" means, why it's important, how can we assess whether a codebase is clean or not. You'll also learn some best practices and conventions you can follow to make your code cleaner.

Let's go!

What does it mean to write "clean code" and why should I care?
How can I assess whether a codebase is clean or not?
Tips and conventions to write cleaner code
Wrapping up

What Does it Mean to Write "Clean Code" and Why Should I Care?

Clean code is a term used to describe computer code that is easy to read, understand, and maintain. Clean code is written in a way that makes it simple, concise, and expressive. It follows a set of conventions, standards, and practices that make it easy to read and follow.

Clean code is free from complexity, redundancy, and other code smells and anti-patterns that can make it difficult to maintain, debug, and modify.

I can't overstate the importance of clean code. When code is easy to read and understand, it makes it easier for developers to work on the codebase. This can lead to increased productivity and reduced errors.

Also, when code is easy to maintain, it ensures that the codebase can be improved and updated over time. This is especially important for long-term projects where code must be maintained and updated for years to come.

How Can I Assess Whether a Codebase is Clean or Not?

You can assess clean code in a variety of ways. Good documentation, consistent formatting, and a well-organized codebase are all indicators of clean code.

Code reviews can also help to identify potential issues and ensure that code follows best practices and conventions.

Testing is also an important aspect of clean code. It helps to ensure that code is functioning as expected and can catch errors early.

There are several tools, practices, and conventions you can implement to ensure a clean codebase. By implementing these tools and practices, developers can create a codebase that is easy to read, understand, and maintain.

It's also important to remember that there's an inevitable amount of subjectivity related to this topic, and there are a number of different opinions and tips out there. What might look clean and awesome for one person or one project might not be so for another person or another project.

But still there are a few general conventions we can follow to achieve cleaner code, so let's jump into that now.

Tips and Conventions to Write Cleaner Code

Effectiveness, Efficiency and Simplicity

Whenever I need to think about how to implement a new feature into an already existing codebase, or how to tackle the solution of a specific problem, I always prioritize this three simple things.

Effectiveness

First, our code should be effective, meaning it should solve the problem it's supposed to solve. Of course this is the most basic expectation we could have for our code, but if our implementation doesn't actually work, it's worthless to think about any other thing.

Efficiency

Second, once we know our code solves the problem, we should check if it does so efficiently. Does the program run using a reasonable amount of resources in terms of time and space? Can it run faster and with less space?

Algorithmic complexity is something you should be aware of in order to evaluate this. If you're not familiar with it, you can check this article I wrote.

To expand upon efficiency, here are two examples of a function that calculates the sum of all numbers in an array.

// Inefficient Example
function sumArrayInefficient(array) {
  let sum = 0;
  for (let i = 0; i < array.length; i++) {
    sum += array[i];
  }
  return sum;
}

This implementation of the sumArrayInefficient function iterates over the array using a for loop and adds each element to the sum variable. This is a valid solution, but it is not very efficient because it requires iterating over the entire array, regardless of its length.

// Efficient example
function sumArrayEfficient(array) {
  return array.reduce((a, b) => a + b, 0);
}

This implementation of the sumArrayEfficient function uses the reduce method to sum the elements of the array. The reduce method applies a function to each element of the array and accumulates the result. In this case, the function simply adds each element to the accumulator, which starts at 0.

This is a more efficient solution because it only requires a single iteration over the array and performs the summing operation on each element as it goes.

Simplicity

And last comes simplicity. This is the toughest one to evaluate because its subjective, it depends on the person who reads the code. But some guidelines we can follow are:

Can you easily understand what the program does at each line?
Do functions and variables have names that clearly represent their responsibilities?
Is the code indented correctly and spaced with the same format all along the codebase?
Is there any documentation available for the code? Are comments used to explain complex parts of the program?
How quick can you identify in which part of the codebase are certain features of the program? Can you delete/add new features without the need of modifying many other parts of the code?
Does the code follow a modular approach, with different features separated in components?
Is code reused when possible?
Are the same architecture, design, and implementation decisions followed equally all along the codebase?

By following and prioritizing these three concepts of effectiveness, efficiency, and simplicity, we can always have a guideline to follow when thinking about how to implement a solution. Now let's expand upon some of the guidelines that can help us simplify our code.

Format and Syntax

Using consistent formatting and syntax throughout a codebase is an important aspect of writing clean code. This is because consistent formatting and syntax make the code more readable and easier to understand.

When code is consistent, developers can easily identify patterns and understand how the code works, which makes it easier to debug, maintain, and update the codebase over time. Consistency also helps to reduce errors, as it ensures that all developers are following the same standards and conventions.

Some of the things we should think about regarding format and syntax are:

Indentation and spacing

// bad indentation and spacing
const myFunc=(number1,number2)=>{
const result=number1+number2;
return result;
}

// good indentation and spacing
const myFunc = (number1, number2) => {
    const result = number1 + number2
    return result
}

Here we have an example of a same function, one done with no indentation and spacing, and the other properly spaced and indented. We can see that the second one is clearly easier to read.

Consistent syntax

// Arrow function, no colons, no return
const multiplyByTwo = number => number * 2

// Function, colons, return
function multiplyByThree(number) {
    return number * 3;
}

Again, here we have very similar functions implemented with different syntax. The first one is an arrow function, with no colons and no return, while the other is a common function that uses colons and a return.

Both work and are just fine, but we should aim to always use the same syntax for similar operations, as it becomes more even and readable along the codebase.

Linterns and code formatters are great tools we can use in our projects to automatize the syntax and formatting conventions in our codebase. If you're not familiar with this tools, check out this other article of mine.

Consistent case conventions

// camelCase
const myName = 'John'
// PascalCase
const MyName = 'John'
// snake_case
const my_name = 'John'

Same goes for the case convention we choose to follow. All of these work, but we should aim to consistently use the same one all through our project.

Naming

Naming variables and functions clearly and descriptively is an important aspect of writing clean code. It helps to improve the readability and maintainability of the codebase. When names are well-chosen, other developers can quickly understand what the variable or function is doing, and how it is related to the rest of the code.

Here are two examples in JavaScript that demonstrate the importance of clear and descriptive naming:

// Example 1: Poor Naming
function ab(a, b) {
  let x = 10;
  let y = a + b + x;
  console.log(y);
}

ab(5, 3);

In this example, we have a function that takes two parameters, adds them to a hardcoded value of 10, and logs the result to the console. The function name and variable names are poorly chosen and don't give any indication of what the function does or what the variables represent.

// Example 1: Good Naming
function calculateTotalWithTax(basePrice, taxRate) {
  const BASE_TAX = 10;
  const totalWithTax = basePrice + (basePrice * (taxRate / 100)) + BASE_TAX;
  console.log(totalWithTax);
}

calculateTotalWithTax(50, 20);

In this example, we have a function that calculates the total price of a product including tax. The function name and variable names are well-chosen and give a clear indication of what the function does and what the variables represent.

This makes the code easier to read and understand, especially for other developers who may be working with the codebase in the future.

Conciseness vs Clarity

When it comes to writing clean code, it's important to strike a balance between conciseness and clarity. While it's important to keep code concise to improve its readability and maintainability, it's equally important to ensure that the code is clear and easy to understand. Writing overly concise code can lead to confusion and errors, and can make the code difficult to work with for other developers.

Here are two examples that demonstrate the importance of conciseness and clarity:

// Example 1: Concise function
const countVowels = s => (s.match(/[aeiou]/gi) || []).length;
console.log(countVowels("hello world"));

This example uses a concise arrow function and regex to count the number of vowels in a given string. While the code is very short and easy to write, it may not be immediately clear to other developers how the regex pattern works, especially if they are not familiar with regex syntax.

// Example 2: More verbose and clearer function
function countVowels(s) {
  const vowelRegex = /[aeiou]/gi;
  const matches = s.match(vowelRegex) || [];
  return matches.length;
}

console.log(countVowels("hello world"));

This example uses a traditional function and regex to count the number of vowels in a given string, but does so in a way that is clear and easy to understand. The function name and variable names are descriptive, and the regex pattern is stored in a variable with a clear name. This makes it easy to see what the function is doing and how it works.

It's important to strike a balance between conciseness and clarity when writing code. While concise code can improve readability and maintainability, it's important to ensure that the code is still clear and easy to understand for other developers who may be working with the codebase in the future.

By using descriptive function and variable names, and making use of clear and readable code formatting and comments, it's possible to write clean and concise code that is easy to understand and work with.

Reusability

Code reusability is a fundamental concept in software engineering that refers to the ability of code to be used multiple times without modification.

The importance of code reusability lies in the fact that it can greatly improve the efficiency and productivity of software development by reducing the amount of code that needs to be written and tested.

By reusing existing code, developers can save time and effort, improve code quality and consistency, and minimize the risk of introducing bugs and errors. Reusable code also allows for more modular and scalable software architectures, making it easier to maintain and update codebases over time.

// Example 1: No re-usability
function calculateCircleArea(radius) {
  const PI = 3.14;
  return PI * radius * radius;
}

function calculateRectangleArea(length, width) {
  return length * width;
}

function calculateTriangleArea(base, height) {
  return (base * height) / 2;
}

const circleArea = calculateCircleArea(5);
const rectangleArea = calculateRectangleArea(4, 6);
const triangleArea = calculateTriangleArea(3, 7);

console.log(circleArea, rectangleArea, triangleArea);

This example defines three functions that calculate the area of a circle, rectangle, and triangle, respectively. Each function performs a specific task, but none of them are reusable for other similar tasks.

Additionally, the use of a hard-coded PI value can lead to errors if the value needs to be changed in the future. The code is inefficient since it repeats the same logic multiple times.

// Example 2: Implementing re-usability
function calculateArea(shape, ...args) {
  if (shape === 'circle') {
    const [radius] = args;
    const PI = 3.14;
    return PI * radius * radius;
  } else if (shape === 'rectangle') {
    const [length, width] = args;
    return length * width;
  } else if (shape === 'triangle') {
    const [base, height] = args;
    return (base * height) / 2;
  } else {
    throw new Error(`Shape "${shape}" not supported.`);
  }
}

const circleArea = calculateArea('circle', 5);
const rectangleArea = calculateArea('rectangle', 4, 6);
const triangleArea = calculateArea('triangle', 3, 7);

console.log(circleArea, rectangleArea, triangleArea);

This example defines a single function calculateArea that takes a shape argument and a variable number of arguments. Based on the shape argument, the function performs the appropriate calculation and returns the result.

This approach is much more efficient since it eliminates the need to repeat code for similar tasks. It is also more flexible and extensible, as additional shapes can easily be added in the future.

Clear Flow of Execution

Having a clear flow of execution is essential for writing clean code because it makes the code easier to read, understand, and maintain. Code that follows a clear and logical structure is less prone to errors, easier to modify and extend, and more efficient in terms of time and resources.

On the other hand, spaghetti code is a term used to describe code that is convoluted and difficult to follow, often characterized by long, tangled, and unorganized code blocks. Spaghetti code can be a result of poor design decisions, excessive coupling, or lack of proper documentation and commenting.

Here are two examples of JavaScript code that perform the same task, one with a clear flow of execution, and the other with spaghetti code:

// Example 1: Clear flow of execution
function calculateDiscount(price, discountPercentage) {
  const discountAmount = price * (discountPercentage / 100);
  const discountedPrice = price - discountAmount;
  return discountedPrice;
}

const originalPrice = 100;
const discountPercentage = 20;
const finalPrice = calculateDiscount(originalPrice, discountPercentage);

console.log(finalPrice);

// Example 2: Spaghetti code
const originalPrice = 100;
const discountPercentage = 20;

let discountedPrice;
let discountAmount;
if (originalPrice && discountPercentage) {
  discountAmount = originalPrice * (discountPercentage / 100);
  discountedPrice = originalPrice - discountAmount;
}

if (discountedPrice) {
  console.log(discountedPrice);
}

As we can see, example 1 follows a clear and logical structure, with a function that takes in the necessary parameters and returns the calculated result. On the other hand, example 2 is much more convoluted, with variables declared outside of any function and multiple if statements used to check if the code block has executed successfully.

Single Responsibility Principle

The Single Responsibility Principle (SRP) is a principle in software development that states that each class or module should have only one reason to change, or in other words, each entity in our codebase should have a single responsibility.

This principle helps to create code that is easy to understand, maintain, and extend.

By applying SRP, we can create code that is easier to test, reuse, and refactor, since each module only handles a single responsibility. This makes it less likely to have side effects or dependencies that can make the code harder to work with.

// Example 1: Withouth SRP
function processOrder(order) {
  // validate order
  if (order.items.length === 0) {
    console.log("Error: Order has no items");
    return;
  }

  // calculate total
  let total = 0;
  order.items.forEach(item => {
    total += item.price * item.quantity;
  });

  // apply discounts
  if (order.customer === "vip") {
    total *= 0.9;
  }

  // save order
  const db = new Database();
  db.connect();
  db.saveOrder(order, total);
}

In this example, the processOrder function handles several responsibilities: it validates the order, calculates the total, applies discounts, and saves the order to a database. This makes the function long and hard to understand, and any changes to one responsibility may affect the others, making it harder to maintain.

// Example 2: With SRP
class OrderProcessor {
  constructor(order) {
    this.order = order;
  }

  validate() {
    if (this.order.items.length === 0) {
      console.log("Error: Order has no items");
      return false;
    }
    return true;
  }

  calculateTotal() {
    let total = 0;
    this.order.items.forEach(item => {
      total += item.price * item.quantity;
    });
    return total;
  }

  applyDiscounts(total) {
    if (this.order.customer === "vip") {
      total *= 0.9;
    }
    return total;
  }
}

class OrderSaver {
  constructor(order, total) {
    this.order = order;
    this.total = total;
  }

  save() {
    const db = new Database();
    db.connect();
    db.saveOrder(this.order, this.total);
  }
}

const order = new Order();
const processor = new OrderProcessor(order);

if (processor.validate()) {
  const total = processor.calculateTotal();
  const totalWithDiscounts = processor.applyDiscounts(total);
  const saver = new OrderSaver(order, totalWithDiscounts);
  saver.save();
}

In this example, the processOrder function has been split into two classes that follow the SRP: OrderProcessor and OrderSaver.

The OrderProcessor class handles the responsibilities of validating the order, calculating the total, and applying discounts, while the OrderSaver class handles the responsibility of saving the order to the database.

This makes the code easier to understand, test, and maintain, since each class has a clear responsibility and can be modified or replaced without affecting the others.

Having a "Single Source of Truth"

Having a "single source of truth" means that there is only one place where a particular piece of data or configuration is stored in the codebase, and any other references to it in the code refer back to that one source. This is important because it ensures that the data is consistent and avoids duplication and inconsistency.

Here's an example to illustrate the concept. Let's say we have an application that needs to display the current weather conditions in a city. We could implement this feature in two different ways:

// Option 1: No "single source of truth"

// file 1: weatherAPI.js
const apiKey = '12345abcde';

function getCurrentWeather(city) {
  return fetch(`https://api.weather.com/conditions/v1/${city}?apiKey=${apiKey}`)
    .then(response => response.json());
}

// file 2: weatherComponent.js
const apiKey = '12345abcde';

function displayCurrentWeather(city) {
  getCurrentWeather(city)
    .then(weatherData => {
      // display weatherData on the UI
    });
}

In this option, the API key is duplicated in two different files, making it harder to maintain and update. If we ever need to change the API key, we have to remember to update it in both places.

// Option 2: "Single source of truth"

// file 1: weatherAPI.js
const apiKey = '12345abcde';

function getCurrentWeather(city) {
  return fetch(`https://api.weather.com/conditions/v1/${city}?apiKey=${apiKey}`)
    .then(response => response.json());
}

export { getCurrentWeather, apiKey };


// file 2: weatherComponent.js
import { getCurrentWeather } from './weatherAPI';

function displayCurrentWeather(city) {
  getCurrentWeather(city)
    .then(weatherData => {
      // display weatherData on the UI
    });
}

In this option, the API key is stored in one place (in the weatherAPI.js file) and exported for other modules to use. This ensures that there is only one source of truth for the API key and avoids duplication and inconsistency.

If we ever need to update the API key, we can do it in one place and all other modules that use it will automatically get the updated value.

Only Expose and Consume Data You Need

One important principle of writing clean code is to only expose and consume the information that is necessary for a particular task. This helps to reduce complexity, increase efficiency, and avoid errors that can arise from using unnecessary data.

When data that is not needed is exposed or consumed, it can lead to performance issues and make the code more difficult to understand and maintain.

Suppose you have an object with multiple properties, but you only need to use a few of them. One way to do this would be to reference the object and the specific properties every time you need them. But this can become verbose and error-prone, especially if the object is deeply nested. A cleaner and more efficient solution would be to use object destructuring to only expose and consume the information you need.

// Original object
const user = {
  id: 1,
  name: 'Alice',
  email: 'alice@example.com',
  age: 25,
  address: {
    street: '123 Main St',
    city: 'Anytown',
    state: 'CA',
    zip: '12345'
  }
};

// Only expose and consume the name and email properties
const { name, email } = user;

console.log(name); // 'Alice'
console.log(email); // 'alice@example.com'

Modularization

Modularization is an essential concept in writing clean code. It refers to the practice of breaking down large, complex code into smaller, more manageable modules or functions. This makes the code easier to understand, test, and maintain.

Using modularization provides several benefits such as:

Re-usability: Modules can be reused in different parts of the application or in other applications, saving time and effort in development.
Encapsulation: Modules allow you to hide the internal details of a function or object, exposing only the essential interface to the outside world. This helps to reduce coupling between different parts of the code and improve overall code quality.
Scalability: By breaking down large code into smaller, modular pieces, you can easily add or remove functionality without affecting the entire codebase.

Here is an example in JavaScript of a piece of code that performs a simple task, one not using modularization and the other implementing modularization.

// Without modularization
function calculatePrice(quantity, price, tax) {
  let subtotal = quantity * price;
  let total = subtotal + (subtotal * tax);
  return total;
}

// Without modularization
let quantity = parseInt(prompt("Enter quantity: "));
let price = parseFloat(prompt("Enter price: "));
let tax = parseFloat(prompt("Enter tax rate: "));

let total = calculatePrice(quantity, price, tax);
console.log("Total: $" + total.toFixed(2));

In the above example, the calculatePrice function is used to calculate the total price of an item given its quantity, price, and tax rate. However, this function is not modularized and is tightly coupled with the user input and output logic. This can make it difficult to test and maintain.

Now, let's see an example of the same code using modularization:

// With modularization
function calculateSubtotal(quantity, price) {
  return quantity * price;
}

function calculateTotal(subtotal, tax) {
  return subtotal + (subtotal * tax);
}

// With modularization
let quantity = parseInt(prompt("Enter quantity: "));
let price = parseFloat(prompt("Enter price: "));
let tax = parseFloat(prompt("Enter tax rate: "));

let subtotal = calculateSubtotal(quantity, price);
let total = calculateTotal(subtotal, tax);
console.log("Total: $" + total.toFixed(2));

In the above example, the calculatePrice function has been broken down into two smaller functions: calculateSubtotal and calculateTotal. These functions are now modularized and are responsible for calculating the subtotal and total, respectively. This makes the code easier to understand, test, and maintain, and also makes it more reusable in other parts of the application.

Modularization can also refer to the practice of dividing single files of code into many smaller files that are later on compiled back on to a single (or fewer files). This practice has the same benefits we just talked about.

If you'd like to know how to implement this in JavaScript using modules, check out this other article of mine.

Folder Structures

Choosing a good folder structure is an essential part of writing clean code. A well-organized project structure helps developers find and modify code easily, reduces code complexity, and improves project scalability and maintainability.

On the other hand, a poor folder structure can make it challenging to understand the project's architecture, navigate the codebase, and lead to confusion and errors.

Here are examples of a good and a bad folder structure using a React project as an example:

// Bad folder structure
my-app/
├── App.js
├── index.js
├── components/
│   ├── Button.js
│   ├── Card.js
│   └── Navbar.js
├── containers/
│   ├── Home.js
│   ├── Login.js
│   └── Profile.js
├── pages/
│   ├── Home.js
│   ├── Login.js
│   └── Profile.js
└── utilities/
    ├── api.js
    └── helpers.js

In this example, the project structure is organized around file types, such as components, containers, and pages.

But this approach can lead to confusion and duplication, as it's not clear which files belong where. For example, the Home component is present in both the containers and pages folders. It can also make it challenging to find and modify code, as developers may need to navigate multiple folders to find the code they need.

// Good folder structure
my-app/
├── src/
│   ├── components/
│   │   ├── Button/
│   │   │   ├── Button.js
│   │   │   ├── Button.module.css
│   │   │   └── index.js
│   │   ├── Card/
│   │   │   ├── Card.js
│   │   │   ├── Card.module.css
│   │   │   └── index.js
│   │   └── Navbar/
│   │       ├── Navbar.js
│   │       ├── Navbar.module.css
│   │       └── index.js
│   ├── pages/
│   │   ├── Home/
│   │   │   ├── Home.js
│   │   │   ├── Home.module.css
│   │   │   └── index.js
│   │   ├── Login/
│   │   │   ├── Login.js
│   │   │   ├── Login.module.css
│   │   │   └── index.js
│   │   └── Profile/
│   │       ├── Profile.js
│   │       ├── Profile.module.css
│   │       └── index.js
│   ├── utils/
│   │   ├── api.js
│   │   └── helpers.js
│   ├── App.js
│   └── index.js
└── public/
    ├── index.html
    └── favicon.ico

In this example, the project structure is organized around features, such as components, pages, and utils. Each feature has its own folder, which contains all the files related to that feature.

This approach makes it easy to find and modify code, as all the files related to a feature are located in the same folder. It also reduces code duplication and complexity, as features are separated, and their related files are organized together.

Overall, a good folder structure should be organized around features, not file types, and should make it easy to find and modify code. A clear and logical structure can make a project easier to maintain, understand and scale, while a confusing and inconsistent structure can lead to errors and confusion.

If you're interested in learning more about this, in this article I wrote about software architecture I expanded upon the topic of folder structures and well-known patterns you can follow.

Documentation

Documentation is an essential part of writing clean code. Proper documentation not only helps the developer who wrote the code understand it better in the future but also makes it easier for other developers to read and understand the codebase. When code is well-documented, it can save time and effort in debugging and maintaining the code.

Documenting is specially important in cases in which simple and easy to understand solutions can't be implemented, cases when the business logic is quite complex, and cases in which people who are not familiar with the codebase have to interact with it.

One way to document code is by using comments. Comments can provide context and explain what the code is doing. But it's important to use comments wisely, only commenting where necessary and avoiding redundant or unnecessary ones.

Another way to document code is by using inline documentation. Inline documentation is embedded in the code itself and can be used to explain what a specific function or piece of code does. Inline documentation is often used in combination with tools like JSDoc, which provides a standard for documenting code in JavaScript.

Tools like Typescript can also provide automatic documentation for our codebase, which is hugely helpful.

If you'd like to know more about Typescript, I wrote a beginner friendly guide a while ago.

And Lastly, tools like Swagger and Postman can be used to document APIs, providing a way to easily understand how to interact with them

If you're interested in knowing how to fully implement, test, consume and document APIs, I recently wrote two guides for REST APIs and GraphQL APIs.

Wrapping Up

Well everyone, as always, I hope you enjoyed the article and learned something new.

If you want, you can also follow me on LinkedIn or Twitter. See you in the next one!

The GraphQL API Handbook – How to Build, Test, Consume and Document GraphQL APIs

German Cocca — Tue, 02 May 2023 13:23:30 +0000

Hi everyone! In this tutorial we're going to take a deep dive into GraphQL APIs.

I recently wrote this article where I explained the main differences between common API types nowadays. And this tutorial aims to show you an example of how you can fully implement a GraphQL API.

We'll cover basic setup and architecture with Node and Apollo GraphQL, unit testing with Supertest, seeing how we can consume the API from a React front-end app using Apollo client and finally documenting the API using Apollo sandbox.

Keep in mind we won't go too deep into how each technology works. The goal here is to give you a general overview of how a GraphQL API works, how its pieces interact, and what a full implementation might consist of.

Let's go!

What is GraphQL?
Core GraphQL concepts
How to Build a GraphQL API with Node and Apollo GraphQL
How to Test a GraphQL API with Supertest
How to Consume a GraphQL API on a Front-end React App
How to Document a GraphQL API with Apollo sandbox
Wrapping up

What is GraphQL?

GraphQL is a query language and runtime for APIs that was developed by Facebook in 2012. It was released to the public in 2015 and has since gained popularity as an alternative to REST APIs.

GraphQL was originally developed by Facebook as a way to simplify data fetching for their mobile applications. They needed a way to make complex data requests from the server without causing performance issues or over-fetching data. GraphQL was born out of the need to solve these problems.

GraphQL was released as an open-source project in 2015 and has since gained popularity in the developer community. It is now supported by many development tools and frameworks, including Apollo, Prisma, and Hasura.

Main Characteristics:

Strongly Typed: GraphQL APIs are strongly typed, which means that each field has a specific data type. This makes it easier to validate and handle data on the client and server sides.
Query Language: GraphQL has its own query language that allows clients to specify exactly what data they need. This reduces over-fetching of data and improves performance.
Single Endpoint: GraphQL APIs have a single endpoint, which means that clients can fetch all the data they need from a single request.
Declarative: GraphQL APIs are declarative, which means that clients specify what they want, not how to get it. This allows for more efficient and flexible data fetching.
Schema-Driven: GraphQL APIs are schema-driven, which means that the schema defines the structure of the data and the available queries and mutations. This makes it easier for developers to understand and work with the API.

Pros:

Efficient Data Fetching: GraphQL APIs allow clients to fetch only the data they need, reducing over-fetching and improving performance.
Strongly Typed: GraphQL APIs are strongly typed, making it easier to validate and handle data.
Single Endpoint: GraphQL APIs have a single endpoint, reducing the complexity of the API and making it easier to work with.
Schema-Driven: GraphQL APIs are schema-driven, which makes it easier for developers to understand and work with the API.

Cons:

Complexity: GraphQL APIs can be more complex to set up and work with compared to REST APIs.
Caching: Caching can be more challenging with GraphQL APIs due to the flexible nature of the API.
Learning Curve: GraphQL requires a learning curve for both developers and clients, as it has its own query language and approach to data fetching.

Best for:

Efficient and flexible needs: GraphQL is well-suited for building applications that require efficient and flexible data fetching, such as mobile and web applications.
Complex data requirements: It is particularly useful in situations where there are complex data requirements and where over-fetching data can cause performance issues.

So to recap, GraphQL is a query language and runtime for APIs that provides efficient and flexible data fetching capabilities.

While it can be more complex to set up and work with compared to REST APIs, it offers benefits such as strongly typed data, single endpoints, and schema-driven development. It is well-suited for building applications with complex data requirements and where efficient data fetching is important.

Core GraphQL Concepts

Before we jump into building stuff, there are some core GraphQL concepts you need to understand in order to know what you're doing and how the code will work.

Object Types

In GraphQL, an Object Type is a complex type that represents a collection of fields. Object Types are used to define the structure of data that can be queried and mutated through a GraphQL API.

Each Object Type has a unique name and a set of fields, where each field has a name and a type. The type of a field can be a scalar type (such as Int, String, or Boolean), another Object Type, or a list of another type.

If you're familiar with Typescript and interfaces, this might ring a bell or two for you.

Here's an example of an Object Type that represents a "User" in a social media application:

type User {
  id: ID!
  name: String!
  email: String!
  friends: [User!]!
}

The ! sign means the field is mandatory.

In this example, the "User" Object Type has four fields: "id", "name", "email", and "friends". The "id" field has a type of ID, which is a built-in scalar type in GraphQL that represents a unique identifier. The "name" and "email" fields have a type of String, and the "friends" field has a type of a list of "User" Objects.

Here's another example of an Object Type that represents a "Book" in a library application:

type Book {
  id: ID!
  title: String!
  author: Author!
  genre: String!
  published: Int!
}

In this example, the "Book" Object Type has five fields: "id", "title", "author", "genre", and "published". The "id" field has a type of ID, the "title" and "genre" fields have a type of String, the "published" field has a type of Int, and the "author" field has a type of an "Author" Object.

Object Types can be used to define the structure of data that is returned from a query or mutation in a GraphQL API. For example, a query that returns a list of users might look like this:

query {
  users {
    id
    name
    email
    friends {
      id
      name
    }
  }
}

In this query, the "users" field returns a list of "User" Objects, and the query specifies which fields to include in the response.

Queries

In GraphQL, a query is a request for specific data from the server. The query specifies the shape of the data that the client wants to receive, and the server responds with the requested data in the same shape.

A query in GraphQL follows a similar structure to the shape of the data it expects to receive. It consists of a set of fields that correspond to the properties of the data the client wants to retrieve. Each field can also have arguments that modify the data returned.

Here's an example of a simple query in GraphQL:

query {
  user(id: "1") {
    name
    email
    age
  }
}

In this example, the query is requesting information about a user with the ID of "1". The fields specified in the query are "name", "email", and "age", which correspond to the properties of the user object.

The response from the server would be in the same shape as the query, with the requested data returned in the corresponding fields:

{
  "data": {
    "user": {
      "name": "John Doe",
      "email": "johndoe@example.com",
      "age": 25
    }
  }
}

Here, the server has returned the requested data about the user in the "name", "email", and "age" fields. The data is contained in a "data" object to differentiate it from any errors or other metadata that may be included in the response.

Mutations

In GraphQL, mutations are used to modify or create data on the server. Like queries, mutations specify the shape of the data being sent to and received from the server. The main difference is that while queries only read data, mutations can both read and write data.

Here's an example of a simple mutation in GraphQL:

mutation {
  createUser(name: "Jane Doe", email: "janedoe@example.com", age: 30) {
    id
    name
    email
    age
  }
}

In this example, the mutation is creating a new user on the server with the name "Jane Doe", email "janedoe@example.com", and age 30. The fields specified in the mutation are "id", "name", "email", and "age", which correspond to the properties of the user object.

The response from the server would be in the same shape as the mutation, with the newly created user data returned in the corresponding fields:

{
  "data": {
    "createUser": {
      "id": "123",
      "name": "Jane Doe",
      "email": "janedoe@example.com",
      "age": 30
    }
  }
}

Here, the server has returned the data about the newly created user in the "id", "name", "email", and "age" fields.

Mutations can also be used to update or delete data on the server. Here's an example of a mutation that updates a user's name:

mutation {
  updateUser(id: "123", name: "Jane Smith") {
    id
    name
    email
    age
  }
}

In this example, the mutation is updating the user with the ID of "123" to have the name "Jane Smith". The fields specified in the mutation are the same as in the previous example.

The response from the server would be the updated user data:

{
  "data": {
    "updateUser": {
      "id": "123",
      "name": "Jane Smith",
      "email": "janedoe@example.com",
      "age": 30
    }
  }
}

Mutations in GraphQL are designed to be composable, meaning that multiple mutations can be combined into a single request. This allows clients to perform complex operations with a single network round-trip.

Resolvers

In GraphQL, a resolver is a function responsible for fetching the data for a specific field defined in a GraphQL schema. Resolvers are the bridge between the schema and the data source. The resolver function receives four parameters: parent, args, context, and info.

parent: The parent object for the current field. In nested queries, it refers to the parent field's value.
args: The arguments passed to the current field. It is an object with key-value pairs of the argument names and their values.
context: An object shared across all resolvers for a particular request. It contains information about the request such as the currently authenticated user, database connection, etc.
info: Contains information about the query including the field name, alias, and the query document AST.

Here's an example of a resolver function for a User type's posts field:

const resolvers = {
  User: {
    posts: (parent, args, context, info) => {
      return getPostsByUserId(parent.id);
    },
  },
};

In this example, User is a GraphQL object type with a posts field. When the posts field is queried, the resolver function is called with the parent object User, any arguments passed, the context object, and query information. In this example, the resolver function calls a function getPostsByUserId to fetch the posts for the current user.

Resolvers can also be used for mutations to create, update or delete data. Here's an example of a resolver function for a createUser mutation:

const resolvers = {
  Mutation: {
    createUser: (parent, args, context, info) => {
      const user = { name: args.name, email: args.email };
      const createdUser = createUser(user);
      return createdUser;
    },
  },
};

In this example, Mutation is a GraphQL object type with a createUser mutation field. When the mutation is invoked, the resolver function is called with the parent object, arguments passed, context object, and query information. In this example, the resolver function calls a function createUser to create a new user with the given name and email, and returns the newly created user.

Schemas

In GraphQL, a schema is a blueprint that defines the structure of the data that can be queried in the API. It defines the available types, fields, and operations that can be performed on those types.

GraphQL schemas are written in the GraphQL Schema Definition Language (SDL), which uses a simple syntax to define the types and fields available in the API. The schema is typically defined in the server-side code and then used to validate and execute incoming queries.

Here's an example of a simple GraphQL schema definition:

type Book {
  id: ID!
  title: String!
  author: String!
  published: Int!
}

type Query {
  books: [Book!]!
  book(id: ID!): Book
}

type Mutation {
  addBook(title: String!, author: String!, published: Int!): Book!
  updateBook(id: ID!, title: String, author: String, published: Int): Book
  deleteBook(id: ID!): Book
}

In this schema, we have three types: Book, Query, and Mutation. The Book type has four fields: id, title, author, and published. The Query type has two fields: books and book, which can be used to retrieve a list of books or a specific book by ID, respectively. The Mutation type has three fields: addBook, updateBook, and deleteBook, which can be used to create, update, or delete books.

Note that each field has a type, which can be a built-in scalar type like String or Int, or a custom type like Book. The ! after a type indicates that the field is non-nullable, meaning it must always return a value (that is, it cannot be null).

TLDR and Comparison with Equivalent REST Concepts

Object Types: In GraphQL, Object Types are used to define the data that can be queried from an API, similar to how the response data model is defined in REST APIs. However, unlike REST, where data models are often defined in different formats (for example, JSON or XML), GraphQL Object Types are defined using a single language-agnostic syntax.
Queries: In GraphQL, queries are used to fetch data from an API, similar to HTTP GET requests in REST APIs. However, unlike REST APIs, where multiple requests may be required to fetch nested data, GraphQL queries can be used to fetch nested data in a single request.
Mutations: In GraphQL, mutations are used to modify data in an API, similar to HTTP POST, PUT, and DELETE requests in REST APIs. However, unlike REST APIs, where different endpoints may be required to perform different modifications, GraphQL mutations are performed through a single endpoint.
Resolvers: In GraphQL, resolvers are used to specify how to fetch data for a particular field in a query or mutation. Resolvers are similar to controller methods in REST APIs, which are used to fetch data from a database and return it as a response.
Schemas: In GraphQL, a schema is used to define the data that can be queried or mutated from an API. It specifies the types of data that can be requested, how they can be queried, and what mutations are allowed. In REST APIs, schemas are often defined using OpenAPI or Swagger, which specify the endpoints, request and response types, and other metadata for an API.

Overall, GraphQL and REST APIs differ in how they handle data fetching and modification.

REST APIs rely on multiple endpoints and HTTP methods to fetch and modify data, whereas GraphQL uses a single endpoint and queries/mutations to accomplish the same.

GraphQL's use of a single schema to define the data model of an API makes it easier to understand and maintain compared to REST APIs, which often require multiple documentation formats to describe the same data model.

How to Build a GraphQL API with Node and Apollo GraphQL

Our Tools

Node.js is an open-source, cross-platform, back-end JavaScript runtime environment that allows developers to execute JavaScript code outside of a web browser. It was created by Ryan Dahl in 2009 and has since become a popular choice for building web applications, APIs, and servers.

Node.js provides an event-driven, non-blocking I/O model that makes it lightweight and efficient, allowing it to handle large amounts of data with high performance. It also has a large and active community, with many libraries and modules available to help developers build their applications more quickly and easily.

Apollo GraphQL is a full-stack platform for building GraphQL APIs. It provides tools and libraries that simplify the process of building, managing, and consuming GraphQL APIs.

The core of the Apollo GraphQL platform is the Apollo Server, a lightweight and flexible server that makes it easy to build scalable and performant GraphQL APIs. The Apollo Server supports a wide range of data sources, including databases, REST APIs, and other services, making it easy to integrate with existing systems.

Apollo also provides a number of client libraries, including the Apollo Client for web and mobile, which simplifies the process of consuming GraphQL APIs. The Apollo Client makes it easy to query and mutate data, and provides advanced features like caching, optimistic UI, and real-time updates.

In addition to the Apollo Server and Apollo Client, Apollo provides a number of other tools and services, including a schema management platform, a GraphQL analytics service, and a set of developer tools for building and debugging GraphQL APIs.

If you're new to GraphQL or to Apollo itself, I really recommend you check out their docs. They're some of the best out there in my opinion.

Our Architecture

For this project we'll follow a layers architecture in our codebase. Layers architecture is about dividing concerns and responsibilities into different folders and files, and allowing direct communication only between certain folders and files.

The matter of how many layers should your project have, what names should each layer have, and what actions should it handle is all a matter of discussion. So let's see what I think is a good approach for our example.

Our application will have five different layers, which will be ordered in this way:

Application layers

The application layer will have the basic setup of our server and the connection to our schema and resolvers (the next layer).
The schema and resolvers layer will have the type definitions for our data and the connection to our queries and mutations (the next layer).
The queries and mutations layer will have the actual logic we want to perform in each of our queries and mutations and the connection to the model layer (the next layer, you get the idea...)
The model layer will hold the logic for interacting with our mock database.
Finally, the persistence layer is where our database will be.

An important thing to keep in mind is that in these kinds of architectures, there's a defined communication flow between the layers that has to be followed for it to make sense.

This means that a request first has to go through the first layer, then the second, then the third and so on. No request should skip layers because that would mess with the logic of the architecture and the benefits of organization and modularity it gives us.

If you'd like to know some other API architecture options, I recommend this software architecture article I wrote a while ago.

The Code

Before jumping to the code, let's mention what we'll actually build. We'll be building an API for a pet shelter business. This pet shelter needs to register the pets that are staying in the shelter, and for that we'll perform basic CRUD operations (create, read, update and delete).

We're using the exact same example we used in my article about fully implementing a REST API. If you're interested in reading that too, this should help to compare concepts between REST and GraphQL, and understand its differences and similarities. ;)

Now let's get this thing going. Create a new directory, hop in to it and start a new Node project by running npm init -y. For our GraphQL server we'll need two more dependencies, so run npm i @apollo/server and npm i graphql too.

App.js

In the root of your project, create an app.js file and drop this code in it:

import { ApolloServer } from '@apollo/server'
import { startStandaloneServer } from '@apollo/server/standalone'
import { typeDefs, resolvers } from './pets/index.js'

// The ApolloServer constructor requires two parameters: your schema
// definition and your set of resolvers.
const server = new ApolloServer({
    typeDefs,
    resolvers
})

// Passing an ApolloServer instance to the `startStandaloneServer` function:
//  1. creates an Express app
//  2. installs your ApolloServer instance as middleware
//  3. prepares your app to handle incoming requests
const { url } = await startStandaloneServer(server, {
    listen: { port: 4000 }
})

console.log(`🚀  Server ready at: ${url}`)

Here we're setting up our Apollo server, by passing it our typeDefs and resolvers (we'll explain those in a sec), and then starting the server in port 4000.

Next, go ahead and create this folder structure in your project:

Our folder structure

index.js

Within the index.js file put this code:

import { addPet, editPet, deletePet } from './mutations/pets.mutations.js'
import { listPets, getPet } from './queries/pets.queries.js'

// A schema is a collection of type definitions (hence "typeDefs")
// that together define the "shape" of queries that are executed against your data.
export const typeDefs = `#graphql
  # OBJECT TYPES
  # This "Pet" type defines the queryable fields for every pet in our data source.
  type Pet {
    id: ID!
    name: String!
    type: String!
    age: Int!
    breed: String!
  }

  # INPUT TYPES
  # Define the input objects for addPet and editPet mutations
  input PetToEdit {
    id: ID!
    name: String!
    type: String!
    age: Int!
    breed: String!
  }

  input PetToAdd {
    name: String!
    type: String!
    age: Int!
    breed: String!
  }

  # The "Query" type is special: it lists all of the available queries that
  # clients can execute, along with the return type for each. In this
  # case, the "pets" query returns an array of zero or more pets.
  # QUERY TYPES
  type Query {
    pets: [Pet],
    pet(id: ID!): Pet
  }

  # MUTATION TYPES
  type Mutation {
    addPet(petToAdd: PetToAdd!): Pet,
    editPet(petToEdit: PetToEdit!): Pet,
    deletePet(id: ID!): [Pet],
  }
`

export const resolvers = {
    // Resolvers for Queries
    Query: {
        pets: () => listPets(),
        pet: (_, { id }) => getPet(id)
    },

    // Resolvers for Mutations
    Mutation: {
        addPet: (_, { petToAdd }) => addPet(petToAdd),
        editPet: (_, { petToEdit }) => editPet(petToEdit),
        deletePet: (_, { id }) => deletePet(id)
    }
}

Here we have two main things: typeDefs and resolvers.

typeDefs defines the types for the data that can be queried in our API (in our case that's the pet object), as well as the input for queries/mutations (in our case that's PetToEdit and PetToAdd).

Lastly, it also defines the available queries and mutations for our API, declaring their names, as well as their input and return values. In our case we have two queries (pets and pet) and three mutations (addPet, editPet and deletePet).

resolvers contain the actual implementation of our queries and mutations types. Here we're declaring each query and mutation, and indicating what each should do. In our case, we're linking them with the queries/mutations we're importing from our queries/mutations layer.

pets.queries.js

In your pets.queries.js file drop this:

import { getItem, listItems } from '../models/pets.models.js'

export const getPet = id => {
    try {
        const resp = getItem(id)
        return resp
    } catch (err) {
        return err
    }
}

export const listPets = () => {
    try {
        const resp = listItems()
        return resp
    } catch (err) {
        return err
    }
}

As you can see, this file is very simple. It declares the functions that are imported in the index.js file and links them to the functions declared in the models layer.

pets.mutations.js

Same goes for our pets.mutations.js file, but with mutations now.

import { editItem, addItem, deleteItem } from '../models/pets.models.js'

export const addPet = petToAdd => {
    try {
        const resp = addItem(petToAdd)
        return resp
    } catch (err) {
        return err
    }
}

export const editPet = petToEdit => {
    try {
        const resp = editItem(petToEdit?.id, petToEdit)
        return resp
    } catch (err) {
        return err
    }
}

export const deletePet = id => {
    try {
        const resp = deleteItem(id)
        return resp
    } catch (err) {
        return err
    }
}

pets.models.js

Now go to the models folder and create a pets.models.js file with this code in it:

import db from '../../db/db.js'

export const getItem = id => {
    try {
        const pet = db?.pets?.filter(pet => pet?.id === parseInt(id))[0]
        return pet
    } catch (err) {
        console.error('Error', err)
        return err
    }
}

export const listItems = () => {
    try {
        return db?.pets
    } catch (err) {
        console.error('Error', err)
        return err
    }
}

export const editItem = (id, data) => {
    try {
        const index = db.pets.findIndex(pet => pet.id === parseInt(id))

        if (index === -1) throw new Error('Pet not found')
        else {
            data.id = parseInt(data.id)
            db.pets[index] = data
            return db.pets[index]
        }
    } catch (err) {
        console.error('Error', err)
        return err
    }
}

export const addItem = data => {
    try {
        const newPet = { id: db.pets.length + 1, ...data }
        db.pets.push(newPet)
        return newPet
    } catch (err) {
        console.error('Error', err)
        return err
    }
}

export const deleteItem = id => {
    try {
        // delete item from db
        const index = db.pets.findIndex(pet => pet.id === parseInt(id))

        if (index === -1) throw new Error('Pet not found')
        else {
            db.pets.splice(index, 1)
            return db.pets
        }
    } catch (err) {
        console.error('Error', err)
        return err
    }
}

These are the functions responsible for interacting with our data layer (database) and returning the corresponding information to our controllers.

Database

We wont use a real database for this example. Instead we'll just use a simple array that will work just fine for example purposes, though our data will of course reset every time our server does.

In the root of our project, create a db folder and a db.js file with this code in it:

const db = {
    pets: [
        {
            id: 1,
            name: 'Rex',
            type: 'dog',
            age: 3,
            breed: 'labrador',
        },
        {
            id: 2,
            name: 'Fido',
            type: 'dog',
            age: 1,
            breed: 'poodle',
        },
        {
            id: 3,
            name: 'Mittens',
            type: 'cat',
            age: 2,
            breed: 'tabby',
        },
    ]
}

export default db

As you can see, our db object contains a pets property whose value is an array of objects, each object being a pet. For each pet, we store an id, name, type, age and breed.

Now go to your terminal and run nodemon app.js. You should see this message confirming your server is alive: 🚀 Server ready at: [http://localhost:4000/](http://localhost:4000/).

How to Test a GraphQL API with Supertest

Now that our server is up and running, let's implement a simple test suit to check if our queries and mutations behave as expected.

If you're not familiar with automated testing, I recommend you read this introductory article I wrote a while ago.

Our Tools

SuperTest is a JavaScript library that is used for testing HTTP servers or web applications that make HTTP requests. It provides a high-level abstraction for testing HTTP, allowing developers to send HTTP requests and make assertions about the responses received, making it easier to write automated tests for web applications.

SuperTest works with any JavaScript testing framework, such as Mocha or Jest, and can be used with any HTTP server or web application framework, such as Express.

SuperTest is built on top of the popular testing library Mocha, and uses the Chai assertion library to make assertions about the responses received. It provides an easy-to-use API for making HTTP requests, including support for authentication, headers, and request bodies.

SuperTest also allows developers to test the entire request/response cycle, including middleware and error handling, making it a powerful tool for testing web applications.

Overall, SuperTest is a valuable tool for developers who want to write automated tests for their web applications. It helps ensure that their applications are functioning correctly and that any changes they make to the codebase do not introduce new bugs or issues.

The Code

First we'll need to install some dependencies. To save up terminal commands, go to your package.json file and replace your devDependencies section with the code below. Then run npm install.

  "devDependencies": {
    "@babel/core": "^7.21.4",
    "@babel/preset-env": "^7.21.4",
    "babel-jest": "^29.5.0",
    "jest": "^29.5.0",
    "jest-babel": "^1.0.1",
    "nodemon": "^2.0.22",
    "supertest": "^6.3.3"
  }

Here we're installing the supertest and jest libraries, which we need for our tests to run, plus some babel stuff we need for our project to correctly identify which files are test files.

Still in your package.json, add this script:

  "scripts": {
    "test": "jest"
  },

To end with the boilerplate, in the root of your project, create a babel.config.cjs file and drop this code in it:

//babel.config.cjs
module.exports = {
    presets: [
      [
        '@babel/preset-env',
        {
          targets: {
            node: 'current',
          },
        },
      ],
    ],
  };

Now let's write some actual tests! Within your pets folder, create a pets.test.js file with this code in it:

import request from 'supertest'

const graphQLEndpoint = 'http://localhost:4000/'

describe('Get all pets', () => {
    const postData = {
        query: `query Pets {
            pets {
                id
                name
                type
                age
                breed
            }
        }`
    }

    test('returns all pets', async () => {
        request(graphQLEndpoint)
            .post('?')
            .send(postData)
            .expect(200)
            .end((error, response) => {
                if (error) console.error(error)

                const res = JSON.parse(response.text)

                expect(res.data.pets).toEqual([
                    {
                        id: '1',
                        name: 'Rex',
                        type: 'dog',
                        age: 3,
                        breed: 'labrador'
                    },
                    {
                        id: '2',
                        name: 'Fido',
                        type: 'dog',
                        age: 1,
                        breed: 'poodle'
                    },
                    {
                        id: '3',
                        name: 'Mittens',
                        type: 'cat',
                        age: 2,
                        breed: 'tabby'
                    }
                ])
            })
    })
})

describe('Get pet detail', () => {
    const postData = {
        query: `query Pet {
            pet(id: 1) {
                id
                name
                type
                age
                breed
            }
        }`
    }

    test('Return pet detail information', async () => {
        request(graphQLEndpoint)
            .post('?')
            .send(postData)
            .expect(200)
            .end((error, response) => {
                if (error) console.error(error)

                const res = JSON.parse(response.text)

                expect(res.data.pet).toEqual({
                    id: '1',
                    name: 'Rex',
                    type: 'dog',
                    age: 3,
                    breed: 'labrador'
                })
            })
    })
})

describe('Edit pet', () => {
    const postData = {
        query: `mutation EditPet($petToEdit: PetToEdit!) {
            editPet(petToEdit: $petToEdit) {
                id
                name
                type
                age
                breed
            }
        }`,
        variables: {
            petToEdit: {
                id: 1,
                name: 'Rexo',
                type: 'dogo',
                age: 4,
                breed: 'doberman'
            }
        }
    }

    test('Updates pet and returns it', async () => {
        request(graphQLEndpoint)
            .post('?')
            .send(postData)
            .expect(200)
            .end((error, response) => {
                if (error) console.error(error)

                const res = JSON.parse(response.text)

                expect(res.data.editPet).toEqual({
                    id: '1',
                    name: 'Rexo',
                    type: 'dogo',
                    age: 4,
                    breed: 'doberman'
                })
            })
    })
})

describe('Add pet', () => {
    const postData = {
        query: `mutation AddPet($petToAdd: PetToAdd!) {
            addPet(petToAdd: $petToAdd) {
                id
                name
                type
                age
                breed
            }
        }`,
        variables: {
            petToAdd: {
                name: 'Salame',
                type: 'cat',
                age: 6,
                breed: 'pinky'
            }
        }
    }

    test('Adds new pet and returns the added item', async () => {
        request(graphQLEndpoint)
            .post('?')
            .send(postData)
            .expect(200)
            .end((error, response) => {
                if (error) console.error(error)

                const res = JSON.parse(response.text)

                expect(res.data.addPet).toEqual({
                    id: '4',
                    name: 'Salame',
                    type: 'cat',
                    age: 6,
                    breed: 'pinky'
                })
            })
    })
})

describe('Delete pet', () => {
    const postData = {
        query: `mutation DeletePet {
            deletePet(id: 2) {
                id,
                name,
                type,
                age,
                breed
            }
        }`
    }

    test('Deletes given pet and returns updated list', async () => {
        request(graphQLEndpoint)
            .post('?')
            .send(postData)
            .expect(200)
            .end((error, response) => {
                if (error) console.error(error)

                const res = JSON.parse(response.text)

                expect(res.data.deletePet).toEqual([
                    {
                        id: '1',
                        name: 'Rexo',
                        type: 'dogo',
                        age: 4,
                        breed: 'doberman'
                    },
                    {
                        id: '3',
                        name: 'Mittens',
                        type: 'cat',
                        age: 2,
                        breed: 'tabby'
                    },
                    {
                        id: '4',
                        name: 'Salame',
                        type: 'cat',
                        age: 6,
                        breed: 'pinky'
                    }
                ])
            })
    })
})

This a test suite for our GraphQL API. It uses the supertest library to make HTTP requests to the API endpoint (http://localhost:4000/) and verifies that the API responds correctly to various queries and mutations.

The code has five different test cases:

Get all pets: This test queries the API for all pets and verifies that the response matches an expected list of pets.
Get pet detail: This test queries the API for the details of a specific pet and verifies that the response matches the expected details for that pet.
Edit pet: This test performs a mutation to edit the details of a specific pet and verifies that the response matches the expected edited details for that pet.
Add pet: This test performs a mutation to add a new pet and verifies that the response matches the expected details for the newly added pet.
Delete pet: This test performs a mutation to delete a specific pet and verifies that the response matches the expected list of pets after the deletion.

Each test case includes a postData object that contains the GraphQL query or mutation to be sent to the API endpoint as well as any necessary variables.

The actual HTTP request is made using the request function from the supertest library, which sends a POST request to the API endpoint with the postData object in the request body. The response is then parsed as JSON and the test case verifies that the response matches the expected result using the expect function from the Jest testing framework.

Now go to your terminal, run npm test, and you should see all your tests passing:

> jest

 PASS  pets/pets.test.js
  Get all pets
    ✓ returns all pets (15 ms)
  Get pet detail
    ✓ Return pet detail information (2 ms)
  Edit pet
    ✓ Updates pet and returns it (1 ms)
  Add pet
    ✓ Adds new pet and returns the added item (1 ms)
  Delete pet
    ✓ Deletes given pet and returns updated list (1 ms)

Test Suites: 1 passed, 1 total
Tests:       5 passed, 5 total
Snapshots:   0 total
Time:        0.607 s, estimated 1 s
Ran all test suites.

How to Consume a GraphQL API on a Front-end React App

Now we know our server is running and behaving as expected. Let's see some more realistic example of how our API might be consumed by a front end app.

For this example, we'll use a React application, and Apollo client to send and process our requests.

Our Tools

React is a popular JavaScript library for building user interfaces. It allows developers to create reusable UI components and efficiently update and render them in response to changes in application state.

Regarding Apollo client, we've introduced it already.

Side comment – we're using Apollo client here since it's a very popular tool and it makes sense to use the same set of libraries both in front and back-end. If you're interested in other possible ways a GraphQL API can be consumed from a front-end React App, Reed Barger has a pretty cool article on this topic.

The Code

Let's create our React app by running yarn create vite and following the terminal prompts. Once that's done, run yarn add react-router-dom (which we'll use to setup basic routing in our app).

App.jsx

Put this code within your App.jsx file:

import { Suspense, lazy, useState } from 'react'
import { BrowserRouter as Router, Routes, Route } from 'react-router-dom'
import './App.css'

const PetList = lazy(() => import('./pages/PetList'))
const PetDetail = lazy(() => import('./pages/PetDetail'))
const EditPet = lazy(() => import('./pages/EditPet'))
const AddPet = lazy(() => import('./pages/AddPet'))

function App() {
    const [petToEdit, setPetToEdit] = useState(null)

    return (
        <div className='App'>
            <Router>
                <h1>Pet shelterh1>

                <Routes>
                    <Route
                        path='/'
                        element={
                            <Suspense fallback={<>}>
                                <PetList />
                            Suspense>
                        }
                    />

                    <Route
                        path='/:petId'
                        element={
                            <Suspense fallback={<>}>
                                <PetDetail setPetToEdit={setPetToEdit} />
                            Suspense>
                        }
                    />

                    <Route
                        path='/:petId/edit'
                        element={
                            <Suspense fallback={<>}>
                                <EditPet petToEdit={petToEdit} />
                            Suspense>
                        }
                    />

                    <Route
                        path='/add'
                        element={
                            <Suspense fallback={<>}>
                                <AddPet />
                            Suspense>
                        }
                    />
                
            
        
    )
}

export default App

Here we're just defining our routes. We'll have 4 main routes in our app, each corresponding to a different view:

One to see the whole list of pets.
One to see the detail of a single pet.
One to edit a single pet.
One to add a new pet to the list.

Besides, we have a button to add a new pet and a state that will store the information of the pet we want to edit.

Next, create a pages directory with these files in it:

Folder structure

main.js

Before jumping into our pages, we have to set up the Apollo client library. Run yarn add @apollo/client and yarn add graphql to install the necessary dependencies.

The go to the main.js file and drop this code in it:

import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App'
import './index.css'
import { ApolloClient, InMemoryCache, ApolloProvider } from '@apollo/client'

const client = new ApolloClient({
  uri: 'http://localhost:4000/',
  cache: new InMemoryCache(),
})

ReactDOM.createRoot(document.getElementById('root')).render(
  <ApolloProvider client={client}>
    <App />
  ApolloProvider>
)

Here we're initializing the ApolloClient, passing its constructor a configuration object with the uri and cache fields:

uri specifies the URL of our GraphQL server.
cache is an instance of InMemoryCache, which Apollo Client uses to cache query results after fetching them.

Then we wrap our App component with our ApolloProvider. This allows any component in our component tree to use the hooks provided by Apollo client, much like React Context works. ;)

Mutations and queries

In the root of your project, create this folder structure:

Folder structure

In these two files we'll declare the request bodies we'll use for our queries and mutations. I like to separate this into different files because it gives use a clear view of the different kinds of request we have in our app, and it also keeps our component's code cleaner.

In the queries.js file drop this:

import { gql } from '@apollo/client'

export const GET_PETS = gql`
    query Pets {
        pets {
            id
            name
            type
            breed
        }
    }
`

export const GET_PET = gql`
    query Pet($petId: ID!) {
        pet(id: $petId) {
            id
            name
            type
            age
            breed
        }
    }
`

And in the mutations.js file drop this:

import { gql } from '@apollo/client'

export const DELETE_PET = gql`
    mutation DeletePet($deletePetId: ID!) {
        deletePet(id: $deletePetId) {
            id
        }
    }
`

export const ADD_PET = gql`
    mutation AddPet($petToAdd: PetToAdd!) {
        addPet(petToAdd: $petToAdd) {
            id
            name
            type
            age
            breed
        }
    }
`

export const EDIT_PET = gql`
    mutation EditPet($petToEdit: PetToEdit!) {
        editPet(petToEdit: $petToEdit) {
            id
            name
            type
            age
            breed
        }
    }
`

As you can see, the syntax for queries and mutations is fairly similar. Request bodies are written in GraphQL query language, which is used to define the structure and data types of data that can be requested from a GraphQL API.

GraphQL Query Syntax:

export const GET_PETS = gql`
    query Pets {
        pets {
            id
            name
            type
            breed
        }
    }
`

This query is named Pets and it requests data from the pets field. The fields id, name, type, and breed are requested from each Pet object returned by the API.

In GraphQL, queries always start with the keyword query and are followed by the name of the query, if provided. The fields requested are enclosed in curly braces and can be nested to request data from related fields.

GraphQL Mutation Syntax:

export const ADD_PET = gql`
    mutation AddPet($petToAdd: PetToAdd!) {
        addPet(petToAdd: $petToAdd) {
            id
            name
            type
            age
            breed
        }
    }
`

This mutation is named AddPet and sends a new Pet object to be added to the API via the addPet mutation. The $petToAdd variable is defined as a required input of type PetToAdd. When the mutation is executed, the input variable will be passed in as an argument to the addPet mutation. The mutation then returns the id, name, type, age, and breed fields for the newly created Pet object.

In GraphQL, mutations always start with the keyword mutation and are followed by the name of the mutation, if provided. The fields requested in the mutation response are also enclosed in curly braces.

Note that both queries and mutations in GraphQL can accept variables as input, which are defined in the query or mutation body using a special syntax ($variableName: variableType!). These variables can be passed in when the query or mutation is executed, allowing for more dynamic and reusable queries and mutations.

PetList.jsx

Let's start with the file responsible for rendering the whole list of pets:

import { Link } from 'react-router-dom'
import { useQuery } from '@apollo/client'
import { GET_PETS } from '../api/queries'

function PetList() {
    const { loading, error, data } = useQuery(GET_PETS)

    return (
        <>
            <h2>Pet Listh2>

            <Link to='/add'>
                <button>Add new petbutton>
            Link>

            {loading && <p>Loading...p>}
            {error && <p>Error: {error.message}p>}

            {data?.pets?.map(pet => {
                return (
                    <div key={pet?.id}>
                        <p>
                            {pet?.name} - {pet?.type} - {pet?.breed}
                        p>

                        <Link to={`/${pet?.id}`}>
                            <button>Pet detailbutton>
                        Link>
                    div>
                )
            })}
        
    )
}

export default PetList

This code defines a React functional component called PetList that fetches a list of pets from a GraphQL API using the useQuery hook provided by the @apollo/client library. The query used to fetch the pets is defined in a separate file called queries.js, which exports a GraphQL query called GET_PETS.

The useQuery hook returns an object with three properties: loading, error, and data. These properties are destructured from the object and used to conditionally render different UI elements depending on the status of the API request.

If loading is true, a loading message is displayed on the screen. If error is defined, an error message is displayed with the specific error message returned by the API. If data is defined and contains an array of pets, each pet is displayed in a div with their name, type, and breed. Each pet div also contains a link to view more details about the pet.

The useQuery hook works by executing the GET_PETS query and returning the result as an object with the loading, error, and data properties. When the component first renders, loading is true while the query is being executed. If the query is successful, loading is false and data is populated with the results. If the query encounters an error, error is populated with the specific error message.

As you can see, managing requests with Apollo client is really nice and simple. And the hooks it provides, save us quite a bit of code normally used to execute requests, store it's response and handle errors.

Remember that to make calls to our server, we must have it up and running by running nodemon app.js in our server project terminal.

Just to show there's no weird magic going on here, if we go to our browser, open the dev tools and go to the network tab, we could see our app is making a POST request to our server endpoint. And that the payload is our request body in the form of a string.

The POST request

Request body

This means that if we wanted to, we could also consume our GraphQL API by using fetch, like following:

import { Link } from 'react-router-dom'
import { useEffect, useState } from 'react'

function PetList() {

    const [pets, setPets] = useState([])

    const getPets = () => {
        fetch('http://localhost:4000/', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify({
                query: `
                query Pets {
                    pets {
                    id
                    name
                    type
                    breed
                    }
                }
                `
            })
        })
            .then(response => response.json())
            .then(data => setPets(data?.data?.pets))
            .catch(error => console.error(error))
    }

    useEffect(() => {
        getPets()
    }, [])

    return (
        <>
            <h2>Pet Listh2>

            <Link to='/add'>
                <button>Add new petbutton>
            Link>

            {pets?.map(pet => {
                return (
                    <div key={pet?.id}>
                        <p>
                            {pet?.name} - {pet?.type} - {pet?.breed}
                        p>

                        <Link to={`/${pet?.id}`}>
                            <button>Pet detailbutton>
                        Link>
                    div>
                )
            })}
        
    )
}

export default PetList

If you check your network tab again, you should see still the same POST request with the some request body.

Of course this approach is not very practical as it requires more lines of code to perform the same thing. But it's important to know that libraries like Apollo only give us a declarative API to work with and simplify our code. Beneath it all we're still working with regular HTTP requests.

PetDetail.jsx

Now let's go to the PetDetail.jsx file:

import { useEffect } from 'react'
import { useParams, Link } from 'react-router-dom'
import { useQuery, useMutation } from '@apollo/client'
import { GET_PET } from '../api/queries'
import { DELETE_PET } from '../api/mutations'

function PetDetail({ setPetToEdit }) {
    const { petId } = useParams()

    const { loading, error, data } = useQuery(GET_PET, {
        variables: { petId }
    })

    useEffect(() => {
        if (data && data?.pet) setPetToEdit(data?.pet)
    }, [data])

    const [deletePet, { loading: deleteLoading, error: deleteError, data: deleteData }] = useMutation(DELETE_PET, {
        variables: { deletePetId: petId }
    })

    useEffect(() => {
        if (deleteData && deleteData?.deletePet) window.location.href = '/'
    }, [deleteData])

    return (
        <div style={{ display: 'flex', flexDirection: 'column', justifyContent: 'center', aligniItems: 'center' }}>
            <h2>Pet Detailh2>

            <Link to='/'>
                <button>Back to listbutton>
            Link>

            {(loading || deleteLoading) && <p>Loading...p>}

            {error && <p>Error: {error.message}p>}
            {deleteError && <p>deleteError: {deleteError.message}p>}

            {data?.pet && (
                <>
                    <p>Pet name: {data?.pet?.name}p>
                    <p>Pet type: {data?.pet?.type}p>
                    <p>Pet age: {data?.pet?.age}p>
                    <p>Pet breed: {data?.pet?.breed}p>

                    <div style={{ display: 'flex', justifyContent: 'center', aligniItems: 'center' }}>
                        <Link to={`/${data?.pet?.id}/edit`}>
                            <button style={{ marginRight: 10 }}>Edit petbutton>
                        Link>

                        <button style={{ marginLeft: 10 }} onClick={() => deletePet()}>
                            Delete pet
                        button>
                    div>
                
            )}
        
    )
}

export default PetDetail

This component loads the detail info of the pet by executing a query in a very similar way than the previous component.

Moreover, it executes the mutation needed to delete the pet register. You can see that for this we're using the useMutation hook. It's quite similar to useQuery, but besides the loading, error and data values it also provides a function to execute our query after a given event.

You can see that for this mutation hook we're passing an object as second parameter, containing the variables this mutation requires. In this case, it's the id of the pet register we want to delete.

const [deletePet, { loading: deleteLoading, error: deleteError, data: deleteData }] = useMutation(DELETE_PET, {
    variables: { deletePetId: petId }
})

Remember that when we declared our mutation in mutations.js we had already declared the variables this mutation would use.

export const DELETE_PET = gql`
    mutation DeletePet($deletePetId: ID!) {
        deletePet(id: $deletePetId) {
            id
        }
    }
`

AddPet.jsx

This is the file responsible for adding a new pet to our register:

import React, { useState, useEffect } from 'react'
import { Link } from 'react-router-dom'
import { useMutation } from '@apollo/client'
import { ADD_PET } from '../api/mutations'

function AddPet() {
    const [petName, setPetName] = useState()
    const [petType, setPetType] = useState()
    const [petAge, setPetAge] = useState()
    const [petBreed, setPetBreed] = useState()

    const [addPet, { loading, error, data }] = useMutation(ADD_PET, {
        variables: {
            petToAdd: {
                name: petName,
                type: petType,
                age: parseInt(petAge),
                breed: petBreed
            }
        }
    })

    useEffect(() => {
        if (data && data?.addPet) window.location.href = `/${data?.addPet?.id}`
    }, [data])

    return (
        <div style={{ display: 'flex', flexDirection: 'column', justifyContent: 'center', aligniItems: 'center' }}>
            <h2>Add Peth2>

            <Link to='/'>
                <button>Back to listbutton>
            Link>

            {loading || error ? (
                <>
                    {loading && <p>Loading...p>}
                    {error && <p>Error: {error.message}p>}
                
            ) : (
                <>
                    <div style={{ display: 'flex', flexDirection: 'column', margin: 20 }}>
                        <label>Pet namelabel>
                        <input type='text' value={petName} onChange={e => setPetName(e.target.value)} />
                    div>

                    <div style={{ display: 'flex', flexDirection: 'column', margin: 20 }}>
                        <label>Pet typelabel>
                        <input type='text' value={petType} onChange={e => setPetType(e.target.value)} />
                    div>

                    <div style={{ display: 'flex', flexDirection: 'column', margin: 20 }}>
                        <label>Pet agelabel>
                        <input type='text' value={petAge} onChange={e => setPetAge(e.target.value)} />
                    div>

                    <div style={{ display: 'flex', flexDirection: 'column', margin: 20 }}>
                        <label>Pet breedlabel>
                        <input type='text' value={petBreed} onChange={e => setPetBreed(e.target.value)} />
                    div>

                    <button
                        style={{ marginTop: 30 }}
                        disabled={!petName || !petType || !petAge || !petBreed}
                        onClick={() => addPet()}
                    >
                        Add pet
                    button>
                
            )}
        
    )
}

export default AddPet

Here we have a component that loads a form to add a new pet and performs a mutation when the data is sent. It accepts the new pet info as parameter, in a similar way that the deletePet mutation accepted the pet id.

EditPet.jsx

Finally, the file responsible for editing a pet register:

import React, { useState, useEffect } from 'react'
import { Link } from 'react-router-dom'
import { useMutation } from '@apollo/client'
import { EDIT_PET } from '../api/mutations'

function EditPet({ petToEdit }) {
    const [petName, setPetName] = useState(petToEdit?.name)
    const [petType, setPetType] = useState(petToEdit?.type)
    const [petAge, setPetAge] = useState(petToEdit?.age)
    const [petBreed, setPetBreed] = useState(petToEdit?.breed)

    const [editPet, { loading, error, data }] = useMutation(EDIT_PET, {
        variables: {
            petToEdit: {
                id: parseInt(petToEdit.id),
                name: petName,
                type: petType,
                age: parseInt(petAge),
                breed: petBreed
            }
        }
    })

    useEffect(() => {
        if (data && data?.editPet?.id) window.location.href = `/${data?.editPet?.id}`
    }, [data])

    return (
        <div style={{ display: 'flex', flexDirection: 'column', justifyContent: 'center', aligniItems: 'center' }}>
            <h2>Edit Peth2>

            <Link to='/'>
                <button>Back to listbutton>
            Link>

            {loading || error ? (
                <>
                    {loading && <p>Loading...p>}
                    {error && <p>Error: {error.message}p>}
                
            ) : (
                <>
                    <div style={{ display: 'flex', flexDirection: 'column', margin: 20 }}>
                        <label>Pet namelabel>
                        <input type='text' value={petName} onChange={e => setPetName(e.target.value)} />
                    div>

                    <div style={{ display: 'flex', flexDirection: 'column', margin: 20 }}>
                        <label>Pet typelabel>
                        <input type='text' value={petType} onChange={e => setPetType(e.target.value)} />
                    div>

                    <div style={{ display: 'flex', flexDirection: 'column', margin: 20 }}>
                        <label>Pet agelabel>
                        <input type='text' value={petAge} onChange={e => setPetAge(e.target.value)} />
                    div>

                    <div style={{ display: 'flex', flexDirection: 'column', margin: 20 }}>
                        <label>Pet breedlabel>
                        <input type='text' value={petBreed} onChange={e => setPetBreed(e.target.value)} />
                    div>

                    <button
                        style={{ marginTop: 30 }}
                        disabled={!petName || !petType || !petAge || !petBreed}
                        onClick={() => editPet()}
                    >
                        Save changes
                    button>
                
            )}
        
    )
}

export default EditPet

Last, we have a component to edit a pet register through a form. It performs a mutation when the data is sent, and as parameters it accepts the new pet info.

And that's it! We're using all of our API queries and mutations in our front end app. =)

How to Document a GraphQL API with Apollo Sandbox

One of Apollo's coolest features is that it comes with a built-in sandbox you can use to test and document your API.

Apollo Sandbox is a web-based GraphQL IDE that provides a sandbox environment for testing GraphQL queries, mutations, and subscriptions. It is a free, online tool provided by Apollo that allows you to interact with your GraphQL API and explore its schema, data, and capabilities.

Here are some of the main features of Apollo Sandbox:

Query Editor: A feature-rich GraphQL query editor that provides syntax highlighting, autocompletion, validation, and error highlighting.
Schema Explorer: A graphical interface that allows you to explore your GraphQL schema and see its types, fields, and relationships.
Mocking: Apollo Sandbox allows you to easily generate mock data based on your schema, which is useful for testing your queries and mutations without connecting to a real data source.
Collaboration: You can share your sandbox with others, collaborate on queries, and see real-time changes.
Documentation: You can add documentation to your schema and query results to help others understand your API.

To use our sandbox, simply open your browser at http://localhost:4000/. You should see something like this:

Apollo sandbox

From here you can see the API data schema and available mutations and queries, and also execute them and see how your API responds. For example, by executing the pets query, we can see that response on the right side panel.

Executing a query

If you hop on to the schema section you could see a whole detail of the available queries, mutations object and input types in our API.

The schema section

Apollo sandbox is a great tool that can be used both as self-documentation for our API and a great development and testing tool.

Wrapping Up

Well everyone, as always, I hope you enjoyed the article and learned something new.

If you want, you can also follow me on LinkedIn or Twitter. See you in the next one!

The REST API Handbook – How to Build, Test, Consume, and Document REST APIs

German Cocca — Thu, 27 Apr 2023 13:55:17 +0000

Hi everyone! In this tutorial we're going to take a deep dive into REST APIs.

I recently wrote this article where I explained the main differences between common API types nowadays. And this tutorial aims to show you an example of how you can fully implement a REST API.

We'll cover basic setup and architecture with Node and Express, unit testing with Supertest, seeing how we can consume the API from a React front-end app and finally documenting the API using tools such as Swagger.

Keep in mind we won't go too deep into how each technology works. The goal here is to give you a general overview of how a REST API works, how its pieces interact, and what a full implementation might consist of.

Let's go!

What is REST?
How to Build a REST API with Node and Express
How to Test a REST API with Supertest
How to Consume a REST API on a Front-end React App
How to Document a REST API with Swagger
Wrapping up

What is REST?

Representational State Transfer (REST) is a widely used architectural style for building web services and APIs.

RESTful APIs are designed to be simple, scalable, and flexible. They are often used in web and mobile applications, as well as in Internet of Things (IoT) and microservices architectures.

Main Characteristics:

Stateless: REST APIs are stateless, which means that each request contains all the necessary information to process it. This makes it easier to scale the API and improves performance by reducing the need to store and manage session data on the server.
Resource-based: REST APIs are resource-based, which means that each resource is identified by a unique URI (Uniform Resource Identifier) and can be accessed using standard HTTP methods such as GET, POST, PUT, and DELETE.
Uniform Interface: REST APIs have a uniform interface that allows clients to interact with resources using a standardized set of methods and response formats. This makes it easier for developers to build and maintain APIs, and for clients to consume them.
Cacheable: REST APIs are cacheable, which means that responses can be cached to improve performance and reduce network traffic.
Layered System: REST APIs are designed to be layered, which means that intermediaries such as proxies and gateways can be added between the client and server without affecting the overall system.

Pros of REST APIs**:**

Easy to learn and use: REST APIs are relatively simple and easy to learn compared to other APIs.
Scalability: The stateless nature of REST APIs makes them highly scalable and efficient.
Flexibility: REST APIs are flexible and can be used to build a wide range of applications and systems.
Wide support: REST APIs are widely supported by development tools and frameworks, making it easy to integrate them into existing systems.

Cons of REST APIs**:**

Lack of standards: The lack of strict standards for REST APIs can lead to inconsistencies and interoperability issues.
Limited functionality: REST APIs are designed to handle simple requests and responses and may not be suitable for more complex use cases.
Security concerns: REST APIs can be vulnerable to security attacks such as cross-site scripting (XSS) and cross-site request forgery (CSRF) if not implemented properly.

REST APIs are best for:****

REST APIs are well-suited for building web and mobile applications, as well as microservices architectures and IoT systems.
They are particularly useful in situations where scalability and flexibility are important, and where developers need to integrate with existing systems and technologies.

In summary, REST APIs are a popular and widely used architectural style for building web services and APIs. They are simple, scalable, and flexible, and can be used to build a wide range of applications and systems.

While there are some limitations and concerns with REST APIs, they remain a popular and effective option for building APIs in many different industries and sectors.

How to Build a REST API with Node and Express

Our tools

Express.js is a popular web application framework for Node.js, which is used to build web applications and APIs. It provides a set of features and tools for building web servers, handling HTTP requests and responses, routing requests to specific handlers, handling middleware, and much more.

Express is known for its simplicity, flexibility, and scalability, making it a popular choice for developers building web applications with Node.js.

Some of the key features and benefits of Express.js include:

Minimalistic and flexible: Express.js provides a minimalistic and flexible structure that allows developers to build applications the way they want to.
Routing: Express.js makes it easy to define routes for handling HTTP requests and mapping them to specific functions or handlers.
Middleware: Express.js allows developers to define middleware functions that can be used to handle common tasks such as authentication, logging, error handling, and more.
Robust API: Express.js provides a robust API for handling HTTP requests and responses, allowing developers to build high-performance web applications.

Our architecture

Our application will have five different layers, which will be ordered in this way:

Application layers

The application layer will have the basic setup of our server and the connection to our routes (the next layer).
The routes layer will have the definition of all of our routes and the connection to the controllers (the next layer).
The controllers layer will have the actual logic we want to perform in each of our endpoints and the connection to the model layer (the next layer, you get the idea...)
The model layer will hold the logic for interacting with our mock database.
Finally, the persistence layer is where our database will be.

An important thing to keep in mind is that in these kinds of architectures, there's a defined communication flow between the layers that has to be followed for it to make sense.

If you'd like to know some other API architecture options, I recommend you this software architecture article I wrote a while ago.

The code

Now yeah, let's get this thing going. Create a new directory, hop on to it and start a new Node project by running npm init -y.

Then install Express by running npm i express and install nodemon as a dev dependency by running npm i -D nodemon (Nodemon is a tool we'll use to get our server running and test it). Lastly, also run npm i cors, which we'll use to be able to test our server locally.

App.js

Cool, now create an app.js file and drop this code in it:


import express from 'express'
import cors from 'cors'

import petRoutes from './pets/routes/pets.routes.js'

const app = express()
const port = 3000

/* Global middlewares */
app.use(cors())
app.use(express.json())

/* Routes */
app.use('/pets', petRoutes)

/* Server setup */
if (process.env.NODE_ENV !== 'test') {
    app.listen(port, () => console.log(`⚡️[server]: Server is running at https://localhost:${port}`))
}

export default app

This would be the application layer of our project.

Here we're basically setting up our server and declaring that any request that hits the /pets direction should use the routes (endpoints) we have declared in the ./pets/routes/pets.routes.js directory.

Next, go ahead and create this folder structure in your project:

Folder structure

Routes

Hop on to the routes folder, create a file called pets.routes.js, and drop this code in it:

import express from "express";
import {
  listPets,
  getPet,
  editPet,
  addPet,
  deletePet,
} from "../controllers/pets.controllers.js";

const router = express.Router();

router.get("/", listPets);

router.get("/:id", getPet);

router.put("/:id", editPet);

router.post("/", addPet);

router.delete("/:id", deletePet);

export default router;

In this file we're initializing a router (the thing that processes our request and directs them accordingly given the endpoint URL) and setting up each of our endpoints.

See that for each endpoint we declare the corresponding HTTP method (get, put, and so on) and the corresponding function that that endpoint will trigger (listPets, getPet, and so on). Each function name is quite explicit so we can easily know what each endpoint does without needing to see further code. ;)

Lastly, we also declare which endpoint will receive URL parameters on the requests like this: router.get("/:id", getPet); Here we're saying that we'll receive the id of the pet as an URL parameter.

Controllers

Now go to the controllers folder, create a pets.controllers.js file, and put this code in it:

import { getItem, listItems, editItem, addItem, deleteItem } from '../models/pets.models.js'

export const getPet = (req, res) => {
    try {
        const resp = getItem(parseInt(req.params.id))
        res.status(200).json(resp)

    } catch (err) {
        res.status(500).send(err)
    }
}

export const listPets = (req, res) => {
    try {
        const resp = listItems()
        res.status(200).json(resp)

    } catch (err) {
        res.status(500).send(err)
    }
}

export const editPet = (req, res) => {
    try {
        const resp = editItem(parseInt(req.params.id), req.body)
        res.status(200).json(resp)

    } catch (err) {
        res.status(500).send(err)
    }
}

export const addPet = (req, res) => {
    try {
        const resp = addItem(req.body)
        res.status(200).json(resp)

    } catch (err) {
        res.status(500).send(err)
    }
}

export const deletePet = (req, res) => {
    try {
        const resp = deleteItem(parseInt(req.params.id))
        res.status(200).json(resp)

    } catch (err) {
        res.status(500).send(err)
    }
}

Controllers are the functions that each endpoint request will trigger. As you can see, they receive as parameters the request and response objects. In the request object we can read things such as URL or body parameters, and we'll use the response object to send our response after doing the corresponding computation.

Each controller calls a specific function defined in our models.

Models

Now go to the models folder and create a pets.models.js file with this code in it:

import db from '../../db/db.js'

export const getItem = id => {
    try {
        const pet = db?.pets?.filter(pet => pet?.id === id)[0]
        return pet
    } catch (err) {
        console.log('Error', err)
    }
}

export const listItems = () => {
    try {
        return db?.pets
    } catch (err) {
        console.log('Error', err)
    }
}

export const editItem = (id, data) => {
    try {
        const index = db.pets.findIndex(pet => pet.id === id)

        if (index === -1) throw new Error('Pet not found')
        else {
            db.pets[index] = data
            return db.pets[index]
        }        
    } catch (err) {
        console.log('Error', err)
    }
}

export const addItem = data => {
    try {  
        const newPet = { id: db.pets.length + 1, ...data }
        db.pets.push(newPet)
        return newPet

    } catch (err) {
        console.log('Error', err)
    }
}

export const deleteItem = id => {
    try {
        // delete item from db
        const index = db.pets.findIndex(pet => pet.id === id)

        if (index === -1) throw new Error('Pet not found')
        else {
            db.pets.splice(index, 1)
            return db.pets
        }
    } catch (error) {

    }
}

These are the functions responsible for interacting with our data layer (database) and returning the corresponding information to our controllers.

Database

We wont use a real database for this example. Instead we'll just use a simple array that will work just fine for example purposes, though our data will of course reset every time our server does.

In the root of our project, create a db folder and a db.js file with this code in it:

const db = {
    pets: [
        {
            id: 1,
            name: 'Rex',
            type: 'dog',
            age: 3,
            breed: 'labrador',
        },
        {
            id: 2,
            name: 'Fido',
            type: 'dog',
            age: 1,
            breed: 'poodle',
        },
        {
            id: 3,
            name: 'Mittens',
            type: 'cat',
            age: 2,
            breed: 'tabby',
        },
    ]
}

export default db

As you can see, our db object contains a pets property whose value is an array of objects, each object being a pet. For each pet, we store an id, name, type, age and breed.

Now go to your terminal and run nodemon app.js. You should see this message confirming your server is alive: ⚡️[server]: Server is running at [https://localhost:3000](https://localhost:3000).

How to Test a REST API with Supertest

Now that our server is up and running, let's implement a simple test suit to check if each of our endpoints behaves as expected.

If you're not familiar with automated testing, I recommend you read this introductory article I wrote a while ago.

Our tools

SuperTest works with any JavaScript testing framework, such as Mocha or Jest, and can be used with any HTTP server or web application framework, such as Express.

SuperTest also allows developers to test the entire request/response cycle, including middleware and error handling, making it a powerful tool for testing web applications.

The code

First we'll need to install some dependencies. To save up terminal commands, go to your package.json file and replace your devDependencies section with this. Then run npm install

  "devDependencies": {
    "@babel/core": "^7.21.4",
    "@babel/preset-env": "^7.21.4",
    "babel-jest": "^29.5.0",
    "jest": "^29.5.0",
    "jest-babel": "^1.0.1",
    "nodemon": "^2.0.22",
    "supertest": "^6.3.3"
  }

Here we're installing the supertest and jest libraries, which we need for our tests to run, plus some babel stuff we need for our project to correctly identify which files are test files.

Still in your package.json, add this script:

  "scripts": {
    "test": "jest"
  },

To end with the boilerplate, in the root of your project, create a babel.config.cjs file and drop this code in it:

//babel.config.cjs
module.exports = {
    presets: [
      [
        '@babel/preset-env',
        {
          targets: {
            node: 'current',
          },
        },
      ],
    ],
  };

Now let's write some actual tests! Within your routes folder, create a pets.test.js file with this code in it:

import supertest from 'supertest' // Import supertest
import server from '../../app' // Import the server object
const requestWithSupertest = supertest(server) // We will use this function to mock HTTP requests

describe('GET "/"', () => {
    test('GET "/" returns all pets', async () => {
        const res = await requestWithSupertest.get('/pets')
        expect(res.status).toEqual(200)
        expect(res.type).toEqual(expect.stringContaining('json'))
        expect(res.body).toEqual([
            {
                id: 1,
                name: 'Rex',
                type: 'dog',
                age: 3,
                breed: 'labrador',
            },
            {
                id: 2,
                name: 'Fido',
                type: 'dog',
                age: 1,
                breed: 'poodle',
            },
            {
                id: 3,
                name: 'Mittens',
                type: 'cat',
                age: 2,
                breed: 'tabby',
            },
        ])
    })
})

describe('GET "/:id"', () => {
    test('GET "/:id" returns given pet', async () => {
        const res = await requestWithSupertest.get('/pets/1')
        expect(res.status).toEqual(200)
        expect(res.type).toEqual(expect.stringContaining('json'))
        expect(res.body).toEqual(
            {
                id: 1,
                name: 'Rex',
                type: 'dog',
                age: 3,
                breed: 'labrador',
            }
        )
    })
})

describe('PUT "/:id"', () => {
    test('PUT "/:id" updates pet and returns it', async () => {
        const res = await requestWithSupertest.put('/pets/1').send({
            id: 1,
            name: 'Rexo',
            type: 'dogo',
            age: 4,
            breed: 'doberman'
        })
        expect(res.status).toEqual(200)
        expect(res.type).toEqual(expect.stringContaining('json'))
        expect(res.body).toEqual({
            id: 1,
            name: 'Rexo',
            type: 'dogo',
            age: 4,
            breed: 'doberman'
        })
    })
})

describe('POST "/"', () => {
    test('POST "/" adds new pet and returns the added item', async () => {
        const res = await requestWithSupertest.post('/pets').send({
            name: 'Salame',
            type: 'cat',
            age: 6,
            breed: 'pinky'
        })
        expect(res.status).toEqual(200)
        expect(res.type).toEqual(expect.stringContaining('json'))
        expect(res.body).toEqual({
            id: 4,
            name: 'Salame',
            type: 'cat',
            age: 6,
            breed: 'pinky'
        })
    })
})

describe('DELETE "/:id"', () => {
    test('DELETE "/:id" deletes given pet and returns updated list', async () => {
        const res = await requestWithSupertest.delete('/pets/2')
        expect(res.status).toEqual(200)
        expect(res.type).toEqual(expect.stringContaining('json'))
        expect(res.body).toEqual([
            {
                id: 1,
                name: 'Rexo',
                type: 'dogo',
                age: 4,
                breed: 'doberman'
            },
            {
                id: 3,
                name: 'Mittens',
                type: 'cat',
                age: 2,
                breed: 'tabby',
            },
            {
                id: 4,
                name: 'Salame',
                type: 'cat',
                age: 6,
                breed: 'pinky'
            }
        ])
    })
})

For each endpoint, the tests send HTTP requests and check the responses for three things: the HTTP status code, the response type (which should be JSON), and the response body (which should match the expected JSON format).

The first test sends a GET request to the /pets endpoint and expects the API to return an array of pets in JSON format.
The second test sends a GET request to the /pets/:id endpoint and expects the API to return the pet with the specified ID in JSON format.
The third test sends a PUT request to the /pets/:id endpoint and expects the API to update the pet with the specified ID and return the updated pet in JSON format.
The fourth test sends a POST request to the /pets endpoint and expects the API to add a new pet and return the added pet in JSON format.
Finally, the fifth test sends a DELETE request to the /pets/:id endpoint and expects the API to remove the pet with the specified ID and return the updated list of pets in JSON format.

Each test checks whether the expected HTTP status code, response type, and response body are returned. If any of these expectations are not met, the test fails and provides an error message.

These tests are important for ensuring that the API is working correctly and consistently across different HTTP requests and endpoints. The tests can be run automatically, which makes it easy to detect any issues or regressions in the API's functionality.

Now go to your terminal, run npm test, and you should see all your tests passing:

> restapi@1.0.0 test
> jest

 PASS  pets/routes/pets.test.js
  GET "/"
    ✓ GET "/" returns all pets (25 ms)
  GET "/:id"
    ✓ GET "/:id" returns given pet (4 ms)
  PUT "/:id"
    ✓ PUT "/:id" updates pet and returns it (15 ms)
  POST "/"
    ✓ POST "/" adds new pet and returns the added item (3 ms)
  DELETE "/:id"
    ✓ DELETE "/:id" deletes given pet and returns updated list (3 ms)

Test Suites: 1 passed, 1 total
Tests:       5 passed, 5 total
Snapshots:   0 total
Time:        1.611 s
Ran all test suites.

How to Consume a REST API on a Front-end React App

Now we know our server is running and our endpoints are behaving as expected. Let's see some more realistic example of how our API might be consumed by a front end app.

For this example, we'll use a React application, and two different tools to send and process our requests: the Fetch API and the Axios library.

Our tools

The Fetch API is a modern browser API that allows developers to make asynchronous HTTP requests from client-side JavaScript code. It provides a simple interface for fetching resources across the network, and supports a variety of request and response types.

Axios is a popular HTTP client library for JavaScript. It provides a simple and intuitive API for making HTTP requests, and supports a wide range of features, including request and response interception, automatic transforms for request and response data, and the ability to cancel requests. It can be used both in the browser and on the server, and is often used in conjunction with React applications.

The code

Let's create our React app by running yarn create vite and following the terminal prompts. Once that's done, run yarn add axios and yarn add react-router-dom (which we'll use to setup basic routing in our app).

App.jsx

Put this code within your App.jsx file:

import { Suspense, lazy, useState } from 'react'
import { BrowserRouter as Router, Routes, Route, Link } from 'react-router-dom'
import './App.css'

const PetList = lazy(() => import ('./pages/PetList'))
const PetDetail = lazy(() => import ('./pages/PetDetail'))
const EditPet = lazy(() => import ('./pages/EditPet'))
const AddPet = lazy(() => import ('./pages/AddPet'))

function App() {

  const [petToEdit, setPetToEdit] = useState(null)

  return (
    <div className="App">
      <Router>
        <h1>Pet shelterh1>

        <Link to='/add'>
          <button>Add new petbutton>
      Link>

        <Routes>
          <Route path='/' element={<Suspense fallback={<>}><PetList />Suspense>}/>

          <Route path='/:petId' element={<Suspense fallback={<>}><PetDetail setPetToEdit={setPetToEdit} />Suspense>}/>

          <Route path='/:petId/edit' element={<Suspense fallback={<>}><EditPet petToEdit={petToEdit} />Suspense>}/>

          <Route path='/add' element={<Suspense fallback={<>}><AddPet />Suspense>}/>
        

      
    
  )
}

export default App

Here we're just defining our routes. We'll have 4 main routes in our app, each corresponding to a different view:

One to see the whole list of pets.
One to see the detail of a single pet.
One to edit a single pet.
One to add a new pet to the list.

Besides, we have a button to add a new pet and a state that will store the information of the pet we want to edit.

Next, create a pages directory with these files in it:

Folder structure

PetList.jsx

Let's start with the file responsible for rendering the whole list of pets:

import { useEffect, useState } from 'react'
import { Link } from 'react-router-dom'
import axios from 'axios'

function PetList() {
    const [pets, setPets] = useState([])

    const getPets = async () => {
        try {
            /* FETCH */
            // const response = await fetch('http://localhost:3000/pets')
            // const data = await response.json()
            // if (response.status === 200) setPets(data)

            /* AXIOS */
            const response = await axios.get('http://localhost:3000/pets')
            if (response.status === 200) setPets(response.data)

        } catch (error) {
            console.error('error', error)
        }
    }

    useEffect(() => { getPets() }, [])

    return (
        <>
            <h2>Pet Listh2>

            {pets?.map((pet) => {
                return (
                    <div key={pet?.id}>
                        <p>{pet?.name} - {pet?.type} - {pet?.breed}p>

                        <Link to={`/${pet?.id}`}>
                            <button>Pet detailbutton>
                        Link>
                    div>
                )
            })}
        
    )
}

export default PetList

As you can see, logic-wise we have 3 main things here:

A state that stores the list of pets to render.
A function that executes the corresponding request to our API.
A useEffect that executes that function when the component renders.

You can see that the syntax for making the HTTP request with fetch and Axios is rather similar, but Axios is a tiny bit more succinct. Once we make the request, we check if the status is 200 (meaning it was successful), and store the response in our state.

Once our state is updated, the component will render the data provided by our API.

Remember that to make calls to our server, we must have it up and running by running nodemon app.js in our server project terminal.

PetDetail.jsx

Now let's go to the PetDetail.jsx file:

import { useEffect, useState } from 'react'
import { useParams, Link } from 'react-router-dom'
import axios from 'axios'

function PetDetail({ setPetToEdit }) {

    const [pet, setPet] = useState([])

    const { petId } = useParams()

    const getPet = async () => {
        try {
            /* FETCH */
            // const response = await fetch(`http://localhost:3000/pets/${petId}`)
            // const data = await response.json()
            // if (response.status === 200) {
            //     setPet(data)
            //     setPetToEdit(data)
            // }

            /* AXIOS */
            const response = await axios.get(`http://localhost:3000/pets/${petId}`)
            if (response.status === 200) {
                setPet(response.data)
                setPetToEdit(response.data)
            }

        } catch (error) {
            console.error('error', error)
        }
    }

    useEffect(() => { getPet() }, [])

    const deletePet = async () => {
        try {
            /* FETCH */
            // const response = await fetch(`http://localhost:3000/pets/${petId}`, {
            //     method: 'DELETE'
            // })

            /* AXIOS */
            const response = await axios.delete(`http://localhost:3000/pets/${petId}`)

            if (response.status === 200) window.location.href = '/'
        } catch (error) {
            console.error('error', error)
        }
    }

    return (
        <div style={{ display: 'flex', flexDirection: 'column', justifyContent: 'center', aligniItems: 'center' }}>
            <h2>Pet Detailh2>

            {pet && (
                <>
                    <p>Pet name: {pet.name}p>
                    <p>Pet type: {pet.type}p>
                    <p>Pet age: {pet.age}p>
                    <p>Pet breed: {pet.breed}p>

                    <div style={{ display: 'flex', justifyContent: 'center', aligniItems: 'center' }}>

                        <Link to={`/${pet?.id}/edit`}>
                            <button style={{ marginRight: 10 }}>Edit petbutton>
                        Link>

                        <button
                            style={{ marginLeft: 10 }}
                            onClick={() => deletePet()}
                        >
                            Delete pet
                        button>
                    div>
                
            )}
        
    )
}

export default PetDetail

Here we have two different kind of requests:

One that gets the information of the given pet (which behaves very similar to the previous request we saw). The only difference here is we're passing an URL parameter to our endpoint, which at the same time we're reading from the URL in our front-end app.
The other request is to delete the given pet from our register. The difference here is once we confirm that the request was successful, we redirect the user to the root of our app.

AddPet.jsx

This is the file responsible for adding a new pet to our register:

import React, { useState } from 'react'
import axios from 'axios'

function AddPet() {

    const [petName, setPetName] = useState()
    const [petType, setPetType] = useState()
    const [petAge, setPetAge] = useState()
    const [petBreed, setPetBreed] = useState()

    const addPet = async () => {
        try {
            const petData = {
                name: petName,
                type: petType,
                age: petAge,
                breed: petBreed
            }

            /* FETCH */
            // const response = await fetch('http://localhost:3000/pets/', {
            //     method: 'POST',
            //     headers: {
            //         'Content-Type': 'application/json'
            //     },
            //     body: JSON.stringify(petData)
            // })

            // if (response.status === 200) {
            //     const data = await response.json()
            //     window.location.href = `/${data.id}`
            // }

            /* AXIOS */
            const response = await axios.post(
                'http://localhost:3000/pets/',
                petData,
                { headers: { 'Content-Type': 'application/json' } }
            )

            if (response.status === 200) window.location.href = `/${response.data.id}`

        } catch (error) {
            console.error('error', error)
        }
    }

    return (
        <div style={{ display: 'flex', flexDirection: 'column', justifyContent: 'center', aligniItems: 'center' }}>
            <h2>Add Peth2>

            <div style={{ display: 'flex', flexDirection: 'column', margin: 20 }}>
                <label>Pet namelabel>
                <input type='text' value={petName} onChange={e => setPetName(e.target.value)} />
            div>

            <div style={{ display: 'flex', flexDirection: 'column', margin: 20 }}>
                <label>Pet typelabel>
                <input type='text' value={petType} onChange={e => setPetType(e.target.value)} />
            div>

            <div style={{ display: 'flex', flexDirection: 'column', margin: 20 }}>
                <label>Pet agelabel>
                <input type='text' value={petAge} onChange={e => setPetAge(e.target.value)} />
            div>

            <div style={{ display: 'flex', flexDirection: 'column', margin: 20 }}>
                <label>Pet breedlabel>
                <input type='text' value={petBreed} onChange={e => setPetBreed(e.target.value)} />
            div>

            <button
                style={{ marginTop: 30 }}
                onClick={() => addPet()}
            >
                Add pet
            button>
        div>
    )
}

export default AddPet

Here we're rendering a form in which the user has to enter the new pet info.

We have a state for each piece of information to enter, and in our request we build an object with each state. This object will be the body of our request.

On our request, we check if the response is successful. If it is, we redirect to the detail page of the newly added pet. To redirect, we use the id returned in the HTTP response. ;)

EditPet.jsx

Finally, the file responsible for editing a pet register:

import React, { useState } from 'react'
import axios from 'axios'

function EditPet({ petToEdit }) {

    const [petName, setPetName] = useState(petToEdit?.name)
    const [petType, setPetType] = useState(petToEdit?.type)
    const [petAge, setPetAge] = useState(petToEdit?.age)
    const [petBreed, setPetBreed] = useState(petToEdit?.breed)

    const editPet = async () => {
        try {
            const petData = {
                id: petToEdit.id,
                name: petName,
                type: petType,
                age: petAge,
                breed: petBreed
            }

            /* FETCH */
            // const response = await fetch(`http://localhost:3000/pets/${petToEdit.id}`, {
            //     method: 'PUT',
            //     headers: {
            //         'Content-Type': 'application/json'
            //     },
            //     body: JSON.stringify(petData)
            // })

            /* AXIOS */
            const response = await axios.put(
                `http://localhost:3000/pets/${petToEdit.id}`,
                petData,
                { headers: { 'Content-Type': 'application/json' } }
            )

            if (response.status === 200) {
                window.location.href = `/${petToEdit.id}`
            }
        } catch (error) {
            console.error('error', error)
        }
    }

    return (
        <div style={{ display: 'flex', flexDirection: 'column', justifyContent: 'center', aligniItems: 'center' }}>
            <h2>Edit Peth2>

            <div style={{ display: 'flex', flexDirection: 'column', margin: 20 }}>
                <label>Pet namelabel>
                <input type='text' value={petName} onChange={e => setPetName(e.target.value)} />
            div>

            <div style={{ display: 'flex', flexDirection: 'column', margin: 20 }}>
                <label>Pet typelabel>
                <input type='text' value={petType} onChange={e => setPetType(e.target.value)} />
            div>

            <div style={{ display: 'flex', flexDirection: 'column', margin: 20 }}>
                <label>Pet agelabel>
                <input type='text' value={petAge} onChange={e => setPetAge(e.target.value)} />
            div>

            <div style={{ display: 'flex', flexDirection: 'column', margin: 20 }}>
                <label>Pet breedlabel>
                <input type='text' value={petBreed} onChange={e => setPetBreed(e.target.value)} />
            div>

            <button
                style={{ marginTop: 30 }}
                onClick={() => editPet()}
            >
                Save changes
            button>
        div>
    )
}

export default EditPet

This behaves very similar to the AddPet.jsx file. The only difference is that our pet info states are initialized with the values of the pet we want to edit. When those values are updated by the user, we construct an object that will be our request body and send the request with the updated information. Quite straightforward. ;)

And that's it! We're using all of our API endpoints in our front end app. =)

How to Document a REST API with Swagger

Now that we have our server up and running, tested, and connected to our front end app, the last step in our implementation will be to document our API.

Documenting and API generally means declaring which endpoints are available, what actions are performed by each endpoint, and the parameters and return values for each of them.

This is useful not only to remember how our server works, but also for people who want to interact with our API.

For example, in companies it's very usual to have back-end teams and front-end teams. When an API is being developed and needs to be integrated with a front-end app, it would be very tedious to ask which endpoint does what, and what parameters should be passed. If you have all that info in a singe place, you can just go there and read it yourself. That's what documentation is.

Our tools

Swagger is a set of open-source tools that help developers build, document, and consume RESTful web services. It provides a user-friendly graphical interface for users to interact with an API and also generates client code for various programming languages to make API integration easier.

Swagger provides a comprehensive set of features for API development, including API design, documentation, testing, and code generation. It allows developers to define API endpoints, input parameters, expected output, and authentication requirements in a standardized way using the OpenAPI specification.

Swagger UI is a popular tool that renders OpenAPI specifications as an interactive API documentation that allows developers to explore and test APIs through a web browser. It provides a user-friendly interface that allows developers to easily view and interact with API endpoints.

How to Implement Swagger

Back in our server app, to implement Swagger we'll need two new dependencies. So run npm i swagger-jsdoc and npm i swagger-ui-express.

Next, modify the app.js file to look like this:

import express from 'express'
import cors from 'cors'
import swaggerUI from 'swagger-ui-express'
import swaggerJSdoc from 'swagger-jsdoc'

import petRoutes from './pets/routes/pets.routes.js'

const app = express()
const port = 3000

// swagger definition
const swaggerSpec = {
    definition: {
        openapi: '3.0.0',
        info: {
            title: 'Pets API',
            version: '1.0.0',
        },
        servers: [
            {
                url: `http://localhost:${port}`,
            }
        ]
    },
    apis: ['./pets/routes/*.js'],
}

/* Global middlewares */
app.use(cors())
app.use(express.json())
app.use(
    '/api-docs',
    swaggerUI.serve,
    swaggerUI.setup(swaggerJSdoc(swaggerSpec))
)

/* Routes */
app.use('/pets', petRoutes)

/* Server setup */
if (process.env.NODE_ENV !== 'test') {
    app.listen(port, () => console.log(`⚡️[server]: Server is running at https://localhost:${port}`))
}

export default app

As you can see, we're importing the new dependencies, we're creating a swaggerSpec object that contains config options for our implementation, and then setting a middleware to render our documentation in the /api-docs directory of our app.

By now, if you open your browser and go to http://localhost:3000/api-docs/ you should see this:

Documentation UI

The cool thing about Swagger is it provides an out-of-the-box UI for our docs, and you can easily access it in the URL path declared in the config.

Now let's write some actual documentation!

Hop on to the pets.routes.js file and replace its code with this:

import express from "express";
import {
  listPets,
  getPet,
  editPet,
  addPet,
  deletePet,
} from "../controllers/pets.controllers.js";

const router = express.Router();

/**
 * @swagger
 * components:
 *  schemas:
 *     Pet:
 *      type: object
 *      properties:
 *          id:
 *              type: integer
 *              description: Pet id
 *          name:
 *              type: string
 *              description: Pet name
 *          age:
 *              type: integer
 *              description: Pet age
 *          type:
 *              type: string
 *              description: Pet type
 *          breed:
 *              type: string
 *              description: Pet breed
 *     example:
 *          id: 1
 *          name: Rexaurus
 *          age: 3
 *          breed: labrador
 *          type: dog
 */

/**
 * @swagger
 * /pets:
 *  get:
 *     summary: Get all pets
 *     description: Get all pets
 *     responses:
 *      200:
 *         description: Success
 *      500:
 *         description: Internal Server Error
 */
router.get("/", listPets);

/**
 * @swagger
 * /pets/{id}:
 *  get:
 *     summary: Get pet detail
 *     description: Get pet detail
 *     parameters:
 *       - in: path
 *         name: id
 *         schema:
 *           type: integer
 *         required: true
 *         description: Pet id
 *     responses:
 *      200:
 *         description: Success
 *      500:
 *         description: Internal Server Error
 */
router.get("/:id", getPet);

/**
 * @swagger
 * /pets/{id}:
 *  put:
 *     summary: Edit pet
 *     description: Edit pet
 *     parameters:
 *       - in: path
 *         name: id
 *         schema:
 *           type: integer
 *         required: true
 *         description: Pet id
 *     requestBody:
 *       description: A JSON object containing pet information
 *       content:
 *         application/json:
 *           schema:
 *              $ref: '#/components/schemas/Pet'
 *           example:
 *              name: Rexaurus
 *              age: 12
 *              breed: labrador
 *              type: dog
 *     responses:
 *     200:
 *        description: Success
 *     500:
 *       description: Internal Server Error
 *
 */
router.put("/:id", editPet);

/**
 * @swagger
 * /pets:
 *  post:
 *      summary: Add pet
 *      description: Add pet
 *      requestBody:
 *          description: A JSON object containing pet information
 *          content:
 *             application/json:
 *                 schema:
 *                    $ref: '#/components/schemas/Pet'
 *                 example:
 *                    name: Rexaurus
 *                    age: 12
 *                    breed: labrador
 *                    type: dog
 *      responses:
 *      200:
 *          description: Success
 *      500:
 *          description: Internal Server Error
 */
router.post("/", addPet);

/**
 * @swagger
 * /pets/{id}:
 *  delete:
 *     summary: Delete pet
 *     description: Delete pet
 *     parameters:
 *       - in: path
 *         name: id
 *         schema:
 *           type: integer
 *         required: true
 *         description: Pet id
 *     responses:
 *     200:
 *        description: Success
 *     500:
 *       description: Internal Server Error
 */
router.delete("/:id", deletePet);

export default router;

As you can see, we're adding a special kind of comment for each of our endpoints. This is the way Swagger UI identifies the documentation within our code. We've put them in this file since it makes sense to have the docs as close to the endpoints as possible, but you could place them wherever you want.

If we analyze the comments in detail you could see they're written in a YAML like syntax, and for each of them we specify the endpoint route, HTTP method, a description, the parameters it receives and the possible responses.

All comments are more or less the same except the first one. In that one we're defining a "schema" which is like a typing to a kind of object we can later on reuse in other comments. In our case, we're defining the "Pet" schema which we then use for the put and post endpoints.

If you enter http://localhost:3000/api-docs/ again, you should now see this:

Documentation UI

Each of the endpoints can be expanded, like this:

Documentation UI

And if we click the "Try it out" button, we can execute an HTTP request and see what the response looks like:

Documentation UI

This is really useful for developers in general and people who want to work with our API, and very easy to set up as you can see.

Having an out-of-the-box UI simplifies the interaction with the documentation. And having it within our codebase as well is a great bonus, as we can modify and update it without the need of touching anything else but our own code.

Wrapping Up

As always, I hope you enjoyed the handbook and learned something new. If you want, you can also follow me on LinkedIn or Twitter.

See you in the next one!

JavaScript Primitive Values vs Reference Values – Explained with Examples

German Cocca — Tue, 18 Apr 2023 16:31:17 +0000

Hi everyone! In JavaScript, variables can hold two types of data: primitive values and reference values. Understanding the difference between these two types of data is crucial for writing efficient and bug-free code.

In this short article, we will explore the difference between values and references in JavaScript.

What are primitive values?
What are reference values?
How to pass values and references as function arguments
How to create copies of objects, arrays and functions
- Shallow vs deep copies
Wrapping up

What are Primitive Values?

Primitive values are data that are stored directly in a variable. These include numbers, booleans, strings, null, and undefined.

When we assign a primitive value to a variable, a copy of that value is created and stored in memory. Any changes made to the variable do not affect the original value.

For example:

let x = 5;
let y = x;
y = 10;
console.log(x); // Output: 5
console.log(y); // Output: 10

In the example above, the variable y is assigned a copy of the value of x. When we change the value of y, it does not affect the value of x. This is because x and y are separate variables with separate memory locations.

What are Reference Values?

Reference values, on the other hand, are objects that are stored in memory and accessed through a reference. These include arrays, objects, and functions.

When we assign a reference value to a variable, a reference to the original value is created and stored in memory. Any changes made to the variable affect the original value.

For example:

let array1 = [1, 2, 3];
let array2 = array1;
array2.push(4);
console.log(array1); // Output: [1, 2, 3, 4]
console.log(array2); // Output: [1, 2, 3, 4]

In the example above, the variable array2 is assigned a reference to the original array array1. When we push a value to array2, it also affects array1 because both variables reference the same memory location.

How to Pass Values and References as Function Arguments

When we pass a primitive value as an argument to a function, a copy of that value is created and passed to the function. Any changes made to the variable inside the function do not affect the original value.

For example:

function addOne(x) {
    x++;
    return x;
}

let number = 5;
console.log(addOne(number)); // Output: 6
console.log(number); // Output: 5

In the example above, the function addOne receives a copy of the value of number. When we increment the value of x inside the function, it does not affect the value of number.

When we pass a reference value as an argument to a function, a reference to the original value is passed. Any changes made to the variable inside the function affect the original value.

For example:

function addToArray(array) {
    array.push(4);
    return array;
}

let myArray = [1, 2, 3];
console.log(addToArray(myArray)); // Output: [1, 2, 3, 4]
console.log(myArray); // Output: [1, 2, 3, 4]

In the example above, the function addToArray receives a reference to the original array myArray. When we push a value to array inside the function, it also affects myArray because both variables reference the same memory location.

How to Create Copies of Objects, Arrays, and Functions

Creating a copy of an object, array, or function can be useful when you want to modify the data without affecting the original. There are several ways to create a copy of an object in JavaScript.

One way to create a shallow copy of an object is to use the object spread syntax, which was introduced in ECMAScript 2018. The syntax is simple and looks like this:

const originalObj = { name: "John", age: 30 };
const copyObj = { ...originalObj };

In this example, copyObj is a new object with the same properties as originalObj. However, modifying copyObj will not affect originalObj.

For arrays, the slice() method can be used to create a shallow copy of an array. Here's an example:

const originalArr = [1, 2, 3, 4];
const copyArr = originalArr.slice();

In this example, copyArr is a new array with the same values as originalArr.

When it comes to creating a copy of a function, things get a bit more complicated. One approach is to create a new function that simply calls the original function with the same arguments. Here's an example:

function originalFunc(arg1, arg2) {
    // function body here
}
const copyFunc = function(...args) {
    return originalFunc.apply(this, args);
};

In this example, copyFunc is a new function that calls originalFunc with the same arguments. But keep in mind that this only creates a shallow copy of the function. Any functions or objects used within originalFunc will still reference the original values.

As you can see, creating copies of objects, arrays, and functions can be a useful technique in JavaScript programming. Using the appropriate method for the data type you're working with will help ensure that your code behaves as expected and is more maintainable in the long run.

Shallow vs Deep Copies

In JavaScript, there are two ways to copy objects and arrays: shallow copy and deep copy. Understanding the difference between these two types of copies is important, as it can affect the behavior of your code.

A shallow copy creates a new object or array, but it only copies the references to the properties of the original object or array.

In other words, the new object or array has the same values for its properties as the original, but the properties themselves still reference the same values in memory. This means that any changes made to the properties of the new object or array will also affect the original object or array, and vice versa.

Here's an example of a shallow copy of an array:

const originalArr = [1, 2, 3, [4, 5]];
const shallowCopyArr = [...originalArr];

shallowCopyArr[0] = 10;
shallowCopyArr[3][0] = 40;

console.log(originalArr); // [1, 2, 3, [40, 5]]
console.log(shallowCopyArr); // [10, 2, 3, [40, 5]]

In this example, the spread operator is used to create a shallow copy of originalArr. Then, the first element of shallowCopyArr is changed to 10, which does not affect originalArr. But when the first element of the nested array in shallowCopyArr is changed to 40, it also changes in originalArr, because both arrays share a reference to the same nested array.

A deep copy, on the other hand, creates a new object or array. It also copies the values of the properties of the original object or array, rather than just the references. This means that any changes made to the new object or array will not affect the original object or array, and vice versa.

Here's an example of a deep copy of an array:

const originalArr = [1, 2, 3, [4, 5]];
const deepCopyArr = JSON.parse(JSON.stringify(originalArr));

deepCopyArr[0] = 10;
deepCopyArr[3][0] = 40;

console.log(originalArr); // [1, 2, 3, [4, 5]]
console.log(deepCopyArr); // [10, 2, 3, [40, 5]]

In this example, JSON.stringify() is used to convert originalArr to a string, and then JSON.parse() is used to convert the string back into an array. This creates a new array with the same values as originalArr, but the new array is completely independent from the original array.

In conclusion, the main difference between a shallow copy and deep copy in JavaScript is whether the new object or array only copies the references to the properties of the original object or array, or whether it also copies the values of the properties.

When copying complex data types like objects and arrays, it's important to use the appropriate type of copy depending on your use case.

Wrapping Up

In summary, understanding the difference between values and references in JavaScript is essential for writing efficient and bug-free code. By being aware of how data is stored and manipulated, you can avoid unexpected behavior and improve the performance of your applications.

Remember that primitive types are passed by value, while objects and arrays are passed by reference. Keep this in mind when working with functions and assigning variables.

Finally, it's worth noting that ECMAScript 6 introduced a new keyword called let which behaves more like traditional programming languages in regards to variable assignment. let allows you to declare a block-scoped variable, meaning that it is only accessible within the block of code it is declared in. This can help prevent confusion with referencing and values as the scope of the variable is limited.

In conclusion, while values and references may seem like a small detail in the grand scheme of JavaScript programming, they can have a significant impact on your code's behavior and efficiency. By understanding the differences and using the appropriate techniques for your particular situation, you can write cleaner, more effective, and less error-prone code.

As always, I hope you enjoyed the article and learned something new.

If you want, you can also follow me on LinkedIn or Twitter. See you in the next one!

How to Use Linters and Code Formatters in Your Projects

German Cocca — Mon, 10 Apr 2023 22:02:17 +0000

Hi everyone! In this article we're going to take a look at two very useful tools we can use to make our lives easier when writing code: linting tools and code formatters.

We're going to talk about what these tools are, how they work, why are they useful, and finally see how we can implement them in a basic React project.

Let's go!

About linting tools
About code formatters
How to Implement ESLint and Prettier
- How to Install ESLint
- How to Install Prettier
Wrapping up

About Linting Tools

In the world of web development, linting tools have become an essential part of the developer's toolkit.

Linting tools are used to analyze source code for potential errors or stylistic issues, making it easier to maintain code quality and consistency across a project.

What are Linting Tools?

Linting tools are automated tools that analyze source code to detect potential errors, security vulnerabilities, or coding style issues.

They are designed to help developers catch mistakes before they become a problem, and to promote best practices in coding.

The term "lint" comes from the name of the first lint tool, which was developed in the early 1970s by a team of Bell Labs researchers led by Stephen C. Johnson.

The original lint tool was designed to analyze C source code for potential errors and stylistic issues.

Since then, linting tools have evolved to work with a variety of programming languages, including JavaScript, Python, and Ruby.

Why are Linting Tools Useful?

Linting tools are useful for a number of reasons. Firstly, they help you catch errors early in the development process, when they are easier and cheaper to fix.

Secondly, they can help promote coding standards and best practices within a development team, ensuring that code is consistent and maintainable.

Finally, they can help you identify potential security vulnerabilities in your code, reducing the risk of a breach.

Main Linting Tools in the Market

There are several linting tools available in the market today. Here are some of the most popular ones:

ESLint: ESLint is a widely used and highly configurable linter for JavaScript and TypeScript. It can be extended using plugins and supports various rule sets, making it a flexible tool for enforcing coding standards and preventing errors.
JSHint: JSHint is a popular linter that has been around since 2010. It offers a simple configuration and a wide range of built-in rules to help developers avoid common pitfalls and improve code quality.
JSLint: JSLint was one of the first linters to be developed for JavaScript, and it still sees some use today. It is known for its strictness and for enforcing a particular style of code, which can be helpful for maintaining consistency across a team.
StandardJS: StandardJS is a popular linter that aims to provide a "batteries included" approach to JavaScript linting. It has a minimal configuration and includes a set of opinionated rules designed to promote clean, readable code.

And we should also talk about Typescript. When using TypeScript, the TypeScript compiler itself acts as a linter. It checks the syntax of TypeScript code and provides warnings and errors when there are issues. This built-in linter can catch common mistakes and issues such as misspelled variable names, invalid method calls, and syntax errors.

The TypeScript compiler can be run using the tsc command in a terminal. When the --noEmit flag is used, the TypeScript compiler will only perform a syntax check without compiling the code to JavaScript. This allows the compiler to act as a linter and provide feedback on code quality without actually generating any output.

You can also configure the TypeScript compiler using a tsconfig.json file to specify various options, including the strictness of the checking. This can help catch even more potential issues and ensure that the code follows best practice

If you're not familiar with TypeScript, I recommend you this article I wrote a while ago.

About Code Formatters

In modern web development, code formatters have become an essential tool for developers. These tools automate the process of code formatting, making it easier to write and read code.

What are Code Formatters?

Code formatters are automated tools that help you format source code automatically. The main purpose of code formatters is to standardize the formatting of code across a project or team, making it easier to read and understand code.

With code formatters, developers no longer need to spend time formatting code manually, which can save a lot of time and effort.

Code formatting tools have been around for decades. One of the earliest tools was the "indent" program, which was used to format C code in the early 1970s. But these early tools were limited and didn't have the same level of functionality as modern code formatters.

In the early 2000s, tools like "astyle" and "uncrustify" were developed, which introduced more advanced formatting capabilities.

Why are Code Formatters Useful?

Code formatters are useful for a variety of reasons. First and foremost, they help to standardize code formatting, which makes it easier to read and understand code. This is particularly important when working on large projects with multiple developers, where everyone needs to be able to read and understand each other's code.

Code formatters also help to ensure that code is consistent across a project or team, which can help to prevent errors and improve code quality. They also make it easier to maintain code over time, as the code is formatted consistently and is easier to read and understand.

Main Code Formatters Available

There are several code formatting tools available in the market today. Here are some of the most popular ones:

Prettier: Prettier is a popular code formatter for JavaScript, TypeScript, and CSS. It's highly configurable and can be used in a variety of different environments, including editors, build tools, and code quality checkers.
ESLint: While primarily known as a linting tool, ESLint can also be used as a code formatter. It has a --fix flag that can automatically format your code based on rules you define.
Beautify: Beautify is a code formatter for JavaScript, HTML, and CSS that can be used in a variety of editors and IDEs. It allows you to customize your formatting options and has support for a wide range of languages.

How to Implement ESLint and Prettier

Cool, so now let's see a linter and code formatter in action! We're going to implement the two most popular tools (ESLint and Prettier) in a simple React project to get an idea of how these things work.

First let's create our project by running this in our command line: npm create vite@latest linternsAndFormatters --template react

Then cd into your project and run npm install so our dependencies get installed.

Now that we have our project up and running, we'll start by installing ESLint.

How to Install ESLint

To install ESLint, we can just run npm init @eslint/config in our console. This will fire a series of prompts asking how we want to use ESLint in our project and building the corresponding config. Your console might end up looking something like this:

Installing ESLint

After all this, we'll see a new file called .eslintrc.cjs in the root of our project. Here's where ESLint's config lives and where we can customize the linter to our preferences. The initial config given the options I selected is the following:

module.exports = {
    "env": {
        "browser": true,
        "es2021": true
    },
    "extends": [
        "eslint:recommended",
        "plugin:react/recommended"
    ],
    "overrides": [
    ],
    "parserOptions": {
        "ecmaVersion": "latest",
        "sourceType": "module"
    },
    "plugins": [
        "react"
    ],
    "rules": {
    }
}

To see our linter in action, let's add the following script in our package.json file:

"lint": "eslint --fix . --ext .js,.jsx"

This script executes the eslint command with the --fix option to automatically fix linting errors and warnings. The command is executed on all files with the .js or .jsx extension located in the root directory of the project, as specified by the . argument.

Now let's modify our app.jsx file to have the following code:

import React from 'react'
import './App.css'

function App() {

  const emptyVariable = ''

  return (
    <div className="App">
      <h1>Vite + Reacth1>
    div>
  )
}

export default App

Then run npm run lint and voilà! Your linter is screaming with red highlighted text that you have an unused variable in your code! =D

How to Install Prettier

Cool, now let's hop on to our code formatter.

We're going to install it by running npm install --save-dev --save-exact prettier.

Then we're going to create and empty config file by running echo {}> .prettierrc.json.

Since we're here, add the following options to your newly created config file:

{
  "singleQuote": true,
  "jsxSingleQuote": true,
  "semi": false
}

What this does is assure single quotes are used whenever possible and semicolons are nowhere to be found (because, god, who likes semicolons...).

As we did with our linter, let's add the following script in our package.json file:

    "format": "prettier --write ."

The script runs the Prettier code formatter on all the files in the project directory and its sub-directories. When run with the --write option, it modifies the files in place, changing them to conform to Prettier's rules for indentation, line length, and other formatting options. The . argument specifies that all files in the project directory and its sub directories should be formatted.

Lastly, let's "uglify" the first line of our app.jsx file like this:

import React from "react";

Run npm run format and you should see it corrected right in front of you:

import React from 'react'

You can breath easy now, those ugly semicolons won't come back to haunt you. ;)

As we've seen, the set up of these two tools isn't that complex, and they truly help to make our everyday jobs easier. ESLint will help us catch bugs and unnecessary/redundant code, and Prettier will help us standardize code format all across our codebase.

Another tip is that if you have a CI/CD pipeline in place, it's a good idea to implement the linting and formatting scripts as part of your workflow. This will help you ensure that every deployment is both automatically linted and formatted.

If you're not familiar with CI/CD or setting up a pipeline, I recently wrote an article about that. ;)

Wrapping up

Linters and code formatters are powerful tools that can greatly benefit web developers.

Linters help you catch potential bugs and issues before they become serious problems, and encourage you to write more maintainable and readable code.

Code formatters help you enforce a consistent code style and format, saving time and reducing the chances of human error.

By using these tools in your web development workflow, you can improve your productivity and the quality of your code.

As always, I hope you enjoyed the article and learned something new.

If you want, you can also follow me on LinkedIn or Twitter. See you in the next one!

What is CI/CD? Learn Continuous Integration/Continuous Deployment by Building a Project

German Cocca — Fri, 07 Apr 2023 19:31:18 +0000

Hi everyone! In this article you're going to learn about CI/CD (continuous integration and continuous deployment).

We're going to review what this practice is about, how it compares to the previous approach in the software development industry, and finally see a practical example of how we can implement it in our projects.

Let's go!

Intro
How CI/CD works
The key benefits of CI/CD
Tools for CI/CD
How to set up a CI/CD pipeline with GitHub Actions
Wrapping up

Intro

Continuous Integration and Continuous Delivery (CI/CD) is a software development approach that aims to improve the speed, efficiency, and reliability of software delivery. This approach involves frequent code integration, automated testing, and continuous deployment of software changes to production.

Before the adoption of CI/CD in the software development industry, the common approach was a traditional, waterfall model of software development.

In this approach, developers worked in silos, with each stage of the software development life cycle completed in sequence. The process typically involved gathering requirements, designing the software, coding, testing, and deployment.

The disadvantages of this traditional approach include:

Slow Release Cycles: Since each stage of the software development life cycle was completed in sequence, the release cycle was slow, which made it difficult to respond quickly to changing customer needs.
High Failure Rates: Software projects were prone to failure due to a lack of automated testing, which meant that developers had to rely on manual testing, leading to errors and bugs in the code.
Limited Collaboration: The traditional approach did not encourage collaboration between developers, testers, and other stakeholders, which made it difficult to identify and fix issues.
High Cost: The manual nature of software development meant that it was expensive, with high costs associated with testing, debugging, and fixing errors.
Limited Agility: Since the traditional approach was linear, it was not possible to make changes to the software quickly or respond to customer needs in real-time.

CI/CD emerged as a solution to these disadvantages, by introducing a more agile and collaborative approach to software development. CI/CD enables teams to work together, integrating their code changes frequently, and automating the testing and deployment process.

How CI/CD Works

CI/CD is an automated process that involves frequent code integration, automated testing, and continuous deployment of software changes to production.

Let's explain each step in a little more detail:

Code Integration

The first step in the CI/CD pipeline is code integration. In this step, developers commit their code changes to a remote repository (like GitHub, GitLab or BitBucket), where the code is integrated with the main codebase.

This step aims to ensure that the code changes are compatible with the rest of the codebase and do not break the build.

Automated Testing

Once the code is integrated, the next step is automated testing. Automated testing involves running a suite of tests to ensure that the code changes are functional, meet the expected quality standards, and are free of defects.

This step helps identify issues early in the development process, allowing developers to fix them quickly and efficiently.

If you're not familiar with the topic of testing, you can refer to this article I wrote a while ago.

Continuous Deployment

After the code changes pass the automated testing step, the next step is continuous deployment. In this step, the code changes are automatically deployed to a staging environment for further testing.

This step aims to ensure that the software is continuously updated with the latest code changes, delivering new features and functionality to users quickly and efficiently.

Production Deployment

The final step in the CI/CD pipeline is production deployment. In this step, the software changes are released to end-users. This step involves monitoring the production environment, ensuring that the software is running smoothly, and identifying and fixing any issues that arise.

The four steps of a CI/CD pipeline work together to ensure that software changes are tested, integrated, and deployed to production automatically. This automation helps to reduce errors, increase efficiency, and improve the overall quality of the software.

By adopting a CI/CD pipeline, development teams can achieve faster release cycles, reduce the risk of software defects, and improve the user experience.

Keep in mind that the pipeline stages might look different given the specific project or company we're talking about. Meaning, some teams might or might not use automated testing, some teams might or might not have a "staging" environment, and so on.

The key parts that make up the CI/CD practice are integration and deployment. This means that the code has to be continually integrated in a remote repository, and that this code has to be continually deployed to a given environment after each integration.

The Key Benefits of CI/CD

The key benefits of CI/CD include:

Faster Release Cycles: By automating the testing and deployment process, CI/CD enables teams to release software more frequently, responding quickly to customer needs.
Improved Quality: Automated testing ensures that software changes do not introduce new bugs or issues, improving the overall quality of the software.
Increased Collaboration: Frequent code integration and testing require developers to work closely together, leading to better collaboration and communication.
Reduced Risk: Continuous deployment allows developers to identify and fix issues quickly, reducing the risk of major failures and downtime.
Cost-Effective: CI/CD reduces the amount of manual work required to deploy software changes, saving time and reducing costs.

In summary, CI/CD emerged as a solution to the limitations of the traditional, linear approach to software development. By introducing a more agile and collaborative approach to software development, CI/CD enables teams to work together, release software more frequently, and respond quickly to customer needs.

Tools for CI/CD

There are several tools available for implementing CI/CD pipelines in software development. Each tool has its unique features, pros, and cons. Here are some of the most commonly used tools in CI/CD pipelines today:

Jenkins

Jenkins is an open-source automation server that is widely used in CI/CD pipelines. It is highly customizable and supports a wide range of plugins, making it suitable for various development environments. Some of its key features include:

Pros:

Highly customizable with a wide range of plugins
Supports integration with various tools and technologies
Provides detailed reporting and analytics

Cons:

Requires some technical expertise to set up and maintain
Can be resource-intensive, especially for large projects
Lack of a centralized dashboard for managing multiple projects

If you want to learn more about Jenkins, here's a full course for you.

Travis CI

Travis CI is a cloud-based CI/CD platform that provides automated testing and deployment for software projects. It supports several programming languages and frameworks, making it suitable for various development environments. Some of its key features include:

Pros:

Easy to set up and use
Cloud-based, so there's no need to set up and maintain infrastructure
Supports a wide range of programming languages and frameworks
Provides detailed reporting and analytics

Cons:

Limited customization options
Not suitable for large projects with complex requirements
Limited support for on-premise installations

Here's a helpful tutorial about how to automate deployment on GitHub Pages with Travis CI.

GitHub actions

GitHub Actions is a powerful CI/CD tool that allows developers to automate workflows, run tests, and deploy code directly from their GitHub repositories.

Pros:

Integrated with GitHub
Easy to use
Provides large ecosystem and good documentation

Cons:

Limited build minutes
Complex YAML syntax

Side comment: I mention GitHub actions here because it's a popular tool – but keep in mind that other online repository providers like GitLab and BitBucket also provide very similar options to GitHub actions.

Built-in CI/CD features by hosts

Popular hosts such as Vercel or Netlify have built-in in CI/CD features that allow you to link an online repository to a given site, and deploy to that site after a given event occurs in that repo.

Pros:

Very simple to set up and use

Cons:

Limited customization options

Each of these tools has its unique features, pros, and cons. The choice of tool will depend on the specific requirements of your project, your team's technical expertise, and your budget.

Here's a tutorial about how to deploy a front-end app with Netlify. And in this tutorial, you'll learn how to use Vercel to deploy a Next.js app.

How to Set Up a CI/CD Pipeline with GitHub Actions

Cool, so now that we have a clear idea of what CI/CD is, let's see how we can implement a simple example with an actual project using GitHub actions.

Initializing the Project

We'll start with a very basic React app built with Vite. You can do that by running yarn create vite in your console.

We'll focus on the CI/CD pipeline here, so there will be no complexity in the actual app code. But just to have an idea, the app.jsx component will have this code:

import './App.css';

function App() {

    return (
        <div className='App'>
            <h1>Vite + Reactoooooh1>
        div>
    );
}

export default App;

And then we'll have a test file that will check for that text to render:

import { describe, expect, it } from 'vitest';
import { render, screen } from './utils/test-utils/test-utils.jsx';

import App from 'src/App.jsx';

describe('App', async () => {
    it('should render while authenticating', () => {
        render(<App />);

        expect(screen.getByText('Vite + Reactooooo')).toBeInTheDocument();
    });
});

This test will run each time we run the yarn test command.

Next step should be to push our code to a GitHub repo. Then, let's talk a bit more about what GitHub actions are and how they work.

What are GitHub Actions and How Do They Work?

GitHub Actions is a CI/CD (Continuous Integration/Continuous Deployment) service provided by GitHub. It allows developers to automate workflows by defining custom scripts, known as "actions", that can be triggered by events such as pushes to a repository, pull requests, or issues.

Actions are defined in a YAML file, also known as a "workflow", which specifies the steps required to complete a task. GitHub Actions workflows can run on Linux, Windows, and macOS environments and support a wide range of programming languages and frameworks.

When an event triggers a GitHub Actions workflow, the service creates a fresh environment, installs dependencies, and runs the defined steps in the order specified. This can include tasks such as building, testing, packaging, and deploying code.

GitHub Actions also provides several built-in actions that can be used to simplify common tasks, such as checking out code, building and testing applications, publishing releases, and deploying to popular cloud providers like AWS, Azure, and Google Cloud.

GitHub Actions workflows can be run on a schedule, manually, or automatically when a specific event occurs, such as a pull request being opened or a new commit being pushed to a branch.

Setting Up Our Workflow

Great, so as we've seen, basically GitHub actions are a feature that allows us to define workflows four our projects. These workflows are nothing but a series of tasks or steps that will execute on GitHub's cloud after a given event we declare.

The way GitHub reads and executes these workflows is by automatically reading files within the .github/workflows directory in the root of our project. These workflow files should have the .yaml extension and use the YAML syntax.

To create a new workflow we just have to create a new YAML file within that directory. We'll call ours prod.yaml since we'll use it to deploy the production branch of our project.

Keep in mind a single project can have many different workflows that run different tasks on different occasions. For example, we could have a workflow for dev and staging branches as well, as those environments could require different tasks to execute and will probably deploy on different sites.

After creating this file, let's drop the following code in it:

# Name of our workflow
name: Production deploy

# Trigger the workflow on push to the main branch
on:
  push:
    branches:
      - main

# List of jobs
# A "job" is a set of steps that are executed on the same runner
jobs:
  # Name of the job
  test-and-deploy-to-netlify:
    # Operating system to run on
    runs-on: ubuntu-latest

    # List of steps that make up the job
    steps:
    # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
    - name: Checkout code
      uses: actions/checkout@v2

    # Setup Node.js environment
    - name: Use Node.js 16.x
      uses: actions/setup-node@v2
      with:
        node-version: '16.x'

    # Install dependencies
    - name: Install dependencies
      run: yarn install

    # Run tests
    - name: Run tests
      run: yarn test

    # Deploy to Netlify
    - name: Netlify Deploy
      uses: jsmrcaga/action-netlify-deploy@v2.0.0
      with:
        # Auth token to use with netlify
        NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
        # Your Netlify site id
        NETLIFY_SITE_ID:  ${{ secrets.NETLIFY_SITE_ID }}
        # Directory where built files are stored
        build_directory: './dist'
        # Command to install dependencies
        install_command: yarn install
        # Command to build static website
        build_command: yarn build

So our workflow has the following tasks declared:

"Checkout code" step that checks out the latest commit on the current branch.
"Use Node.js 16.x" step that sets up the Node.js environment to version 16.x.
"Install dependencies" step that installs the project dependencies using the Yarn package manager.
"Run tests" step that runs the project's tests using the Yarn package manager.
"Netlify Deploy" step that deploys the project to Netlify using the jsmrcaga/action-netlify-deploy action. This step uses the Netlify authentication token and site ID secrets stored in the GitHub repository's secrets. The build directory, install command, and build command are also specified.

You probably noticed the first and last steps have the keyword uses. This keyword allows you to use actions or workflows developed by other GitHub users, and it's one of the best features of GitHub actions.

What's great is that by using this third party actions we can execute complex tasks such as deploying to an external host or building complex cloud infrastructure without the need to write every single line of necessary code.

As these tasks tend to be repetitive and frequently executed in many projects, we can just use a workflow developed by an official company account (such as Azure or AWS for example) or an independent open-source developer. Think about it as using a third party library. It's the same idea but taken to CI/CD workflows. Very convenient.

Another important thing to mention here is that in GitHub actions workflows tasks run sequentially, one after the other. And if a given task fails or throws and error, the next one won't execute. This is important because if we have a problem when installing our dependencies or a test fails, we don't want that code to be deployed.

Before we can push this code and see how the magic works, we first need to create a site on Netlify and get the NETLIFY_AUTH_TOKEN and NETLIFY_SITE_ID. This is quite straight forward even if you don't have previous experience with Netlify, so give it a try and Google a bit if you can't figure it out. ;)

Once you have these two tokens, you need to declare them as repository secrets in your GitHub repo. You can do this from the "settings" tab:

Configure both Netlify secret tokens in your repo

With this in place, now our prod.yaml file will be able to read these two tokens and execute the Netlify deploy action.

The Magic

Now that we have everything in place, let's push our code and see how it goes.

After pushing, if we go to the "actions" tabs of our repo, on the left we'll see a list of all the workflows we have in our repo. And on the right we'll see a list of each execution of the selected workflow. Since our workflow executes after each push, we should see a new execution each time we push.

A workflow execution

When the execution has a yellow light to the left of it, it means it's still running (executing tasks). If it has a green light it means it finished executing successfully and if the light is red, you know something went wrong, haha...

After clicking on the execution we can see a list of the workflow's jobs (we only had a single one).

The workflow's jobs

And after clicking on the job we can see a list of the job's tasks.

The tasks of the job

Each task is expansible and within it we can see logs corresponding to that task's execution. This is quite useful for debugging purposes. ;)

Now if we go to our previously set up Netlify site, we should see our app up and running!

And now that we have our CI/CD pipeline in place, we can deploy our app after each push to the main branch, all without lifting another finger. =D

Wrapping Up

CI/CD is a software development approach that provides several benefits to software development teams, including faster time-to-market, improved quality, increased collaboration, reduced risk, and cost-effectiveness.

By automating the software delivery pipeline, teams can quickly deploy new features and bug fixes, while reducing the risk of major failures and downtime.

With the availability of several CI/CD tools, it has become easier for teams to implement this approach and improve their software delivery process.

Well everyone, as always, I hope you enjoyed the article and learned something new.

If you want, you can also follow me on LinkedIn or Twitter. See you in the next one!

How to Measure and Improve the Performance of a React App

German Cocca — Mon, 27 Mar 2023 17:18:19 +0000

Hi everyone!

React is a popular JavaScript library for building user interfaces. As applications built with React become more complex, their performance can start to degrade.

Poor performance can lead to a frustrating user experience and a negative impact on user engagement. So in this article, we will discuss how to measure and improve the performance of a React application.

How to define performance
How to measure performance
- React dev tools
How to improve performance
Wrapping Up

How to Define Performance

In web development, "performance" generally refers to the speed and efficiency of a website or web application. It encompasses several different factors, including:

Page load time: This refers to the time it takes for a page to fully load and display all of its content. Faster load times generally lead to a better user experience.
Responsiveness: This refers to the speed at which a website responds to user interactions, such as clicking a button or scrolling. A responsive website feels snappy and quick, which can also improve user experience.
Resource usage: This refers to the amount of server resources (such as CPU and memory) that a website uses to serve pages and respond to requests. A well-optimized website will use resources efficiently, allowing the server to handle more traffic and reducing costs.
Scalability: This refers to a website's ability to handle increased traffic and load without sacrificing performance. A scalable website can handle sudden spikes in traffic without slowing down or crashing.

Optimizing website performance is important because it can directly impact user experience, search engine rankings, and even business revenue.

How to Measure Performance

The first step in improving the performance of a React application is to measure its current performance. There are several tools available for measuring performance, including:

Lighthouse – Lighthouse is an open-source tool from Google that audits web pages for performance, accessibility, and more. Lighthouse generates a report that includes suggestions for improving the performance of the application.
WebPageTest – WebPageTest is a free tool that allows you to test the speed of your website from multiple locations around the world. WebPageTest provides detailed reports on the performance of your website, including suggestions for improvement.
Google PageSpeed Insights – Google PageSpeed Insights analyzes the content of a web page and generates a report that identifies opportunities to improve the page's performance.

All three tools work basically in the same way. You provide the URL of the site you'd like to analyze, and the tools will run through it and provide you with a detailed report covering improvement opportunities in performance, and also accessibility, SEO and general best practices.

These tools are nice to get an objective measure of our apps. Some of them can even be integrated into CI/CD pipelines so we can monitor how changes impact in performance through time.

React dev tools

Another useful tool for measuring performance in a React app is the profiler of React DevTools. React DevTools is a browser extension that allows you to inspect and debug React applications in the Chrome, Firefox, or Edge browsers.

The "profiler" is a tool that allows you to record the activity in your app, and later on generate a report showing what components were rendered, how many times and when each component was rendered, and how long each render took.

It's quite useful for detecting unnecessary component re-renders and renders that take too long, generating performance bottlenecks.

If you'd like to get a deeper dive into how profiler works, I recommend this video.

How to Improve Performance

Now that we have an idea of how can we identify performance issues in our app, let's go through some of the optimization techniques we can use to make it better.

Optimizing Images

Images are one of the primary culprits for slow loading websites. You can optimize images by compressing them without compromising their quality. Tools like tinyPng can compress your images and help you reduce the size of your website, and therefore it's load time.

Meta frameworks such as Next come with built-in image optimization.

Code splitting and Lazy Loading

Lazy loading involves loading content only when it is needed, instead of loading everything at once. This is done through something called "code splitting". This is a bundling technique that allows you to break up code in smaller chunks that are downloaded only when needed, instead of downloading the whole code in the first render.

A classic example of when this technique can come in handy is when navigating through different routes. Let's say our website has two main routes, "Home" and "Contact".

We'd only want to download the code related to the "Home" page when we're in that route, and the "Contact" code to download when we are in that other route. Code splitting allows us to do that, and in this way help reduce the initial load time of the application and improve the user experience.

You can use tools such as React.lazy() and Suspense to implement lazy loading in your application. If you'd like a deeper dive into how these tools work, check out this video.

Optimizing the DOM

The size of the Document Object Model (DOM) can impact the performance of the application. The bigger and more complex it is, the longer it'll take to load and be modified.

You can optimize the DOM by reducing the number of elements, removing unnecessary elements, and minimizing the use of CSS animations.

Avoid unnecessary component re-renders

As you may know, React is a library that allows us to build user interfaces. In React, each piece of the UI is represented in code by a component. When a piece of the UI needs to be modified, React re-renders the component with the updated information.

There are two things that trigger a component re-render: A change in state or a change in props. But sometimes, components can re-render unnecessarily, meaning there's no actual change in the information to be displayed.

To prevent unnecessary re-renders, we can implement some of the following techniques:

Memoization: In React, memoization allows a component to "remember" the value of the state and/or props it receives. Before re-rendering, it can check if the value has actually changed. If it hasn't, then it doesn't re-render. This technique can be achieved through hooks like useMemo and useCallback. If you'd like a deeper dive on that, check out this article I wrote.
Use key prop for lists: When rendering a list of items in React, it's important to provide a unique key prop for each item. This helps React identify which items have changed and need to be re-rendered. If you don't provide a key prop, React will use the index of the item in the array, which can lead to unnecessary re-renders if the order of the items changes.
Keeping state as local as possible: By keeping state local, I mean that the state that a component uses should be (when possible) within the component itself or as close in the component tree as possible. This is because when a component re-renders, all children components will re-render as well. It's not necessarily a terrible thing, but if we can avoid it, we probably should. So It's not a good idea to centralize all state in a single parent component, unless that states needs to be used from multiple parts of the application down the component tree. Here's a great article about this topic if you're interested in learning more.

Rendering patterns

Another thing that can have an impact on the performance of your app is the rendering pattern it uses. A rendering pattern refers to the way in which the HTML, CSS, and JavaScript code is all processed and rendered in a web application or website.

Different rendering patterns are used to achieve different performance and user experience goals. The most common rendering patterns in web development are:

Client-side rendering (CSR): In CSR, the client's browser generates the HTML content of a web page on the client-side using JavaScript. This approach can provide a fast and interactive user experience but can be slower for initial loading times and bad for SEO.
Server-side rendering (SSR): In SSR, the web server generates the HTML content of a web page on the server-side and sends it to the client's browser. This approach can improve initial loading times and SEO (search engine optimization) but can be slower for dynamic content.

Server-Side Rendering (SSR) can help improve the initial load time of the application by rendering the initial page on the server-side. This can help improve the Time-to-Interactive (TTI) and First Contentful Paint (FCP) metrics. You can use tools such as Next.js or Gatsby to implement SSR in your application.

The choice of rendering pattern depends on the specific needs and requirements of a project, such as performance, SEO, user experience, and flexibility. If your priority is to provide users with a fluid, native-like experience, CSR is probably a good choice. If you need ultra fast page load times, SSR or SSG can be a better option.

For a deeper dive into rendering patterns, check out this article I recently wrote.

Content Delivery Network (CDN)

A CDN, or Content Delivery Network, is a system of distributed servers or nodes that work together to deliver web content, such as images, videos, and other files, to users based on their geographic location.

When a user requests content from a website, the CDN will serve the content from the server closest to the user, which helps to reduce latency and improve website performance. CDNs can also help to reduce the load on a website's origin server by caching frequently accessed content and delivering it from the CDN's servers instead of the origin server.

CDNs are normally used to host static content (meaning content that doesn't change frequently over time), such as images, videos, blog posts and so on. Also, if you're using Static Site Generation (SSG) as a rendering pattern, you could host your rendered sites in a CDN for an even faster delivery.

Some examples of popular CDNs are Cloudflare and Amazon CloudFront.

For more detail on how CDNs work, check out this awesome video.

Wrapping Up

Well everyine, in this article we've discussed how to measure and improve the performance of a React application.

We defined the concept of website performance, including page load time, responsiveness, resource usage, and scalability, and outlined how to measure performance using tools such as Lighthouse, WebPageTest, Google PageSpeed Insights and React dev tools.

Finally, we've seen some optimization techniques such as optimizing images, code splitting and lazy loading, optimizing the DOM, and avoiding unnecessary component re-renders.

As always, I hope you enjoyed the article and learned something new.

If you want, you can also follow me on LinkedIn or Twitter. See you in the next one!

How to Build a React App – A Walkthrough of the Many Different Ways

German Cocca — Mon, 13 Mar 2023 19:01:24 +0000

Hi everyone! In this article we're going to take a look at some of the many ways you can build a React application these days. We'll compare their main characteristics, along with their pros and cons.

We'll start by explaining what React is and what improvements it brought over the previous era of web development. Then we're going to build a React app from scratch to get a good idea of the libraries that conform React, and how it interacts with dependencies such as bundlers (like Webpack) and compilers (like Babel).

Finally, we're going to review more realistic approaches like CRA (create-react-app) and modern alternatives like Vite, Astro, Gatsby, Next and Remix.

This should be a longish but interesting article to read if you're wondering how React works under the hood, or if you want to know more about the differences between the many building tools available.

Let's hop on to it!

What is React and what does it do?
How to build a React app
Client side rendering (CSR) vs Server side rendering (SSR)
SSR building tools
- What is Astro?
- What is Gatsby?
React's metaframeworks
- What is Next?
- What is Remix?
Wrapping up

What is React and What Does it Do?

React.js is a popular open-source JavaScript library for building user interfaces (UIs) that was developed by Facebook. It enables developers to create reusable UI components and declaratively specify how the UI should look and behave based on changes in the application state.

If you wonder what "declaratively" means, you might be interested in this article about programming paradigms I wrote a while ago.

React follows a component-based architecture, where each UI element is represented as a separate component that can be reused throughout the application. React allows developers to create these components using a combination of HTML-like syntax called JSX and JavaScript code.

React uses a virtual DOM (Document Object Model) to efficiently update the actual DOM when the application state changes. This means that instead of updating the entire page every time a change occurs, React updates only the specific components that need to be changed. This makes React applications faster and more responsive compared to traditional JavaScript frameworks.

You can use React to build single-page applications, mobile applications, and even desktop applications using tools such as Electron. You can also combine it with other libraries and frameworks to build more complex applications.

React has a large and active community, with a wealth of resources and third-party libraries available to help developers get started quickly.

This all sounds pretty good, but it's tough to understand the value of a tool like React if you don't know how web development used to be before it. So let's take a quick look at that now.

Web Development Before React

Before React.js, web development was heavily reliant on traditional client-side scripting using vanilla JavaScript and libraries like jQuery.

Web developers used to build web applications by directly manipulating the Document Object Model (DOM) of web pages using JavaScript. This approach was often time-consuming and error-prone, especially for complex applications.

jQuery, a popular JavaScript library, was introduced as a way to simplify the process of manipulating the DOM and handling browser events. It provided a concise and easy-to-use syntax for selecting and manipulating HTML elements on a page.

jQuery was widely adopted by web developers due to its simplicity, and it helped to improve the efficiency of client-side scripting.

Other JavaScript frameworks such as AngularJS and Backbone.js also gained popularity in the early 2010s.

AngularJS provided a more structured approach to building web applications and was heavily focused on data binding and dependency injection. Backbone.js was a lightweight framework that allowed developers to create simple web applications with minimal overhead.

But despite their popularity, these JavaScript frameworks had various limitations. For example, they did not provide an efficient way of managing the state of web applications, which could lead to performance issues and slow page load times. They also did not provide an easy way to create reusable components, which could make it challenging to build complex web applications.

React.js addressed many of these limitations by introducing a new way of thinking about building web applications.

React.js allowed developers to create reusable UI components that could be composed together to build complex interfaces. It also introduced the concept of a virtual DOM, which improved the performance of web applications by minimizing the number of updates required to the actual DOM.

Overall, while vanilla JavaScript and libraries like jQuery were essential in the early days of web development, they were limited in their ability to handle complex applications. The emergence of frameworks like React.js has made it easier for developers to build scalable and efficient web applications.

The Benefits of React

React.js brought several improvements over traditional client-side scripting using vanilla JavaScript and libraries like jQuery, as well as over other JavaScript frameworks like Backbone.js, AngularJS, and Knockout.js. Some of these improvements include:

Component-Based Architecture: React.js introduced the concept of a component-based architecture, where UI elements are represented as separate reusable components that can be composed together to create complex interfaces. This approach makes it easier to manage complex web applications, improves code reusability, and allows for more efficient testing and debugging.
Virtual DOM: React.js introduced the concept of a virtual DOM, which is a lightweight representation of the actual DOM. The virtual DOM makes it possible to update the user interface without re-rendering the entire page. This results in faster page load times and improved performance, especially for complex applications.
JSX: React.js introduced JSX, a syntax extension that allows developers to write HTML-like code in JavaScript files. This makes it easier to write and maintain code, especially for developers who are more familiar with HTML than with JavaScript.
A different way to separate concerns: In previous paradigms, we used to have HTML, CSS and JavaScript divided into different files. Under React's paradigm, using JSX we can have HTML, JS, and (optionally) CSS in the same file, and divide our files according to the UI components they're responsible for.
Data Binding: React.js introduced a unidirectional data flow, which means that data flows in a single direction from parent components to child components. This approach simplifies data management and reduces the risk of data inconsistencies or bugs.
Scalability: React.js is highly scalable and can be used to build applications of any size. It is particularly well-suited for building large-scale applications that require complex interfaces and frequent updates.
Community Support: React.js has a large and active community that provides extensive documentation, third-party libraries, and tutorials. This makes it easy for developers to get started with React.js and to find solutions to common problems.

Overall, React.js brought several significant improvements over traditional client-side scripting using vanilla JavaScript and libraries like jQuery, as well as over other JavaScript frameworks like Backbone.js, AngularJS, and Knockout.js. These improvements have made it easier for developers to build scalable, efficient, and maintainable web applications.

If you want to dig deeper into this transition that happened between previous tools and frameworks like React, I recommend this video by uidotdev.

How React Works Under the Hood

React is a JavaScript library that works by creating a virtual representation of the user interface, called the Virtual DOM. This virtual representation is a lightweight copy of the actual DOM, and it allows React to efficiently manage and update the user interface.

When a React component is created, React generates a corresponding Virtual DOM tree that represents the component's current state. The Virtual DOM tree is essentially a JavaScript object that describes the structure of the user interface, including all of the HTML elements, their attributes, and their children.

When the state of a React component changes, React updates the corresponding Virtual DOM tree to reflect the new state. The updated Virtual DOM tree is then compared with the previous Virtual DOM tree to identify the differences between the two.

React then generates a list of minimal updates that need to be made to the actual DOM to bring it in sync with the new Virtual DOM tree. These updates are then applied to the actual DOM, resulting in an updated user interface.

One of the key benefits of this approach is that it allows React to update the user interface efficiently, without having to redraw the entire page. This can result in significant performance improvements, especially for complex applications with many components and frequent updates.

Another benefit of using a Virtual DOM is that it makes it easier to build reusable components. By abstracting away the details of the actual DOM, React components can be more easily composed together to build complex interfaces.

Overall, React's Virtual DOM approach allows for efficient and scalable user interface development, and it has played a significant role in the popularity of React as a front-end development framework.

How to Build a React App

Cool, so now that we have a clear idea of what React is and the improvements it brings to web development, let's actually start building applications!

Build a React App from Scratch using Webpack and Babel

We're going to see many different options available, but first we're going to build one from scratch. This means we're going to manually install and configure all the dependencies React needs to actually work.

Keep in mind this is a rare approach to use at the moment, since most apps are created through scripts that quickly take care of all this boilerplate. But the idea here is to see and understand the different components that interact to make React work under the hood.

To build a React app we'll need to install the 4 following dependencies:

Webpack: Webpack is a popular open-source module bundler for JavaScript applications. It takes multiple JavaScript files and their dependencies and packages them into a single optimized bundle for use in a web browser. It also has the capability to transform and bundle other types of assets such as CSS, images, and fonts.

Keep in mind that Webpack is just an option between many other available bundlers. We're going to use it because it's quite a standard option.

If you're interested in knowing more about JS modules and how to bundle them with Webpack, you can take a look at this article I wrote.

Babel: Babel is a popular open-source JavaScript compiler that allows developers to write code in the latest versions of JavaScript and translate it into code that can run on older browsers and environments. It supports the latest ECMAScript features and can also transpile other languages that compile to JavaScript, such as TypeScript and JSX.

Keep in mind Babel is just an option between many other available transpilers. We're going to use it because it's quite a standard option.

React: React is a JavaScript library for building user interfaces. It's focused on providing a declarative and efficient way to build complex UIs by breaking them into smaller, reusable components.

react-dom: React-DOM is a package that provides DOM-specific methods that React uses to interact with the browser's DOM (Document Object Model), such as rendering React components to the DOM, updating components, and handling user events.

So we have react and react-dom that provide the core functionalities of React, a bundler to unify all the different files into a few, and a transpiler to make our code compatible in most browsers. That's it. So now let's hop on to the code!

Start a node project by running this command in your terminal:

npm init -y

Install the following dependencies:

npm i webpack babel-loader @babel/preset-react @babel/core babel-preset-react html-webpack-plugin webpack-dev-server css-loader style-loader @babel/plugin-proposal-class-properties webpack-cli -D && npm i react react-dom -S

Here we're installing the 4 dependencies we previously mentioned and some extra plugins and stuff that help Webpack and Babel work.

Since we're doing this for theoretical foundation, we won't get too deep into these things. Just keep in mind the core dependencies are React's libraries, a bundler, and a transpiler (plus some other minor stuff).

If you're interested in a more detailed approach, you can take a look at this article.

Now create an SRC folder and two index.js and index.html files within it by running the next two commands:

mkdir src && cd src && touch index.js
touch index.html

Hop onto the index.html file and put this within it:




 
 My React App from Scratch

This is the single HTML file that will be present in our project. When we finally build it, this is the file that will be sent to the client. Initially it will be just like we coded it (almost empty), and then React will do its magic and render all the content through JavaScript.

Hop onto the index.js file and put this within it:

import ReactDOM from ‘react-dom’;
import React from ‘react’;
const App = () => {
 return This is my React app!;
 }
ReactDOM.render(, document.getElementById(‘app’));

Here we're creating a dummy component called App and telling react-dom to render it in the HTML element that has app as its id. See we just coded that element as a div in the previous step. ;)

Now we need to add some config files for Babel and Webpack. In your root directory run the following:

touch .babelrc && touch webpack.config.js

Inside your webpack.config.js file put the following:

const HtmlWebPackPlugin = require(“html-webpack-plugin”);
const htmlPlugin = new HtmlWebPackPlugin({
 template: “./src/index.html”,
 filename: “./index.html”
});
module.exports = {
mode: ‘development’,
  module: {
    rules: [{
   test: /\.js$/,
   exclude: /node_modules/,
   use: {
     loader: “babel-loader”
   }
 },
  {
   test: /\.css$/,
   use: [“style-loader”, “css-loader”]
  }
]},
 plugins: [htmlPlugin]
};

Inside your .babelrc file put the following:

{
 “presets”: [“@babel/preset-react”],
 “plugins”: [“@babel/plugin-proposal-class-properties”]
}

Finally, go to your package.json file and add the following within the scripts section:

"start": "webpack serve --config webpack.config.js"

At the end of all this, your file structure should look like this:

my-app-from-scratch/
┣ node_modules/
┣ src/
 ┣ index.html
 ┗ index.js
┣ .babelrc
┣ package-lock.json
┣ package.json
┗ webpack.config.js

And your package.json file should have this within it:

{
 “name”: “my-app-from-scratch “,
 “version”: “1.0.0”,
 “description”: “”,
 “main”: “webpack.config.js”,
 “scripts”: {
   “test”: “echo \”Error: no test specified\” && exit 1",
   "start": "webpack serve --config webpack.config.js"
},
 “keywords”: [],
 “author”: “”,
 “license”: “ISC”,
 “devDependencies”: {
 “@babel/preset-react”: “⁷.12.13”,
 “babel-core”: “⁶.26.3”,
 “babel-loader”: “⁸.2.2”,
 “babel-preset-react”: “⁶.24.1”,
 “css-loader”: “⁵.0.2”,
 “html-webpack-plugin”: “⁵.1.0”,
 “style-loader”: “².0.0”,
 “webpack”: “⁵.22.0”,
 “webpack-cli”: “⁴.5.0”,
 “webpack-dev-server”: “³.11.2”
 },
 “dependencies”: {
 “react”: “¹⁷.0.1”,
 “react-dom”: “¹⁷.0.1”
 }
}

Now if you run npm run start you should see your app coming alive! =D

What is CRA (create-react-app)?

As we've seen, setting up a React app from scratch is not THAT complicated. But it can be a pain in the butt to do all this every time you want to start a new project. Also, if you want some particular config for your bundler and transpilers, it can get tricky if you don't know your way around those tools.

And because of this problem, we got tools like Create-react-app (CRA). ;)

Create-React-App (CRA) is a popular and officially supported tool for creating React applications quickly and easily. It is a command-line interface (CLI) tool that automates the setup of a new React project by generating a basic file structure, configuration files, and build scripts.

CRA provides a streamlined development experience by setting up a preconfigured development server, live-reloading, and automatic build optimization for production. It also comes with a built-in tool for running tests and generating code coverage reports.

Using CRA, developers can create a new React application with a single command, without having to manually set up configuration files or install and configure build tools. This allows developers to focus on writing code and building their application, rather than spending time on setup and configuration.

CRA also provides a set of default project configurations, such as Webpack and Babel, which are optimized for creating React applications. This means that developers can get started quickly with a project that is optimized for performance, maintainability, and scalability.

Overall, Create-React-App is a powerful tool that simplifies the process of setting up and configuring a new React project.

How to build an app with create-react-app

Starting a React app with CRA is dead easy. We just run npx create-react-app and on its own it will set up all the boilerplate for us.

After it runs, your folder structure should look like this:

And your package.json should contain the following:

{
  "name": "testapp",
  "version": "0.1.0",
  "private": true,
  "dependencies": {
    "@testing-library/jest-dom": "^5.16.5",
    "@testing-library/react": "^13.4.0",
    "@testing-library/user-event": "^13.5.0",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-scripts": "5.0.1",
    "web-vitals": "^2.1.4"
  },
  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject"
  },
  "eslintConfig": {
    "extends": [
      "react-app",
      "react-app/jest"
    ]
  },
  "browserslist": {
    "production": [
      ">0.2%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  }
}

You might be wondering, well where are the Webpack and Babel things, right? Well, since CRA takes care of this stuff under the hood, they are initially hidden. If we want to see this hidden files and folders, we can run npm run eject.

You can now see that the folder structure has a few more things in it:

And your package.json file contains the whole list of dependencies:


  "name": "testapp",
  "version": "0.1.0",
  "private": true,
  "dependencies": {
    "@babel/core": "^7.16.0",
    "@pmmmwh/react-refresh-webpack-plugin": "^0.5.3",
    "@svgr/webpack": "^5.5.0",
    "@testing-library/jest-dom": "^5.16.5",
    "@testing-library/react": "^13.4.0",
    "@testing-library/user-event": "^13.5.0",
    "babel-jest": "^27.4.2",
    "babel-loader": "^8.2.3",
    "babel-plugin-named-asset-import": "^0.3.8",
    "babel-preset-react-app": "^10.0.1",
    "bfj": "^7.0.2",
    "browserslist": "^4.18.1",
    "camelcase": "^6.2.1",
    "case-sensitive-paths-webpack-plugin": "^2.4.0",
    "css-loader": "^6.5.1",
    "css-minimizer-webpack-plugin": "^3.2.0",
    "dotenv": "^10.0.0",
    "dotenv-expand": "^5.1.0",
    "eslint": "^8.3.0",
    "eslint-config-react-app": "^7.0.1",
    "eslint-webpack-plugin": "^3.1.1",
    "file-loader": "^6.2.0",
    "fs-extra": "^10.0.0",
    "html-webpack-plugin": "^5.5.0",
    "identity-obj-proxy": "^3.0.0",
    "jest": "^27.4.3",
    "jest-resolve": "^27.4.2",
    "jest-watch-typeahead": "^1.0.0",
    "mini-css-extract-plugin": "^2.4.5",
    "postcss": "^8.4.4",
    "postcss-flexbugs-fixes": "^5.0.2",
    "postcss-loader": "^6.2.1",
    "postcss-normalize": "^10.0.1",
    "postcss-preset-env": "^7.0.1",
    "prompts": "^2.4.2",
    "react": "^18.2.0",
    "react-app-polyfill": "^3.0.0",
    "react-dev-utils": "^12.0.1",
    "react-dom": "^18.2.0",
    "react-refresh": "^0.11.0",
    "resolve": "^1.20.0",
    "resolve-url-loader": "^4.0.0",
    "sass-loader": "^12.3.0",
    "semver": "^7.3.5",
    "source-map-loader": "^3.0.0",
    "style-loader": "^3.3.1",
    "tailwindcss": "^3.0.2",
    "terser-webpack-plugin": "^5.2.5",
    "web-vitals": "^2.1.4",
    "webpack": "^5.64.4",
    "webpack-dev-server": "^4.6.0",
    "webpack-manifest-plugin": "^4.0.2",
    "workbox-webpack-plugin": "^6.4.1"
  },
  "scripts": {
    "start": "node scripts/start.js",
    "build": "node scripts/build.js",
    "test": "node scripts/test.js"
  },
  "eslintConfig": {
    "extends": [
      "react-app",
      "react-app/jest"
    ]
  },
  "browserslist": {
    "production": [
      ">0.2%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  },
  "jest": {
    "roots": [
      "/src"
    ],
    "collectCoverageFrom": [
      "src/**/*.{js,jsx,ts,tsx}",
      "!src/**/*.d.ts"
    ],
    "setupFiles": [
      "react-app-polyfill/jsdom"
    ],
    "setupFilesAfterEnv": [
      "/src/setupTests.js"
    ],
    "testMatch": [
      "/src/**/__tests__/**/*.{js,jsx,ts,tsx}",
      "/src/**/*.{spec,test}.{js,jsx,ts,tsx}"
    ],
    "testEnvironment": "jsdom",
    "transform": {
      "^.+\\.(js|jsx|mjs|cjs|ts|tsx)$": "/config/jest/babelTransform.js",
      "^.+\\.css$": "/config/jest/cssTransform.js",
      "^(?!.*\\.(js|jsx|mjs|cjs|ts|tsx|css|json)$)": "/config/jest/fileTransform.js"
    },
    "transformIgnorePatterns": [
      "[/\\\\]node_modules[/\\\\].+\\.(js|jsx|mjs|cjs|ts|tsx)$",
      "^.+\\.module\\.(css|sass|scss)$"
    ],
    "modulePaths": [],
    "moduleNameMapper": {
      "^react-native$": "react-native-web",
      "^.+\\.module\\.(css|sass|scss)$": "identity-obj-proxy"
    },
    "moduleFileExtensions": [
      "web.js",
      "js",
      "web.ts",
      "ts",
      "web.tsx",
      "tsx",
      "json",
      "web.jsx",
      "jsx",
      "node"
    ],
    "watchPlugins": [
      "jest-watch-typeahead/filename",
      "jest-watch-typeahead/testname"
    ],
    "resetMocks": true
  },
  "babel": {
    "presets": [
      "react-app"
    ]
  }
}

Once again, if you run npm start you'll see your app coming alive. ;)

What is Vite?

CRA sounds pretty cool, right? It was a really helpful tool for React devs, since it brought a big improvement over building apps from scratch.

But the problem with create-react-app is it's kind of slow. Especially in large applications, that have thousands of lines of code and hundreds of components and files, tools like Webpack take a long time to bundle and build the application. This is the kind of problem that tools like Vite.js have come to solve.

For further info on why CRA is not the best building tool available today, I recommend this video and this video.

Vite.js is a build tool and development server that is designed to optimize the development experience for modern web applications. It was created by Evan You, the creator of the popular JavaScript framework Vue.js.

Vite.js is built on top of native ES modules, which allows for faster and more efficient module loading during development. This means that the development server can start up quickly and changes to the code can be reflected instantly in the browser, without the need for a full page reload.

Vite.js also includes a number of other features that are designed to streamline the development process. For example, it includes built-in support for TypeScript, CSS preprocessors, and hot module replacement. This allows for changes to be made to the code without the need for a full page reload.

Another key feature of Vite.js is its optimized production build process. Vite.js generates highly optimized production builds that leverage modern browser features such as code splitting, lazy loading, and tree shaking to reduce the size of the final bundle and improve performance.

Overall, Vite.js is a powerful and modern build tool that is designed to streamline the development process and improve performance for modern web applications. While it was originally designed for use with Vue.js, you can use it with other modern front-end frameworks such as React and Svelte.

Vite.js vs Create React App

Vite.js and Create React App (CRA) are both build tools and development servers that are designed to improve the development experience for React applications. While there is some overlap in their functionality, there are also some key differences between the two tools.

Some of the improvements that Vite.js brings over Create React App include:

Faster development server: Vite.js leverages native ES modules to provide a faster and more efficient development server. This means that changes to the code can be reflected instantly in the browser without the need for a full page reload. CRA, on the other hand, uses Webpack to power its development server, which can be slower and less efficient.
Faster build times: Vite.js generates highly optimized production builds that leverage modern browser features such as code splitting, lazy loading, and tree shaking to reduce the size of the final bundle and improve performance. This can result in significantly faster build times compared to CRA.
Support for other frameworks: While CRA is designed specifically for React applications, Vite.js can be used with other modern front-end frameworks such as Vue.js, Svelte, and others. This makes Vite.js a more versatile tool for front-end development.
Built-in support for TypeScript: Vite.js includes built-in support for TypeScript, which can simplify the development process for projects that use TypeScript.
Simplified configuration: Vite.js uses a simple and intuitive configuration format that makes it easy to get started with the tool. CRA, on the other hand, can require more complex configuration for some use cases.

Overall, Vite.js provides a number of improvements over Create React App in terms of performance, versatility, and ease of use. But both tools have their strengths and weaknesses, and the best tool for a particular project will depend on the specific requirements and constraints of that project.

How to build an app with Vite

To create a React app with Vite, go to your command line and run npm createvite@latest.

Then follow the prompts in your command line (it will ask you to provide the project name and the kind of template you'd like to start with). After selecting the options of using React and JavaScript, your folder structure should look somewhat like this:

See that it's quite similar to the one generated by CRA.

And this will be your package.json:

{
  "name": "vite-project",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  },
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  },
  "devDependencies": {
    "@types/react": "^18.0.27",
    "@types/react-dom": "^18.0.10",
    "@vitejs/plugin-react": "^3.1.0",
    "vite": "^4.1.0"
  }
}

To start your app, just run npm run dev and you're ready to go!

Vite is a great option for building React apps nowadays. It gives us all the simplicity and convenience that CRA gave us, plus some big optimizations over what CRA did. But one thing it doesn't have is out of the box support for SSR (server side rendering).

To understand why that matters, we're going to go through a brief explanation of what CSR (client side rendering) and SSR are, and in which situations one might be more beneficial than the other. And then we're going to take a look at two tools that actually provide support for SSR with React.

Client Side Rendering (CSR) vs Server Side Rendering (SSR)

Client-side rendering (CSR) and server-side rendering (SSR) are two approaches to rendering web pages in web development.

Client-side rendering involves generating HTML and rendering a web page entirely in the client's web browser using JavaScript.

In CSR, the client requests a minimal HTML file that includes links to JavaScript and CSS files. The client's browser then fetches the necessary files, executes the JavaScript, and updates the DOM to render the web page.

This approach is often used for single-page applications (SPAs) where the content is dynamically generated and changes frequently. Client-side rendering can provide a faster and more interactive user experience as the browser can update the UI without reloading the page.

Server-side rendering, on the other hand, involves generating the complete HTML of a web page on the server-side before sending it to the client's browser.

In SSR, the server processes the request, fetches the data, generates the HTML, and sends the fully-rendered HTML to the client. This approach is often used for content-heavy websites that require search engine optimization (SEO) or where the content changes infrequently.

Server-side rendering can provide a better initial loading speed and SEO as the search engine crawlers can read the complete HTML content.

The choice between CSR and SSR depends on the specific requirements and constraints of a project.

Client-side rendering might be more convenient for applications that require dynamic content and interactive user interfaces. On the other hand, server-side rendering might be more suitable for content-heavy websites that need to be SEO-friendly or for projects that require good initial loading times, especially for users with slow internet connections or older devices.

Some projects might even use a hybrid approach, where they combine both CSR and SSR to achieve the best of both worlds.

If you're interested in further exploring the many rendering options available in web development, you can refer to the article I recently wrote about rendering patterns.

SSR Building Tools

What is Astro?

Astro is a modern static site generator and web development framework that allows developers to build fast and efficient websites and web applications using a combination of server-side rendering and client-side rendering.

Astro uses a modular architecture that allows developers to mix and match different rendering strategies, allowing for maximum flexibility and performance.

For example, Astro supports server-side rendering (SSR) for initial page loads, which can improve performance and SEO, while also supporting client-side rendering (CSR) for subsequent interactions, which can provide a more interactive and dynamic user experience.

In addition to its flexible rendering capabilities, Astro also includes a number of other features that make it a powerful tool for web development. These include:

Built-in support for popular front-end frameworks such as React, Vue.js, and Svelte.
A powerful build system that is designed to optimize performance and minimize bundle sizes.
A flexible component model that allows developers to build reusable UI components and layouts.
A built-in development server and hot reloading that allows for fast and efficient development.
Support for a wide range of web technologies, including HTML, CSS, JavaScript, Markdown, and more.

Overall, Astro is a powerful and versatile tool for building modern static sites and web applications. Its flexible rendering model, powerful build system, and support for popular front-end frameworks make it a great choice for developers who want to build fast, efficient, and engaging web experiences.

How to build an app with Astro

To build an app with Astro we can run the command npm create astro@latest.

Then follow the prompts in your command line (it will ask you to provide the project name and the kind of template you'd like to start with). After completing that, your folder structure will look like this:

And this will be your package.json:

{
  "name": "satellite-series",
  "type": "module",
  "version": "0.0.1",
  "scripts": {
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "astro": "astro"
  },
  "dependencies": {
    "@astrojs/react": "^2.0.2",
    "@types/react": "^18.0.28",
    "@types/react-dom": "^18.0.11",
    "astro": "^2.0.17",
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  }
}

From the Astro docs we can see how the project structure works:

src/components: Components are reusable units of code for your HTML pages. These could be Astro components, or UI framework components like React or Vue. It is common to group and organize all of your project components together in this folder. src/layouts: Layouts are a special kind of component that wrap some content in a larger page layout. These are most often used by Astro pages and Markdown or MDX pages to define the layout of the page. Just like src/components, this directory is a common convention but not required. src/pages: Pages are a special kind of component used to create new pages on your site. A page can be an Astro component, or a Markdown file that represents some page of content for your site. src/pages is a required sub-directory in your Astro project. Without it, your site will have no pages or routes! src/styles: It is a common convention to store your CSS or Sass files in a src/styles directory, but this is not required. As long as your styles live somewhere in the src/ directory and are imported correctly, Astro will handle and optimize them. public/: The public/ directory is for files and assets that do not need to be processed during Astro’s build process. These files will be copied into the build folder untouched. This behavior makes public/ ideal for common assets like images and fonts, or special files such as robots.txt and manifest.webmanifest. You can place CSS and JavaScript in your public/ directory, but be aware that those files will not be bundled or optimized in your final build.

As you can see, Astro adds features on top of what React offers (like bundling optimization, Astro components, and out-of-the-box routing). This is what people call a "metaframework" (we'll take a closer look at that later on).

If you'd like to get a more detailed overview of how Astro works, I recommend you check out their docs. They're really well-written and easy to follow.

What is Gatsby?

Gatsby is a modern web framework based on React that allows developers to build fast, dynamic websites and applications using the latest web technologies. It was initially released in 2015 by Kyle Mathews, and has since grown to become one of the most popular static site generators and web frameworks in the world.

One of the main characteristics of Gatsby is its focus on performance and speed. Gatsby uses a technique called pre-rendering to generate static HTML, CSS, and JavaScript files that can be served to users almost instantly, resulting in a faster and more responsive user experience.

Also, Gatsby's use of React.js allows developers to create highly dynamic and interactive web applications that feel like native apps.

Gatsby also offers a powerful plugin system that makes it easy to add new features and functionality to your website or application. Gatsby plugins can help with everything from optimizing images and improving performance to integrating with external services and databases.

Some of the pros of using Gatsby include:

Fast and responsive user experience: Gatsby's use of pre-rendering and React.js makes for a highly performant and responsive user experience.
Large and active community: Gatsby has a large and active community of developers and contributors, which means there are plenty of resources and support available.
Plugin system: Gatsby's plugin system makes it easy to add new features and functionality to your website or application without having to write custom code.
Integration with external services: Gatsby can easily integrate with external services and databases, making it a good choice for applications that need to access and process data from a variety of sources.

Some of the cons of using Gatsby include:

Steep learning curve: Gatsby can be complex and difficult to learn for developers who are new to React or web development in general.
Limited server-side rendering: Gatsby's use of pre-rendering means that it may not be the best choice for applications that require extensive server-side rendering.
Static site limitations: Because Gatsby generates static files, it may not be the best choice for applications that require frequent database updates or real-time data.

Gatsby is a good choice for a wide variety of web applications, including blogs, e-commerce sites, marketing sites, and other content-driven websites. It is particularly well-suited for applications that require fast page loads and a highly performant user experience, as well as applications that need to integrate with external services and databases.

How to build an app with Gatsby

To initiate a Gatsby project, run npm init gatsby and follow the CLI prompts.

Your folder structure might look something like this:

Within the pages folder we have a file for each of the site's pages. Gatsby works with out-of-the box routing just like Astro.

A typical React front-end application project that uses Gatsby.js as the static site generator will have the following structure:

src/ folder: This folder contains all the source code of the application. It usually includes sub-folders for pages, components, images, styles, and data.
gatsby-config.js: This file contains the configuration settings for Gatsby. It includes metadata such as the site title, description, and author, as well as settings for plugins and other features.
public/ folder: This folder contains the compiled static assets that Gatsby generates when the site is built. These assets can be deployed to a web server or CDN.

React's Metaframeworks

React's metaframeworks are high-level frameworks that provide additional abstractions and functionality on top of the React library.

They are designed to simplify the development of complex applications and provide additional features and functionality that are not available in the React library alone.

Some examples of React.js metaframeworks include:

Next.js: Next.js is a metaframework that provides server-side rendering, automatic code splitting, and simplified client-side routing. It also includes built-in support for static site generation, API routes, and other advanced features.
Remix: Remix is a metaframework for building server-rendered React applications. It provides a unified data management system, a simple and intuitive routing system, and other features that can simplify building complex web applications. Remix aims to improve developer productivity by providing a simpler, more streamlined development experience for building large, complex web applications.

Overall, React.js metaframeworks provide powerful abstractions and functionality that can simplify the development of complex applications and help developers to build high-quality, efficient, and maintainable code.

Side comment: Astro and Gatsby might be considered metaframeworks as well. I just put them in a different section to introduce what SSR is, and also considering that Next and Remix provide more extra features on top of React than the other two.

What is Next.js?

Next.js is a popular metaframework for building server-side rendered (SSR) React applications. It is an open-source project developed by Vercel (formerly Zeit) and has gained popularity due to its ease of use, performance, and flexibility.

Next.js provides a number of features out of the box, such as automatic code splitting, server-side rendering, and hot module replacement. It also has built-in support for various front-end features, including client-side routing, static file serving, and API routes.

One of the main advantages of Next.js is its support for server-side rendering, which can improve the performance and SEO of web applications. With Next.js, the initial HTML is generated on the server, which can then be quickly hydrated with JavaScript on the client side.

If you wander what "hydration" means, again you can refer to the article I wrote about rendering patterns. ;)

Next.js also supports static site generation, where pages can be pre-built and served statically for faster performance and reduced server load. This feature makes it easy to build fast, scalable, and SEO-friendly sites with Next.js.

In addition to these features, Next.js has a large and active community that provides many plugins and tools to extend its functionality. It is also designed to be easy to use, with a simple setup process and a well-documented API.

Another interesting thing to mention is that the Next developer team works hand-in-hand with the React developer team, so both the Next framework and the React library are very well integrated and take advantage of each other's latest features.

Overall, Next.js is a powerful and flexible tool for building modern web applications with React. Its support for server-side rendering and static site generation make it a popular choice for developers looking to optimize their web applications for performance and SEO.

How to build an app with Next.js

To create a Next app, we can run the following command: npx create-next-app@latest . Then follow the prompts in your command line.

Your folder structure might look something like this:

A typical React front-end application project that uses Next.js as the framework will have the following structure:

pages/ folder: This folder contains all the pages of the application. Each file in this folder represents a route in the application, and the file name corresponds to the route path. For example, a file named index.js represents the root route (/), and a file named about.js represents the /about route.
public/ folder: This folder contains the static assets that are served directly by the web server, such as images, videos, and fonts.
styles/ folder: This folder contains all the styles of the application. It includes global styles, such as the font family and color scheme, as well as component-specific styles.
next.config.js: This file contains the configuration settings for Next.js. It can be used to customize features such as webpack, CSS, and image handling.

For a deeper dive into how Next works, refer to their awesome docs.

What is Remix?

Remix is a metaframework for building server-rendered React applications. It is an open-source project developed by the team at Remix Software, and it aims to provide a simpler and more unified approach to building server-rendered React applications.

One of the main features of Remix is its focus on code splitting and lazy loading. It automatically code splits your application into small chunks that are loaded on demand. This can improve performance and reduce the initial load time of your application.

Remix also provides a unified data management system, which makes it easy to manage the data your application needs to function. With Remix, you can define your data requirements in one place and fetch them on the server or client as needed.

Another key feature of Remix is its routing system, which is designed to be simple and intuitive. You can define your routes using a declarative API, and Remix will automatically generate the necessary code to handle client-side and server-side rendering.

Remix also provides built-in support for authentication, authorization, and other common web application features. It is highly extensible, with a plugin system that makes it easy to add custom functionality to your application.

Overall, Remix is a powerful and flexible metaframework for building server-rendered React applications. Its focus on code splitting, data management, and routing make it easy to build fast, scalable, and maintainable applications.

How to build an app with Remix

To create a Remix app, we can run the following command: npx create-remix@latest Then follow the prompts in your command line.

Your folder structure might look something like this:

A typical React front-end application project that uses Remix as the framework will have the following structure:

public/: This directory contains the publicly accessible files of the application, such as the index.html file and other assets like images, fonts, etc.
app/: This directory contains the source code of the application.
routes.js: This file defines the routes of the application and maps them to the corresponding page components.
remix.config.js: This file contains configuration options for Remix.js, such as setting up server-side rendering and defining routes.

For a deeper dive into how Next works, refer to their docs.

Wrapping Up

There are several popular React.js build tools available, each with its own unique set of features and advantages.

Here is a comparison of the main characteristics, pros, and cons of five popular React.js build tools: create-react-app, Vite, Astro, Gatsby, Next.js, and Remix.

create-react-app:

Characteristics: A command-line tool that sets up a basic React application with a simple file structure and build process.
Pros: Easy to use, with a simple setup process and no configuration required. Provides a good starting point for new React projects.
Cons: Limited flexibility and customization options. May not be suitable for larger or more complex projects.
Best for: Small to medium-sized projects with straightforward requirements.

Vite:

Characteristics: A fast build tool that leverages modern browser features to provide fast development and build times.
Pros: Extremely fast, with instant hot module replacement and other optimizations for faster builds. Supports a wide range of front-end frameworks and technologies.
Cons: Less mature than some other tools, with a smaller community and fewer available plugins.
Best for: Modern, fast-paced development workflows with a focus on speed and efficiency.

Astro:

Characteristics: A static site generator that can be used with React and other front-end frameworks.
Pros: Extremely fast, with a focus on generating static sites that can be deployed anywhere. Provides a simple, intuitive API for building static sites.
Cons: Less mature than some other tools, with a smaller community and fewer available plugins. May not be suitable for dynamic applications or complex routing needs.
Best for: Static sites or simple web applications that can be generated and served statically.

Gatsby:

Main characteristics: Gatsby is a popular static site generator that uses React to create fast and performant websites and applications. It includes a powerful plugin system for adding new features and functionality, and supports features like server-side rendering and data sourcing from a variety of APIs and databases.
Pros: Highly performant, powerful plugin system, good for content-driven websites and applications.
Cons: May be more limited in terms of dynamic data updates and real-time data.
Best for: Projects that require fast and performant content-driven websites or applications, or for developers who prefer a static site architecture.

Next.js:

Characteristics: A metaframework for building server-rendered React applications.
Pros: Provides built-in support for server-side rendering, static site generation, and other features that can improve performance and SEO. Has a large and active community with many available plugins and tools.
Cons: Can be more complex to set up and configure than some other tools. May not be suitable for smaller or simpler projects.
Best for: Large, complex web applications with complex routing, data management, or SEO requirements.

Remix:

Characteristics: A metaframework for building server-rendered React applications.
Pros: Provides a unified data management system, a simple and intuitive routing system, and other features that can simplify building complex web applications. Has a plugin system that makes it easy to add custom functionality to your application.
Cons: Less mature than some other tools, with a smaller community and fewer available plugins.
Best for: Large, complex web applications with complex data management, routing, or other requirements.

Overall, the best choice of React.js build tool depends on the specific needs of your project.

For small to medium-sized projects with straightforward requirements and fast-paced development workflows with a focus on speed and efficiency, Vite may be the best choice due to its simplicity and ease of use.

For static sites or simple web applications that can be generated and served statically, Astro may be the best choice.

And for larger, more complex projects with complex routing, data management, or SEO requirements, Next.js may be a better choice.

Well everyone, that's all for today. As always, I hope you enjoyed the article and learned something new.

If you want, you can also follow me on LinkedIn or Twitter. See you in the next one!

Different Types of APIs – SOAP vs REST vs GraphQL

German Cocca — Tue, 07 Mar 2023 23:24:27 +0000

Hi everyone! In this article we're going to take a good look at APIs, a core concept in modern software development.

We're going to talk about the main kinds of APIs used nowadays (SOAP, REST and GraphQL), their characteristics, pros and cons, and situations in which each of them might be more beneficial.

Let's go! 🙃

How SOAP APIs Work
- About XML
- How to Consume a SOAP API
How REST APIs Work
- How to Consume a REST API
How GraphQL APIs work
- How to Consume a GraphQL API
Wrapping Up

Intro

In a recent article I talked briefly about two very important concepts in modern software development: the client-server model and APIs.

Client-server is a model that structures the tasks or workloads of an application between a resource or service provider (server) and a service or resource requester (client).

Put simply, the client is the application that requests some kind of information or performs actions, and the server is the program that sends information or performs actions according to what the client does.

Most applications nowadays use a client-server model. The most important concept to remember about it is that clients request resources or services that the server performs. The way in which these two parts usually communicate is through an API (application programming interface).

An API is nothing more than a set of defined rules that establishes how one application can communicate with another. It's like a contract between the two parts that says "If you send A, I'll always respond B. If you send C, I'll always respond D..." and so on.

Having this set of rules, the client knows exactly what it has to require in order to complete a certain task, and the server knows exactly what the client will require when a certain action has to be performed.

APIs are absolutely everywhere in current software development. Almost any kind of application will use a client-server model enabled by API communication. That's why I think it's a very good idea for us as developers to get to know them well.

The most popular ways to implement APIs nowadays are REST and GraphQl. We'll also take a look at SOAP, which was quite popular some years ago and is still used in some niche sectors.

If you'd like a deeper intro to what APIs are, here's an awesome video about it.

With all this in mind, let's get into the details of how SOAP, REST and GraphQL APIs work.

How SOAP APIs Work

Simple Object Access Protocol (SOAP) is a messaging protocol used for exchanging structured data between different systems over the internet. SOAP is an XML-based protocol and is considered one of the earliest web service protocols.

SOAP was first introduced in 1998 by Microsoft as a successor to Common Object Request Broker Architecture (CORBA) and Distributed Component Object Model (DCOM).

SOAP was designed to provide a platform-independent way to exchange data between different systems over the internet. SOAP was later standardized by the World Wide Web Consortium (W3C) in 2003.

Main Characteristics:

Protocol-Independent: SOAP is designed to work with any protocol that supports the transmission of messages over the internet, including HTTP, SMTP, and FTP.
Platform-Independent: SOAP is designed to work with any programming language or platform that supports XML and can send and receive HTTP messages.
Messaging: SOAP is a messaging protocol and defines a set of rules for exchanging structured data between different systems.
Security: SOAP supports several security standards, including encryption, digital signatures, and authentication.
Extensibility: SOAP allows for the creation of custom extensions to the protocol to support specific requirements.

Pros:

Standardization: SOAP is a well-established and standardized protocol, making it a reliable choice for exchanging data between different systems.
Security: SOAP provides built-in support for several security standards, making it a secure choice for transmitting sensitive data.
Extensibility: SOAP is highly extensible and allows for the creation of custom extensions to support specific requirements.

Cons:

Complexity: SOAP can be complex to implement and may require specialized expertise.
Overhead: SOAP messages can be large and can require significant processing resources, resulting in increased overhead.
Performance: SOAP can be slower compared to other API protocols due to its messaging nature.

Best for:

When you need to transmit sensitive data: SOAP supports several security standards, making it a secure choice for transmitting sensitive data.
When you need to support complex data structures: SOAP supports complex data structures, making it a good choice for transmitting and exchanging data between different systems.
When you need a reliable and standardized protocol: SOAP is a well-established and standardized protocol, making it a reliable choice for exchanging data between different systems.

SOAP APIs were widely used in the early days of web services and are still used in several industries and sectors today, although REST and GraphQL have become more popular in recent years.

Here are some industries, sectors, and types of applications in which SOAP is still the main option:

Healthcare: SOAP is still widely used in healthcare applications, especially in electronic health records (EHR) and health information exchanges (HIE). This is because SOAP provides a secure and reliable way to transmit sensitive patient information between different systems.
Finance: SOAP is still used in financial applications, such as payment gateways and trading platforms, because it provides a secure and reliable way to transmit financial data.
Enterprise applications: SOAP is still used in enterprise applications, such as customer relationship management (CRM) and enterprise resource planning (ERP) systems, because it provides a standardized and reliable way to exchange data between different systems.
Legacy systems: Many older systems and applications still use SOAP APIs, and it can be costly and time-consuming to migrate them to newer technologies.

In conclusion, SOAP APIs have been around for a long time and are still used in several industries to exchange data between different systems.

SOAP might be the most beneficial option for developing an API when you need to transmit sensitive data, support complex data structures, or need a reliable and standardized protocol.

About XML

As mentioned, SOAP APIs use XML as the main format for data transmission, so let's explain how XML works.

XML stands for Extensible Markup Language. It is a markup language that allows users to create custom tags and attributes to describe the structure and content of data.

XML uses a set of rules for encoding documents in a format that is both human-readable and machine-readable. This is achieved by using tags to define elements of a document, similar to HTML.

For example, an XML document may have a tag called to define an element representing a person, with nested tags for properties such as , , and

. XML also allows users to define custom tags to describe their data in a way that is specific to their needs.

XML is widely used in various industries, including finance, healthcare, and government. It is often used for data exchange between different applications and systems, as it provides a standardized way of representing data that can be easily parsed by computers. XML is also used for storing configuration files and metadata for various applications.

Overall, XML provides a flexible and extensible way of describing and exchanging data that can be easily processed by computers. However, its use has declined in recent years with the rise of more modern formats such as JSON and YAML, which are more lightweight and easier to use for many applications.

How to Consume a SOAP API

Here's an example of how you can make a simple request to a SOAP API from a JavaScript front-end application:

// specify the URL of the SOAP API endpoint
const url = 'http://www.example.com/soap-api';

// specify the SOAP message to send
const soapMessage = '' +
                    '' +
                    '' +
                    '' +
                    '' +
                    '123' +
                    '' +
                    '' +
                    '';

// set the content type of the SOAP message
const contentType = 'text/xml';

// make the fetch request
fetch(url, {
  method: 'POST', // SOAP uses the HTTP POST method to send requests to a server.
  headers: {
    'Content-Type': contentType,
    'SOAPAction': 'http://example.com/GetData'
  },
  body: soapMessage
})
  .then(response => response.text())
  .then(xml => {
    // handle the XML response
    const parser = new DOMParser();
    const xmlDoc = parser.parseFromString(xml, 'text/xml');
    const value = xmlDoc.getElementsByTagName('Value')[0].childNodes[0].nodeValue;
    console.log(value);
  })
  .catch(error => console.error(error));

Let's break down what each line does:

const url = 'http://www.example.com/soap-api'; specifies the URL of the SOAP API endpoint.
const soapMessage = '' + ... specifies the SOAP message to send to the API endpoint. This is a string that contains the XML markup for the SOAP message.
const contentType = 'text/xml'; specifies the content type of the SOAP message.
fetch(url, { ... }) makes a fetch request to the API endpoint using the specified URL and options.
method: 'POST', specifies the HTTP method to use for the request.
headers: { ... } specifies the headers to include in the request.
'Content-Type': contentType, sets the content type of the request header to the value of contentType.
'SOAPAction': 'http://example.com/GetData' sets the SOAPAction header to the value of the SOAP action that corresponds to the API method being called.
body: soapMessage sets the body of the request to the value of soapMessage.
.then(response => response.text()) converts the response to text format.
.then(xml => { ... }) handles the response from the server.

A typical response might look like this:


<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Body>
      <ns1:GetDataResponse xmlns:ns1="http://example.com">
         <ns1:Result>
            <ns1:Id>123ns1:Id>
            <ns1:Value>42ns1:Value>
         ns1:Result>
      ns1:GetDataResponse>
   SOAP-ENV:Body>
SOAP-ENV:Envelope>

To access the values in the XML response, you can use the DOMParser API to parse the response into an XML document object, and then use DOM traversal methods to navigate the document and extract the values.

For example, the following code extracts the value of the Value element from the XML document object:

const parser = new DOMParser();
const xmlDoc = parser.parseFromString(xml, 'text/xml');
const value = xmlDoc.getElementsByTagName('Value')[0].childNodes[0].nodeValue;
console.log(value); // output: 42

Here's what each line does:

const parser = new DOMParser(); creates a new instance of the DOMParser object, which is used to parse the XML response.
const xmlDoc = parser.parseFromString(xml, 'text/xml'); parses the XML response into an XML document object.
const value = xmlDoc.getElementsByTagName('Value')[0].childNodes[0].nodeValue; retrieves the value of the Value element from the XML document object. This line uses the getElementsByTagName() method to get all elements with the tag name Value, and then accesses the first element (assuming there's only one), and gets the value of its first child node. The value is then assigned to the value variable.
console.log(value); // output: 42 logs the value of the Value element to the console.

Overall, SOAP responses tend to be more verbose and complex than responses from REST or GraphQL APIs, due to their use of XML and the envelope format. But this format provides a standardized way of exchanging information that can be useful in certain industries and use cases.

How REST APIs Work

Representational State Transfer (REST) is a widely used architectural style for building web services and APIs.

REST was first introduced in 2000 by Roy Fielding in his doctoral dissertation, "Architectural Styles and the Design of Network-based Software Architectures." Fielding, who was also one of the primary authors of the HTTP protocol, defined REST as an architectural style that is based on the principles of the web.

RESTful APIs are designed to be simple, scalable, and flexible. They are often used in web and mobile applications, as well as in Internet of Things (IoT) and microservices architectures.

Main Characteristics:

Stateless: REST APIs are stateless, which means that each request contains all the necessary information to process it. This makes it easier to scale the API and improves performance by reducing the need to store and manage session data on the server.
Resource-based: REST APIs are resource-based, which means that each resource is identified by a unique URI (Uniform Resource Identifier) and can be accessed using standard HTTP methods such as GET, POST, PUT, and DELETE.
Uniform Interface: REST APIs have a uniform interface that allows clients to interact with resources using a standardized set of methods and response formats. This makes it easier for developers to build and maintain APIs, and for clients to consume them.
Cacheable: REST APIs are cacheable, which means that responses can be cached to improve performance and reduce network traffic.
Layered System: REST APIs are designed to be layered, which means that intermediaries such as proxies and gateways can be added between the client and server without affecting the overall system.

Pros:

Easy to learn and use: REST APIs are relatively simple and easy to learn compared to other APIs.
Scalability: The stateless nature of REST APIs makes them highly scalable and efficient.
Flexibility: REST APIs are flexible and can be used to build a wide range of applications and systems.
Wide support: REST APIs are widely supported by development tools and frameworks, making it easy to integrate them into existing systems.

Cons:

Lack of standards: The lack of strict standards for REST APIs can lead to inconsistencies and interoperability issues.
Limited functionality: REST APIs are designed to handle simple requests and responses and may not be suitable for more complex use cases.
Security concerns: REST APIs can be vulnerable to security attacks such as cross-site scripting (XSS) and cross-site request forgery (CSRF) if not implemented properly.

Best for:

REST APIs are well-suited for building web and mobile applications, as well as microservices architectures and IoT systems.
They are particularly useful in situations where scalability and flexibility are important, and where developers need to integrate with existing systems and technologies.

While there are some limitations and concerns with REST APIs, they remain a popular and effective option for building APIs in many different industries and sectors.

How to Consume a REST API

Here's an example of how to make a simple GET request to a REST API from a JavaScript front-end application, and how to access the values within the response:

fetch('https://jsonplaceholder.typicode.com/todos/1')
  .then(response => response.json())
  .then(data => {
    console.log(data);
    // Access the values within the response here
  })
  .catch(error => console.error(error));

Here's what each line does:

fetch('https://jsonplaceholder.typicode.com/todos/1') initiates a GET request to the specified URL.
.then(response => response.json()) converts the response from JSON format to a JavaScript object.
.then(data => { ... }) defines a function that will be executed when the response has been successfully converted to a JavaScript object. This function will have access to the JavaScript object containing the response data.
console.log(data); logs the response data to the console. You can inspect the response data to determine how to access the values within the response.

To access the values within the response, you can use standard JavaScript object traversal techniques, such as dot notation or bracket notation. For example, if the response from the REST API is in the following format:

{
  "userId": 1,
  "id": 1,
  "title": "delectus aut autem",
  "completed": false
}

You can access the title value using dot or bracket notation like this:

console.log(data.title); // output: "delectus aut autem"
console.log(data['title']); // output: "delectus aut autem"

Here, data refers to the JavaScript object that contains the response data.

REST API responses are generally simpler and more lightweight than SOAP responses, and they are often formatted in either JSON or XML. The use of standard formats makes it easier for clients to parse the response and extract the relevant data.

Additionally, REST APIs often use standard HTTP status codes to indicate the success or failure of a request, which can simplify error handling on the client side.

Overall, REST APIs are a popular and widely used approach to building web APIs due to their simplicity, flexibility, and ease of use.

How GraphQL APIs Work

GraphQL is a query language and runtime for APIs that was developed by Facebook in 2012. It was released to the public in 2015 and has since gained popularity as an alternative to REST APIs.

Main Characteristics:

Strongly Typed: GraphQL APIs are strongly typed, which means that each field has a specific data type. This makes it easier to validate and handle data on the client and server sides.
Query Language: GraphQL has its own query language that allows clients to specify exactly what data they need. This reduces over-fetching of data and improves performance.
Single Endpoint: GraphQL APIs have a single endpoint, which means that clients can fetch all the data they need from a single request.
Declarative: GraphQL APIs are declarative, which means that clients specify what they want, not how to get it. This allows for more efficient and flexible data fetching.
Schema-Driven: GraphQL APIs are schema-driven, which means that the schema defines the structure of the data and the available queries and mutations. This makes it easier for developers to understand and work with the API.

Pros:

Efficient Data Fetching: GraphQL APIs allow clients to fetch only the data they need, reducing over-fetching and improving performance.
Strongly Typed: GraphQL APIs are strongly typed, making it easier to validate and handle data.
Single Endpoint: GraphQL APIs have a single endpoint, reducing the complexity of the API and making it easier to work with.
Schema-Driven: GraphQL APIs are schema-driven, which makes it easier for developers to understand and work with the API.

Cons:

Complexity: GraphQL APIs can be more complex to set up and work with compared to REST APIs.
Caching: Caching can be more challenging with GraphQL APIs due to the flexible nature of the API.
Learning Curve: GraphQL requires a learning curve for both developers and clients, as it has its own query language and approach to data fetching.

Best for:

Efficient and flexible needs: GraphQL is well-suited for building applications that require efficient and flexible data fetching, such as mobile and web applications.
Complex data requirements: It is particularly useful in situations where there are complex data requirements and where over-fetching data can cause performance issues.

In conclusion, GraphQL is a query language and runtime for APIs that provides efficient and flexible data fetching capabilities.

How to Consume a GraphQL API

Here's an example of how to make a simple request to retrieve information from a GraphQL API from a JavaScript front-end application, and how to access the values within the response:

fetch('https://api.example.com/graphql', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    query: `
      query {
        user(id: 123) {
          name
          email
          posts {
            title
          }
        }
      }
    `
  })
})
.then(response => response.json())
.then(data => {
  console.log(data);
  // Access the values within the response here
})
.catch(error => console.error(error));

Here's what each line does:

fetch('https://api.example.com/graphql', { ... }) initiates a POST request to the specified GraphQL API endpoint. The second argument to the fetch() function is an options object that specifies the HTTP method, headers, and request body.
method: 'POST' specifies that the HTTP method for the request is POST.
headers: { 'Content-Type': 'application/json' } specifies the Content-Type header for the request, which is application/json to indicate that the request body is in JSON format.
body: JSON.stringify({ ... }) specifies the request body as a JSON-encoded string. In this example, the request body is a GraphQL query that retrieves information about a user with the ID 123.
.then(response => response.json()) converts the response from JSON format to a JavaScript object.
.then(data => { ... }) defines a function that will be executed when the response has been successfully converted to a JavaScript object. This function will have access to the JavaScript object containing the response data.
console.log(data); logs the response data to the console. You can inspect the response data to determine how to access the values within the response.

{
  "data": {
    "user": {
      "name": "John Doe",
      "email": "john.doe@example.com",
      "posts": [
        { "title": "Post 1" },
        { "title": "Post 2" }
      ]
    }
  }
}

You can access the name value using dot or bracket notation like this:

console.log(data.data.user.name); // output: "John Doe"
console.log(data['data']['user']['name']); // output: "John Doe"

Here, data refers to the JavaScript object that contains the response data. The response data is wrapped in a data object, and the values can be accessed by traversing the object using dot notation or bracket notation.

GraphQL API responses are typically more focused and specific than REST API responses because the client can specify exactly what data they want to receive. This makes it easier to avoid overfetching or underfetching data, and can improve performance by reducing the amount of data transferred over the network.

Additionally, GraphQL APIs can provide a more flexible schema that can be easily modified over time without breaking existing clients. Overall, GraphQL APIs are a popular choice for building modern web applications due to their flexibility, efficiency, and ease of use.

Wrapping Up

Well everyone, as always, I hope you enjoyed the article and learned something new.

If you want, you can also follow me on LinkedIn or Twitter. See you in the next one!

Rendering Patterns for Web Apps – Server-Side, Client-Side, and SSG Explained

German Cocca — Mon, 06 Mar 2023 18:22:40 +0000

Hi everyone! In this article we're going to take a look at the different rendering pattern options available nowadays for web applications.

I'll start by explaining what a rendering pattern is, then go through each of the main options available. Finally we'll compare them, explaining the pros and cons and when one might be more beneficial than another.

Let's go!

What's a rendering pattern?
Different rendering pattern options
Comparing the different patterns
Wrap up

What's a Rendering Pattern?

In web development, a rendering pattern refers to the way in which the HTML, CSS, and JavaScript code is all processed and rendered in a web application or website.

Different rendering patterns are used to achieve different performance and user experience goals. The most common rendering patterns in web development are:

Server-side rendering (SSR): In SSR, the web server generates the HTML content of a web page on the server-side and sends it to the client's browser. This approach can improve initial loading times and SEO (search engine optimization) but can be slower for dynamic content.
Client-side rendering (CSR): In CSR, the client's browser generates the HTML content of a web page on the client-side using JavaScript. This approach can provide a fast and interactive user experience but can be slower for initial loading times and bad for SEO.
Static site generation (SSG): In SSG, the HTML content of a web page is generated at build time and served to the client as a static file. This approach can provide excellent performance and security but can be less flexible for dynamic content.

In summary, a rendering pattern is a strategy for processing and rendering web content in web development. The choice of rendering pattern depends on the specific needs and requirements of a project, such as performance, SEO, user experience, and flexibility.

Now that we have an idea of what a rendering pattern is, let's examine in detail the many options available nowadays.

Different Rendering Pattern Options

Static Websites

A static website is a type of website that consists of a set of HTML, CSS, and JavaScript files that are served to the client's browser without any server-side processing or database integration.

Static websites are typically created using static site generators, such as Jekyll, Hugo, or Gatsby.js. These generators compile templates, markdown files, or other data sources into a set of static files that are then deployed to a web server or content delivery network (CDN).

Static websites are often used for small to medium-sized websites that do not require complex dynamic features or server-side processing. They are easy to deploy, scale, and maintain, as they do not require a server-side application or database.

They also provide excellent security and performance, as the content is served directly from a web server or CDN without any server-side processing.

Static websites can be enhanced with client-side JavaScript, such as React or Vue, to provide interactive features or dynamic content. But any data that is required for these features must be loaded through client-side API requests, as there is no server-side processing to generate or retrieve the data.

In summary, a static website is a type of website that consists of a set of static files that are served to the client's browser without any server-side processing or database integration. They are simple, fast, secure, and scalable, and are suitable for small to medium-sized websites that do not require complex dynamic features or server-side processing.

Single Page Applications (SPAs) with Client Side Rendering (CSR)

A Single Page Application (SPA) is a type of web application rendered with Client-side rendering (CSR). This means that all necessary HTML, CSS, and JavaScript files are loaded at once when the user first loads the page. Then Javascript dynamically updates the content as the user interacts with the page, without requiring a full page reload.

In an SPA, the client-side JavaScript application is responsible for rendering the HTML and processing the user's interactions. The JavaScript application interacts with a backend API to retrieve data and update the user interface dynamically. Typically, this interaction is achieved using AJAX (Asynchronous JavaScript and XML) requests or Fetch API requests.

SPAs provide a fast and interactive user experience because only the necessary content is loaded and rendered dynamically, reducing the need for full page reloads. They also provide a more fluid user experience because the application can respond to user input without refreshing the entire page.

However, SPAs require a more complex setup and may have longer initial loading times compared to server-side rendering (SSR) or static site generation (SSG) approaches.

They also require additional considerations for search engine optimization (SEO) and accessibility, as search engines and assistive technologies may have difficulty indexing or navigating the content.

In summary, a Single Page Application (SPA) or Client-side rendering (CSR) is a type of web application that loads all necessary HTML, CSS, and JavaScript files at once and then dynamically updates the content as the user interacts with the page, without requiring a full page reload.

They provide a fast and interactive user experience but require a more complex setup and additional considerations for SEO and accessibility.

Server Side Rendering (SSR)

Server-side rendering (SSR) is a technique for rendering web pages on the server-side before sending them to the client's browser. In SSR, the server generates the HTML content of a web page based on the requested URL and data, and sends it to the client's browser as a complete HTML document.

SSR provides several benefits, including improved performance, better SEO, and more robust accessibility.

By rendering the HTML on the server-side, SSR reduces the amount of JavaScript code that needs to be loaded and executed on the client's browser. This results in faster initial loading times and better performance on low-end devices or slow networks.

Additionally, SSR enables search engines and social media crawlers to index the web pages more accurately, as the complete HTML content is available on the initial page load. This can improve the visibility and ranking of the website in search engine results pages.

SSR also ensures that the web pages are accessible to users with assistive technologies, such as screen readers or keyboard navigation, as the HTML content is available from the initial page load.

However, SSR has some limitations, such as increased server-side processing requirements and limited interactivity compared to client-side rendering (CSR) or single-page applications (SPAs).

In summary, Server-side rendering (SSR) is a technique for rendering web pages on the server-side before sending them to the client's browser. It provides improved performance, better SEO, and more robust accessibility, but requires more server-side processing and has some limitations in interactivity.

Static Site Generation (SSG)

Static site generation (SSG) is a technique for building web pages by pre-generating HTML, CSS, and JavaScript files at build time instead of rendering them on the server or client-side.

In SSG, a static site generator tool like Jekyll, Hugo, or Gatsby.js is used to compile the website's content from data sources such as markdown files, JSON files, or CMS data, and generate a set of static files that can be served directly to the browser without any server-side processing.

The generated static files can be deployed on a web server or a content delivery network (CDN) and served quickly to the end-users with low latency. SSG offers several benefits such as fast loading times, improved security, and scalability.

Since SSG renders web pages at build time, there is no need to generate pages dynamically on the server or client-side. This reduces the processing overhead and enables faster loading times.

Static sites are also less vulnerable to server-side attacks and require fewer server resources, making them more scalable and easier to maintain.

But SSG has some limitations in terms of dynamic content and interactivity. Since the content is generated at build time, any dynamic data or user interactions need to be handled by client-side JavaScript code or serverless functions.

In summary, Static Site Generation (SSG) is a technique for building web pages by pre-generating HTML, CSS, and JavaScript files at build time instead of rendering them on the server or client-side. It offers several benefits such as fast loading times, improved security, and scalability, but has some limitations in terms of dynamic content and interactivity.

Incremental Static Regeneration (ISR)

Incremental Static Regeneration (ISR) is a technique for building static sites that combines the benefits of both Server-Side Rendering (SSR) and Static Site Generation (SSG).

In ISR, the static site generator tool pre-generates a set of static pages at build time, but also includes additional metadata that enables the pages to be re-generated dynamically on the server-side when requested by the user. This metadata could include information such as expiration times or dependencies on specific data sources.

When a user requests a page that has expired or has dependencies that have changed, the server-side logic can regenerate the page with the updated content and serve it to the user, without requiring a full rebuild of the site.

This enables the site to maintain the benefits of static site generation, such as fast load times and low server processing overhead, while also allowing for dynamic content and personalized experiences for users.

ISR is particularly useful for sites that have content that changes frequently or for sites with a large number of pages that would be inefficient to rebuild in their entirety each time a change is made.

It allows for the best of both worlds: the performance and security benefits of static sites combined with the flexibility and personalization of server-side rendering.

In summary, Incremental Static Regeneration (ISR) is a technique for building static sites that combines the benefits of both Server-Side Rendering (SSR) and Static Site Generation (SSG). It allows for dynamic content and personalized experiences for users while maintaining the performance and security benefits of static sites.

The Concept of Hydration

In web development, "hydration" refers to the process of taking an HTML document that was initially rendered on the server and adding dynamic interactivity to it on the client-side.

Hydration is commonly used in Single-Page Applications (SPAs) that use client-side rendering (CSR).

During hydration, the browser parses the HTML document generated by the server and constructs a Document Object Model (DOM) tree, which represents the page's structure and content.

The browser then executes the JavaScript code that is responsible for adding dynamic behavior to the page, such as event handling, data fetching, and component rendering.

The JavaScript code retrieves the initial state and props of the components from the server-generated HTML and uses them to rehydrate the components on the client-side, effectively turning them into interactive elements.

This process ensures that the initial state of the page on the client-side matches the server-generated HTML and provides a seamless transition from the initial server-rendered view to the interactive client-side view.

Hydration is important for several reasons. First, it provides better performance and user experience by minimizing the time to interactive and enabling the user to interact with the page immediately.

Second, it enables search engine crawlers to access the page's content and metadata, improving SEO.

Finally, it ensures that the content is accessible and usable even if JavaScript is disabled in the user's browser.

In summary, hydration is the process of taking an HTML document that was initially rendered on the server and adding dynamic interactivity to it on the client-side.

It is commonly used in Single-Page Applications (SPAs) that use client-side rendering (CSR) and provides better performance, SEO, and accessibility.

Islands

The Islands pattern is a web development technique that involves breaking down a large, complex web page into smaller, self-contained components, each with its own HTML, CSS, and JavaScript code.

Each component is rendered independently on the server and is then rehydrated on the client-side, allowing it to become interactive.

The term "islands" refers to the individual components, each of which represents a separate island of content and functionality within the larger page.

By breaking the page into smaller islands, each with its own state and behavior, the application becomes more modular, easier to reason about and maintain, and can provide a more seamless user experience.

The Islands pattern is closely related to the concept of hydration because it relies on the same basic principle: rendering static HTML on the server and then hydrating it on the client-side with JavaScript to add interactivity.

In this case, each individual island is rendered on the server with its own static HTML, which is then hydrated on the client-side to enable dynamic functionality.

Hydration in the Islands pattern typically involves using a client-side framework or library to attach event handlers, manage state, and render dynamic content within each component. The framework or library must be capable of rehydrating the component on the client-side, ensuring that the initial state and behavior of the component matches that of the server-rendered HTML.

One benefit of using the Islands pattern with hydration is that it can improve the performance of large, complex web applications by reducing the amount of JavaScript that needs to be downloaded and executed on the client-side. By rendering each component independently on the server and rehydrating it on the client-side, the application can provide a more seamless user experience without sacrificing performance or scalability.

In summary, the Islands pattern is a web development technique that involves breaking down a large, complex web page into smaller, self-contained components, each with its own HTML, CSS, and JavaScript code. It relies on the same principle of hydration as other rendering patterns, rendering static HTML on the server and then adding interactivity with JavaScript on the client-side.

The Islands pattern can improve the performance and scalability of large web applications by reducing the amount of JavaScript that needs to be downloaded and executed on the client-side.

Streaming SSR

Streaming Server-Side Rendering (SSR) is a rendering pattern for web development that involves sending the server-generated HTML to the client as soon as it becomes available, rather than waiting for the entire page to be rendered before sending it.

With traditional SSR, the server would wait for the entire page to be rendered before sending it to the client, resulting in a longer time to first byte (TTFB) and a slower user experience.

Streaming SSR allows the server to send the HTML to the client in chunks as it is generated, providing a faster TTFB and a more responsive user experience.

Streaming SSR is particularly useful for rendering large or complex web pages that take a long time to render, such as e-commerce product pages or news articles.

With streaming SSR, the user can start interacting with the page as soon as the first chunk of HTML is received, without having to wait for the entire page to be rendered.

To implement streaming SSR, the server must use a technique called "chunking" to break the server-generated HTML into smaller chunks and send them to the client as they become available. The client then uses JavaScript to append each chunk of HTML to the page as it is received, effectively streaming the content to the user.

One challenge with streaming SSR is ensuring that the chunks of HTML are sent to the client in the correct order and that the page remains coherent as it is rendered.

To address this, developers may use techniques such as critical CSS, which involves identifying and rendering the most important styles first, or template-based chunking, which involves breaking the HTML into smaller chunks based on templates or components.

In summary, Streaming Server-Side Rendering (SSR) is a rendering pattern for web development that involves sending the server-generated HTML to the client in chunks as it is generated, providing a faster TTFB and a more responsive user experience. It is particularly useful for rendering large or complex web pages.

To implement streaming SSR, the server must use a technique called "chunking" to break the HTML into smaller chunks, and the client must use JavaScript to append each chunk to the page as it is received.

Comparing the Different Patterns

Awesome, so now we have a clear idea of each of the common options available. Let's now quickly go through the main characteristics of each pattern and mention the situations in which each of them might be more beneficial.

Static Websites

Main characteristics:

Pre-built HTML, CSS, and JavaScript files that are served to the client as-is.
No dynamic content, as all content is pre-rendered and does not change.
Fast load times due to the lack of server processing.

Pros:

Extremely fast load times and low server costs.
Great for sites with little to no dynamic content, such as portfolios or blogs.

Cons:

Limited interactivity and functionality, as all content is pre-rendered.
Not suitable for sites that require dynamic content or user input.

Best for:

Sites with limited dynamic content or sites that do not require dynamic functionality.

Single Page Applications (SPAs)

Main characteristics:

All content is dynamically rendered client-side through JavaScript.
Only a single page is loaded, with content updates handled by JavaScript.
Dynamic content can be easily added through APIs.

Pros:

High interactivity and functionality, as all content is dynamic and can be updated without refreshing the page.
Ideal for complex, data-driven applications that require frequent content updates.

Cons:

Slower initial load times due to the need to load JavaScript and dynamically render content.
Can be difficult to implement proper SEO techniques due to the lack of pre-rendered content.

Best for:

Applications that require complex interactivity or frequent content updates.

Server Side Rendering (SSR):

Main characteristics:

Server Side Rendering (SSR) is a process in which web pages are generated on the server and sent to the client as fully rendered HTML.
The server sends a complete HTML response to the client, which includes all the dynamic content, after processing the data on the server.

Pros:

Improved SEO because search engine crawlers can easily parse the complete HTML content.
Better performance because the initial HTML is sent in a single response, which reduces the time for the browser to load and display the content.
Works well for content-rich applications or dynamic web applications that require data to be fetched from APIs.

Cons:

Higher server overhead because every request is processed on the server.
More complex to set up because it requires a server-side framework that supports SSR.
Less interactive because interactions require additional server requests.

Best for:

Applications with content that changes frequently.
Applications with dynamic data that needs to be processed on the server before sending the response.

Static Site Generation (SSG):

Main characteristics:

Static Site Generation (SSG) is a process in which web pages are pre-built as static files during the build process and served to the client as static HTML pages.
The server sends static HTML pages to the client, which includes all the content, without processing any data on the server.

Pros:

Very fast and efficient because static pages can be served from a CDN or cache.
Lower server overhead because the server only needs to serve static files.
Can be deployed on a static file host or serverless environments like AWS Lambda.

Cons:

Not suitable for dynamic content that changes frequently.
Interactions require additional client-side JavaScript.

Best for:

Applications with mostly static content and few interactions.
Applications with limited interactivity.

Incremental Static Regeneration (ISR):

Main characteristics:

Incremental Static Regeneration (ISR) is a hybrid approach between SSG and SSR, where pages are pre-rendered as static HTML pages during the build process, and then the content is regenerated periodically or on-demand as required.

Pros:

Faster time-to-content because static pages are served initially, but content can be updated quickly.
Lower server overhead because static pages can be served from a CDN or cache, and dynamic content is regenerated only when required.

Cons:

Limited dynamic content because content regeneration requires a server request.
Requires a complex caching strategy to ensure that stale content is not served to clients.

Situations:

Applications with content that changes frequently but can tolerate some latency.
Applications with limited dynamic content.

Islands:

Main Characteristics:

The Island rendering pattern refers to rendering parts of the page on the server while other parts are rendered on the client-side.
The server renders the critical content, while the client fetches the rest of the content.
The server-side rendering can improve the initial page load speed and improve SEO.
The client-side rendering can improve the interactivity and reduce server overhead.

Pros:

Faster page load times because the server renders critical content while the client fetches the rest.
Works well for applications that require partial server-side rendering and partial client-side rendering.

Cons:

More complex to set up because it requires a hybrid framework that can support both server-side and client-side rendering.
May result in inconsistencies if the server and client render different versions of the content.

Best for:

Applications with dynamic content that require some server-side processing.
Applications that require a fast initial page load.

Streaming SSR:

Main Characteristics:

The server sends the HTML response in a streaming fashion, which enables the client to start rendering the content as soon as possible.
The client can see content being rendered progressively, which improves the user experience.

Pros:

Improved time-to-content because the client can start rendering the content while the server is still processing the request.
Better user experience because the client can see content being rendered progressively.

Cons:

More complex to set up because it requires a server framework that supports streaming.

Best for:

Applications with large pages or media that require a long time to load.
Applications that require a smooth user experience with minimal waiting time.

Wrap up

Well everyone, as always, I hope you enjoyed the article and learned something new.

If you want, you can also follow me on LinkedIn or Twitter. See you in the next one!

German Cocca - freeCodeCamp.org

Event-Based Architectures in JavaScript: A Handbook for Devs

Prerequisites: What you should already know

Table of Contents

1. Introduction

What Is an Event-Driven Architecture?

Why JavaScript Naturally Fits This Paradigm

Event-Driven vs. Request-Driven Architectures

When It Makes Sense to Use an Event-Driven Architecture

When It Might Not Be the Right Choice

Typical Business Use Cases

2. Fundamentals of the Event Model in JavaScript

The Event Loop, Task Queue, and Call Stack

EventEmitter and the Pub/Sub Pattern

EventTarget, CustomEvent, and Browser Events

Putting It All Together

3. Publisher–Subscriber (Pub/Sub) Pattern

Concept and Advantages of Decoupling

Basic Implementation in Plain JavaScript

Limitations and When to Use a Library

Summary

4. Implementations in Node.js

How to Use the Native events Module

Real Example: Event-Oriented Microservice

Error Handling and Backpressure

How to Build an Event Bus Across Services

Summary

5. Event-Driven Microservices Architecture

Asynchronous Communication via Message Brokers

Example: Order → Inventory → Notification Flow

Designing Event Contracts (Event Schemas)

When to Use an Event-Driven Microservice Architecture

Summary

6. Frontend Applications and Events

Custom Events in the Browser

Event Communication in Modern Frameworks

React Example

Vue Example

Real-Time Architectures: WebSockets and Server-Sent Events

WebSockets

Server-Sent Events (SSE)

Summary

7. Event Sourcing and CQRS (Command Query Responsibility Segregation)

Event Sourcing: The Core Idea

Example: Reconstructing State from Events

CQRS: Command Query Responsibility Segregation

Difference Between Event Sourcing and Pub/Sub

When to Use Event Sourcing and CQRS

Summary

8. Benefits and Challenges

Benefits of EDA

1. Scalability and Responsiveness

2. Loose Coupling and Extensibility

3. Resilience and Fault Isolation

4. Real-Time and Reactive Experiences

5. Auditability and Traceability

Challenges of EDA

1. Debugging and Tracing

2. Data Consistency

3. Message Duplication and Ordering

4. Operational Complexity

5. Team and Mental Model Shift

Summary

9. Real-World Use Cases

1. Financial and Banking Systems

Typical Events

How It Works

Benefits

2. E-commerce Platforms

Typical Events

Event Flow Example

Benefits

3. IoT and Sensor Networks

Typical Events

Event Flow Example

Benefits

4. Real-Time Analytics and Monitoring

Typical Events

Event Flow Example

Benefits

How to Use the Native `events` Module

`useValue`

`useClass`

`useFactory`