Building a Server with the http Module

HTTP is just text, so Node can speak it with a single built-in module. The Node.js for Beginners series now builds a real server from scratch: http.createServer, routing by method and path, JSON responses, and how to read a request body without blocking the loop. This is the machinery Express hides in chapter 12 — understanding it makes Express obvious.

Your first server

import http from 'node:http';

const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
  res.end('Hello from Node!');
});

server.listen(3000, () => {
  console.log('listening on http://localhost:3000');
});

node server.js
curl -s http://localhost:3000

Expected output:

listening on http://localhost:3000
Hello from Node!

Three things are worth noticing. listen starts a long-running process — the script does not exit, because the event loop now has a listening socket (exactly the "never exits" behaviour chapter 3 hinted at). The callback runs only once the port is actually bound. And the same file works with require('node:http') if your project is CommonJS — only the import line changes.

Reading the request

The req argument is an incoming message: method, URL, headers and a stream of body bytes. The res argument is where you write the reply.

const server = http.createServer((req, res) => {
  console.log(req.method, req.url, req.headers['user-agent'] ?? 'unknown');

  if (req.method === 'GET' && req.url === '/health') {
    res.writeHead(200, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify({ status: 'ok' }));
  } else {
    res.writeHead(404, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify({ error: 'not found' }));
  }
});

Expected output: a log line such as GET /health curl/8.7.1, and {"status":"ok"} at /health — with {"error":"not found"} plus a genuine 404 status everywhere else. This if/else ladder is routing; Express packages it as app.get('/health', handler).

A small JSON helper

Every API route repeats the same three lines — set status, set content type, serialise — so factor them once:

function sendJSON(res, status, payload) {
  const body = JSON.stringify(payload);
  res.writeHead(status, {
    'Content-Type': 'application/json; charset=utf-8',
    'Content-Length': Buffer.byteLength(body),
  });
  res.end(body);
}

// usage inside the request handler
sendJSON(res, 200, { todos: [], count: 0 });

Expected output: {"todos":[],"count":0}. Setting Content-Length explicitly is optional in modern Node (it computes it for you) but a useful habit when bodies are streamed — and it keeps HTTP/1.1 clients from waiting on a timeout.

Reading a request body

A body arrives in chunks on a stream; collect them, then parse. Because parsing can throw, guard it and answer 400 — never crash the process on bad client input.

if (req.method === 'POST' && req.url === '/api/todos') {
  const chunks = [];
  for await (const chunk of req) chunks.push(chunk);

  let todo;
  try {
    todo = JSON.parse(Buffer.concat(chunks).toString('utf8'));
  } catch {
    return sendJSON(res, 400, { error: 'invalid JSON' });
  }
  if (!todo?.title || typeof todo.title !== 'string') {
    return sendJSON(res, 422, { error: 'title is required' });
  }

  sendJSON(res, 201, { id: 1, title: todo.title, done: false });
}

Expected output: a valid POST replies {"id":1,"title":"...","done":false} with status 201; a malformed body replies {"error":"invalid JSON"} with 400. The for await loop is the same stream machinery you met in chapter 7 — top-level await inside a handler needs an async wrapper, which is one of several reasons Express's body parser is worth having.

Mapping methods to actions

Extracting the id from /api/todos/1 means string splitting, query strings mean URLSearchParams, and error handling means nested try/catch — three problems Express solved long ago, which is where this series goes next.

Common mistakes

• Never calling res.end() — the request hangs until the client times out; every path must end the response.
• EADDRINUSE — port 3000 is taken by a leftover process; kill it or pick another port.
• Crashing on bad input — JSON.parse throws; uncaught exceptions take the whole server down (chapter 9).
• Forgetting Content-Type — clients guess or refuse to parse the body.
• Manual path matching without normalising — /todos/ and /todos are different strings; decide a canonical form early.

Practice checklist

1. Start the server and hit it with curl -i; confirm your status line and headers.
2. Add a GET /about route returning JSON and verify the 404 fallback still works.
3. POST a valid and an invalid JSON body; confirm 201 versus 400 responses.
4. Log every request's method, URL and duration to the console as a mini access log.
5. Reproduce EADDRINUSE, then fix it two ways: kill the process and change the port.

The raw module works — now let a battle-tested framework carry the plumbing. Next: Getting Started with Express.