Back to Blog

Exploring Node.js: The First Concepts

February 15, 2025

1. Introduction to Node.js

🧑‍💻 What is Node.js?

Node.js is a server-side JavaScript runtime built on Google Chrome's V8 engine. It enables developers to write backend applications using JavaScript. Created by Ryan Dahl in 2009, its design emphasizes non-blocking, asynchronous execution, making it ideal for scalable, real-time applications.

Node.js uses an event-driven architecture to handle asynchronous I/O efficiently.

🌍 Use Cases

  • RESTful APIs: For fast, scalable APIs.
  • WebSockets: Real-time apps like chat or notifications.
  • CLI Tools: Create command-line utilities.
  • Microservices: Lightweight and process-efficient.

📦 Installation and First Commands

Install from Node.js official website.

Verify installation:

node -v  # Node.js version
npm -v   # npm version

2. Internal Mechanism

🔄 Event Loop

The event loop is the heart of Node.js, enabling non-blocking execution.

Phases of the event loop:

  1. Timers: Executes setTimeout/setInterval callbacks.
  2. I/O Callbacks: Handles I/O operations.
  3. Idle, Prepare: System preparation steps.
  4. Poll: Waits for new I/O events.
  5. Check: Executes setImmediate callbacks.
  6. Close Callbacks: Handles close events (e.g. server.close()).

Microtasks (like resolved promises, process.nextTick()) run between phases.

🧑‍🔧 Thread Pool (libuv)

Node.js uses libuv to delegate heavy tasks (like file I/O or CPU-bound work) to a thread pool, preventing the main event loop from blocking.

📁 Call Stack and Queues

  • Call Stack: Function execution stack.
  • Callback Queue: Holds asynchronous callbacks (e.g., setTimeout).
  • Microtask Queue: Promises and process.nextTick().
  • Task Queue: Regular tasks after microtasks.

3. Node.js Modules

🛠️ CommonJS vs ES Modules

  • CommonJS: require() and module.exports.
  • ES Modules: import/export, modern syntax.

Example (CommonJS):

// math.js
module.exports.add = (a, b) => a + b;

// app.js
const math = require('./math');
console.log(math.add(2, 3));

Example (ES Modules):

// math.mjs
export const add = (a, b) => a + b;

// app.mjs
import { add } from './math.mjs';
console.log(add(2, 3));

🛠️ Custom Modules

Every JavaScript file can be treated as a module. Organize logic into modules for clarity and reuse.

4. Core Node.js APIs

📂 Core Modules Overview

  • fs: File system operations.
  • http: Create HTTP servers/clients.
  • url: URL parsing/manipulation.
  • path: Path utilities.
  • os: OS-level info.
  • util: Utility functions.
  • querystring: Parse/query URL strings.

Example using http:

const http = require('http');

const server = http.createServer((req, res) => {
  res.statusCode = 200;
  res.setHeader('Content-Type', 'text/plain');
  res.end('Hello, World!');
});

server.listen(3000, '127.0.0.1', () => {
  console.log('Server running at http://127.0.0.1:3000/');
});

5. Asynchronous Programming

🔄 Callbacks, Promises, async/await

  • Callbacks: Functions executed after async operations.
  • Promises: Handle async values with .then()/.catch().
  • async/await: Syntactic sugar for promises.

const myPromise = new Promise((resolve) => {
  setTimeout(() => resolve('Success!'), 1000);
});

myPromise.then((result) => console.log(result));

async function fetchData() {
  const data = await myPromise;
  console.log(data);
}

⚠️ Error Handling

Use try/catch with async/await, or .catch() with promises.

6. Events and EventEmitter

📢 Creating an Event Emitter

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

myEmitter.on('event', () => {
  console.log('Event occurred!');
});

myEmitter.emit('event');

🌟 Event Hierarchy and Patterns

  • Emit multiple types of events.
  • Implements Observer and Pub/Sub patterns.

7. Native HTTP Server

🌐 Request Parsing

const http = require('http');

const server = http.createServer((req, res) => {
  console.log(req.url);
  res.statusCode = 200;
  res.setHeader('Content-Type', 'text/plain');
  res.end('Hello, HTTP!');
});

server.listen(3000, () => {
  console.log('Server running at http://localhost:3000/');
});

🔄 Basic Routing (No Express)

Manually check req.url and req.method to route requests.

8. Express.js & Middleware

🚀 Intro to Express

Express.js is a minimal web framework for Node.js.

🛠️ Define Routes and Middleware

const express = require('express');
const app = express();

app.use((req, res, next) => {
  console.log('Global middleware');
  next();
});

app.get('/', (req, res) => {
  res.send('Hello World!');
});

app.listen(3000);

📌 Advanced Routing with express.Router

Use routers to group routes by domain (e.g., user, auth).

9. Data Handling

📚 MongoDB with Mongoose

const mongoose = require('mongoose');

mongoose.connect('mongodb://localhost/mydb');

const UserSchema = new mongoose.Schema({
  name: String,
  age: Number,
});

const User = mongoose.model('User', UserSchema);

const user = new User({ name: 'Alice', age: 30 });
user.save().then(() => console.log('User saved!'));

10. Middleware and Authentication

🔐 JWT Auth Middleware

const jwt = require('jsonwebtoken');

function authenticateToken(req, res, next) {
  const token = req.headers['authorization'];
  if (!token) return res.status(401).send('Missing token');

  jwt.verify(token, process.env.TOKEN_SECRET, (err, user) => {
    if (err) return res.status(403).send('Invalid token');
    req.user = user;
    next();
  });
}

🔒 Using bcrypt for Hashing

const bcrypt = require('bcrypt');

async function hashPassword(password) {
  const salt = await bcrypt.genSalt(10);
  return await bcrypt.hash(password, salt);
}

💬 Sessions vs Tokens

  • Sessions: Stored on the server; uses cookies.
  • Tokens: Stateless, stored client-side.

11. Environment & Configuration

🌍 .env with dotenv

require('dotenv').config();
console.log(process.env.DB_HOST);

🧑‍💼 Detecting Environment

if (process.env.NODE_ENV === 'production') {
  console.log('Production');
} else {
  console.log('Development');
}

12. Dev & Build Tools

🛠️ Tools Overview

  • nodemon: Auto-restart on file changes.
  • eslint: Linting.
  • prettier: Code formatting.
  • husky: Git hooks.

nodemon server.js

🚀 TypeScript: ts-node, tsconfig.json

Use ts-node to run TS directly. Configure with tsconfig.json.

13. Testing & Code Quality

🔍 Testing with jest, mocha, supertest

  • jest: A popular testing framework with built-in support for unit tests, integration tests, and code coverage.
  • mocha: A flexible testing framework for Node.js.
  • supertest: Used to test HTTP routes.

Example with jest:

const request = require('supertest');
const app = require('./app');

test('GET /api/endpoint', async () => {
  const response = await request(app).get('/api/endpoint');
  expect(response.status).toBe(200);
  expect(response.body).toHaveProperty('data');
});

🔥 TDD (Test Driven Development)

TDD is a development approach where tests are written before the actual production code.

14. Security

🛡️ Helmet, rate-limiting, sanitization

  • helmet: Middleware that helps secure Express apps by setting various HTTP headers.
  • Rate limiting: Prevents abuse (e.g., DDoS attacks) by limiting the number of requests per user over a time period.
  • Sanitization: Cleans user input to prevent SQL injection, XSS, etc.

Example with helmet:

const helmet = require('helmet');
app.use(helmet());

15. Performance & Logging

🚀 Benchmarking with autocannon, wrk

Tools like autocannon and wrk simulate a high load of requests to benchmark server performance.

Example with autocannon:

autocannon http://localhost:3000

📊 Profiling with inspect and Chrome DevTools

Use Node.js's --inspect flag to profile your app and analyze performance via Chrome DevTools.

📝 Logging with Winston

Winston is a popular logging library for Node.js that helps you to log messages at different levels (e.g., info, warn, error) with flexible output formats and transport options. It’s highly configurable and allows you to write logs to multiple destinations, such as files, databases, or external services.

Key Features:

  • Log Levels: Default levels like info, warn, error, debug and more.
  • Transports: You can configure multiple transports (console, file, HTTP, etc.) to output logs to different destinations.
  • Log Formatting: Winston supports customizable formats, including JSON, to structure logs for easier analysis.
  • Performance: It handles logging asynchronously and can optimize performance with the use of buffering and different log levels.

Example Usage:

npm install winston

Then, in your Node.js app:

const winston = require('winston');

// Create a logger instance
const logger = winston.createLogger({
  level: 'info', // Set default log level
  transports: [
    new winston.transports.Console({
      format: winston.format.simple(),
    }),
    new winston.transports.File({ filename: 'combined.log' }),
  ],
});

// Log messages
logger.info('Info message');
logger.warn('Warning message');
logger.error('Error message');

Performance Considerations:

  • Async Logging: By default, Winston is non-blocking, so it won’t slow down your application during heavy logging. However, excessive logging in performance-critical code may still impact response times.
  • Log Rotation: To avoid large log files, configure log rotation with the winston-daily-rotate-file transport.

Winston helps improve application observability, making it easier to track, debug, and optimize the performance of your server-side code.

16. Project Architecture

🏛️ MVC, Hexagonal, Clean Architecture

Architectural patterns such as MVC, Hexagonal, and Clean Architecture help structure your codebase in layers, improving maintainability and testability.

MVC example:

  • Model: Handles data and business logic.
  • View: Displays data to users.
  • Controller: Connects user input and the model/view.

17. Creating a CLI with Node.js

💻 Reading command-line input with process.argv

process.argv is an array containing command-line arguments.

Example:

const args = process.argv.slice(2);
console.log(args); // Logs the passed arguments

🧰 Using commander, inquirer

  • commander: Helps build CLI tools with options and commands.
  • inquirer: Allows you to ask interactive questions via the terminal.

Example with commander:

const { program } = require('commander');
program.option('-v, --version', 'Show version');
program.parse(process.argv);

18. REST APIs & RESTful Design

🌐 What Is a RESTful API?

REST (Representational State Transfer) is an architectural style that uses standard web protocols like HTTP to structure communication between clients and servers.

A RESTful API is one that adheres to REST principles, ensuring simplicity, scalability, and statelessness in design.

📐 Core Principles of a RESTful API

1. Client-Server Architecture

Separation of concerns between client and server:

  • The client handles the UI and user interactions.

  • The server manages data, logic, and business rules.

This separation allows each side to evolve independently.

2. Statelessness

  • Each HTTP request must contain all information needed to process the request.

  • The server does not store any session or user state between requests.

  • Example: Include an authentication token in every request.

3. Cacheability

  • Resources should be cacheable to improve performance.

  • Use HTTP caching headers like Cache-Control, ETag, and Last-Modified.

4. Uniform Interface

A consistent interface simplifies communication:

  • Use standard HTTP methods (GET, POST, PUT, DELETE)

  • Resource-based URIs (/users, /orders/123)

  • Representation in standard formats (usually JSON)

  • Stateless interactions

5. Layered System

  • The API may be composed of multiple layers (e.g. proxy, gateway, authentication service), but clients only interact with the outermost layer.

  • This supports load balancing, caching, and security without client knowledge.

6. Code on Demand (Optional)

  • REST optionally allows servers to send executable code (e.g. JavaScript) to clients.

  • Rarely used in RESTful APIs, but still part of the original REST definition.

✅ HTTP Methods

Each HTTP verb corresponds to a CRUD operation:

  • GET: Retrieve a resource (read)
  • POST: Create a new resource
  • PUT: Update a resource entirely
  • PATCH: Partially update a resource
  • DELETE: Remove a resource

📬 Status Codes

Standardize client-server communication using HTTP status codes:

  • 200 OK: Request succeeded
  • 201 Created: Resource created successfully
  • 204 No Content: Request succeeded, no data to return
  • 400 Bad Request: Client-side error (e.g. validation)
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Authenticated, but not allowed
  • 404 Not Found: Resource does not exist
  • 500 Internal Server Error: Server-side error

🛣️ RESTful Routing Conventions

Use clear, resource-oriented URIs and use nouns, not verbs:

GET    /products          // Get all products
POST   /products          // Create a new product
GET    /products/:id      // Get product by ID
PUT    /products/:id      // Replace product
PATCH  /products/:id      // Partially update product
DELETE /products/:id      // Delete product

Avoid using verbs:

POST /getAllProducts
POST /updateUserInfo

🧩 RESTful API Example with Express

const express = require('express');
const app = express();
app.use(express.json()); // To parse JSON bodies

let users = [
  { id: 1, name: 'Alice' },
  { id: 2, name: 'Bob' },
];

// Get all users
app.get('/users', (req, res) => {
  res.status(200).json(users);
});

// Get a single user by ID
app.get('/users/:id', (req, res) => {
  const user = users.find((u) => u.id === parseInt(req.params.id));
  if (!user) return res.status(404).json({ error: 'User not found' });
  res.status(200).json(user);
});

// Create a new user
app.post('/users', (req, res) => {
  const newUser = {
    id: users.length + 1,
    name: req.body.name,
  };
  users.push(newUser);
  res.status(201).json(newUser);
});

// Update an existing user
app.put('/users/:id', (req, res) => {
  const user = users.find((u) => u.id === parseInt(req.params.id));
  if (!user) return res.status(404).json({ error: 'User not found' });

  user.name = req.body.name;
  res.status(200).json(user);
});

// Delete a user
app.delete('/users/:id', (req, res) => {
  users = users.filter((u) => u.id !== parseInt(req.params.id));
  res.status(204).send();
});

🧱 Best Practices for RESTful Design

  • Use plural nouns for endpoints: /users, /products, /orders
  • Use query parameters for filtering, sorting, and pagination:
    /users?sort=name&limit=10&page=2
  • Return consistent and structured responses (wrap data in a top-level key)
  • Implement versioning to avoid breaking changes:
    /api/v1/users
  • Validate and sanitize all user input to avoid security issues (e.g. SQL Injection, XSS)
  • Use tools like Postman or Insomnia for testing your endpoints

19. Real-time with WebSocket

⚡ WebSocket vs HTTP

WebSocket allows for real-time, bidirectional communication between client and server, unlike HTTP which is unidirectional.

Basic WebSocket server with ws:

const WebSocket = require('ws');
const wss = new WebSocket.Server({ port: 8080 });

wss.on('connection', (ws) => {
  ws.send('Hello Client');
  ws.on('message', (message) => {
    console.log(`Received: ${message}`);
  });
});

📡 Using socket.io

socket.io simplifies WebSocket communication and adds features like reconnection handling and event-based messaging.

20. Node.js in Production

⚙️ Process management with pm2

pm2 is a process manager for Node.js, useful for running and monitoring apps in production.

Example:

pm2 start app.js --name "my-app"
pm2 logs my-app

📊 Monitoring and Logs

pm2 also provides real-time logs and performance monitoring tools.

21. Deployment

🚀 Deploying on Render, Railway, Heroku, VPS

Node.js apps can be easily deployed on platforms like Render, Railway, and Heroku, with support for environment variables and scaling.

🛠️ CI/CD with GitHub Actions

Automate your build, test, and deployment pipeline using GitHub Actions.

22. TypeScript with Node.js

🔧 Using TypeScript

TypeScript adds static typing to Node.js applications, helping catch errors at compile time.

Setup example:

npm install typescript @types/node

23. Useful Libraries

📦 Libraries like axios, dotenv, uuid, etc.

  • axios: A promise-based HTTP client.
  • dotenv: Loads environment variables from a .env file.
  • uuid: Generates universally unique identifiers.

Example with axios:

const axios = require('axios');
axios
  .get('https://api.example.com')
  .then((response) => console.log(response.data))
  .catch((error) => console.error(error));

24. Best Practices

🛠️ Handle All Errors

  • Catch both synchronous and asynchronous errors.
  • Use try/catch in async/await and centralized error middleware with Express.
  • Prevent app crashes by handling unhandled promise rejections and uncaught exceptions.

process.on('unhandledRejection', (err) => {
  console.error('Unhandled rejection:', err);
});

process.on('uncaughtException', (err) => {
  console.error('Uncaught exception:', err);
});

📁 Organize Project Structure

  • Use a modular folder structure:

/src
  /controllers
  /routes
  /services
  /models
  /middlewares
  /utils

  • Separate concerns (logic, routes, validation, data access).

🔐 Secure Your Application

  • Sanitize inputs to prevent injections (use express-validator, DOMPurify, etc.).
  • Use helmet to set secure HTTP headers.
  • Avoid exposing sensitive data (e.g. .env, stack traces).
  • Always use HTTPS in production.

🧪 Write Unit and Integration Tests

  • Use testing frameworks like Jest, Mocha, or Vitest.
  • Cover core logic, API routes, and database behavior.
  • Example with Jest: 
    test('adds numbers', () => {
  expect(sum(1, 2)).toBe(3);
});

⚙️ Use Environment Variables

  • Store secrets and configs in a .env file and load with dotenv.
  • Never hardcode secrets (like DB passwords or API keys) in your code.

require('dotenv').config();
const dbUrl = process.env.DATABASE_URL;

📊 Use a Logger, Not console.log

  • Use libraries like winston or pino for structured logging.
  • Enable log levels (info, error, debug) and output to files or external log services.

const winston = require('winston');
const logger = winston.createLogger({
  level: 'info',
  transports: [new winston.transports.Console()],
});

🌀 Avoid Blocking the Event Loop

  • Offload CPU-heavy tasks to Worker Threads or child processes.
  • Avoid long for/while loops or large JSON parsing in the main thread.

🧰 Use Linters & Formatters

  • Enforce code style with ESLint and Prettier.
  • Add pre-commit hooks with husky + lint-staged.

npm install eslint prettier --save-dev

🧹 Clean and Consistent Code

  • Use async/await consistently.
  • Prefer const and let over var.
  • Extract magic values into constants or configs.
  • Use TypeScript or JSDoc for better type safety.

🧠 Use Middleware Smartly

  • Abstract repeated logic like auth, validation, error handling into reusable middleware.
  • Keep middleware thin and readable.

function authMiddleware(req, res, next) {
  if (!req.user) return res.status(401).send('Unauthorized');
  next();
}

⏱️ Graceful Shutdown

  • Handle SIGINT and SIGTERM to close server and DB connections properly before exit.

process.on('SIGINT', async () => {
  await db.disconnect();
  server.close(() => process.exit(0));
});

🚀 Performance Tips

  • Use compression middleware (compression) to reduce payload size.
  • Serve static files via CDN or reverse proxy (e.g. Nginx).
  • Use cluster or PM2 for multi-core usage in production.

🌍 Document Your API

  • Use tools like Swagger/OpenAPI, Postman, or Redoc.
  • Provide examples, request/response schemas, and error codes.

25. More Advanced Concepts

These concepts are essential for experienced developers who want to master Node.js in production environments, particularly in complex or large-scale architectures.

🧠 Worker Threads

Worker threads allow you to perform CPU-intensive operations in separate threads, preventing the main event loop from being blocked.

Example:

const { Worker } = require('worker_threads');

const worker = new Worker('./worker.js');
worker.on('message', (message) => console.log(message));
worker.postMessage('start');

🔄 Cluster Module

The cluster module enables you to create multiple Node.js processes (workers) to take advantage of multi-core processors. It allows you to distribute the load across multiple processes.

Example:

const cluster = require('cluster');
const http = require('http');
const numCPUs = require('os').cpus().length;

if (cluster.isMaster) {
  // Fork workers
  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();
  }

  cluster.on('exit', (worker, code, signal) => {
    console.log(`Worker ${worker.process.pid} died`);
  });
} else {
  http
    .createServer((req, res) => {
      res.writeHead(200);
      res.end('Hello World');
    })
    .listen(8000);
}

🚀 Streams: Readable, Writable, and Transform Streams

Streams provide an efficient way to handle data flows. Streams can be readable (input), writable (output), or transform (data modification while passing through).

Example of a readable stream:

const fs = require('fs');
const readableStream = fs.createReadStream('input.txt');

readableStream.on('data', (chunk) => {
  console.log('Data received: ', chunk);
});

Example of a transform stream:

const { Transform } = require('stream');

const uppercaseTransform = new Transform({
  transform(chunk, encoding, callback) {
    this.push(chunk.toString().toUpperCase());
    callback();
  },
});

process.stdin.pipe(uppercaseTransform).pipe(process.stdout);

🧩 Event Loop Optimization

Although Node.js' event loop is highly performant, it is possible to optimize it. Using asynchronous tasks or freeing up the event loop with techniques like process.nextTick(), setImmediate(), and timers can improve performance.

Example with setImmediate() to schedule execution:

console.log('Before');

setImmediate(() => {
  console.log('Inside setImmediate');
});

console.log('After');

🔐 Cryptography with Node.js

Node.js provides a set of cryptography APIs to implement features like hashing, encryption, and digital signatures.

Example of hashing with crypto:

const crypto = require('crypto');
const hash = crypto.createHash('sha256');
hash.update('Hello, world!');
console.log(hash.digest('hex'));

📈 Benchmarking with Node.js

Benchmarking allows you to measure the performance of your application. You can use tools like autocannon for HTTP load testing or profile your code with Chrome DevTools.

Example with autocannon to test performance:

autocannon http://localhost:3000

🔒 Security: OWASP Top 10 and Best Practices

Security in Node.js applications is critical. Here are some recommended practices to adhere to OWASP Top 10 guidelines:

  • SQL Injection: Use ORMs like Sequelize or Mongoose to prevent injections.
  • Cross-site Scripting (XSS): Sanitize user input to prevent the injection of malicious scripts.
  • Securing cookies and HTTP headers: Use modules like helmet.

Example of using helmet to secure an Express app:

const helmet = require('helmet');
const express = require('express');
const app = express();

app.use(helmet());

📡 Microservices with Node.js

Microservices allow you to split an application into smaller, independent parts, each responsible for a specific functionality. You can build microservices in Node.js using tools like Docker, Kubernetes, and exposing RESTful APIs or gRPC.

🔄 gRPC and Protocol Buffers

gRPC is a remote procedure call (RPC) framework developed by Google. It is based on Protocol Buffers for data serialization and is particularly useful in microservices environments for fast and reliable communication.

Example of defining a gRPC service with Protocol Buffers:

syntax = "proto3";

service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply);
}

message HelloRequest {
  string name = 1;
}

message HelloReply {
  string message = 1;
}

🛠️ Deploying with Docker

Using Docker with Node.js allows you to containerize your applications, making it easier to deploy and ensuring that the code runs consistently across all platforms.

Example of a Dockerfile for a Node.js application:

# Use official Node.js image
FROM node:16

# Create app directory
WORKDIR /app

# Copy necessary files
COPY package.json package-lock.json ./

# Install dependencies
RUN npm install

# Copy application code
COPY . .

# Expose port
EXPOSE 3000

# Run the application
CMD ["node", "app.js"]

📚 Further Reading & Official Resources

Here are some reliable sources to learn more about Node.js: