Node.js HTTP Server: http.createServer With Examples

http.createServer() creates a web server from one function, the request handler, which Node calls for every incoming request with two objects: req (the method, URL and headers the client sent) and res (what you send back). Set a status code and headers on res, then call res.end() with the body. server.listen(3000) starts accepting connections on port 3000.

const http = require('http');

const server = http.createServer((req, res) => {
    console.log(req.method, req.url);
    res.statusCode = 200;
    res.setHeader('Content-Type', 'text/plain');
    res.end(`You asked for ${req.method} ${req.url}`);
});

// GET /hello?name=Ada
server.listen(3000, () => {
    console.log('Listening on port 3000');
});

The first request answers You asked for GET /hello?name=Ada, and the Console logs the same method and URL. Send DELETE /anything from the request bar: the same handler answers it, because a plain http server has no routes. Every request goes through the one function.

Send JSON and set the status code

res.writeHead(status, headers) sets the status code and headers in one call. For JSON, set Content-Type: application/json and send the result of JSON.stringify(); res.end() only accepts a string or a Buffer.

const http = require('http');

const users = [
    { id: 1, name: 'Ada' },
    { id: 2, name: 'Linus' },
];

function sendJson(res, status, data) {
    res.writeHead(status, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify(data));
}

const server = http.createServer((req, res) => {
    const url = new URL(req.url, 'http://localhost');
    const limit = Number(url.searchParams.get('limit')) || users.length;

    if (req.method === 'GET' && url.pathname === '/users') {
        return sendJson(res, 200, users.slice(0, limit));
    }
    sendJson(res, 404, { error: 'Not found' });
});

// GET /users?limit=1
server.listen(3000);

GET /users?limit=1 returns [{"id":1,"name":"Ada"}]. req.url is the path plus the query string, so new URL(req.url, 'http://localhost') splits it into pathname and searchParams (the base is only there because URL needs an absolute address). Send GET /nothing and the status turns to 404.

Route requests with a switch

A small API needs nothing more than a switch on the method and path. Build a key such as 'GET /users' and give each route its own case:

const http = require('http');

const users = [{ id: 1, name: 'Ada' }];

function sendJson(res, status, data) {
    res.writeHead(status, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify(data));
}

function readBody(req) {
    return new Promise((resolve, reject) => {
        let data = '';
        req.on('data', (chunk) => {
            data += chunk;
        });
        req.on('end', () => resolve(data));
        req.on('error', reject);
    });
}

const server = http.createServer(async (req, res) => {
    const { pathname } = new URL(req.url, 'http://localhost');

    switch (`${req.method} ${pathname}`) {
        case 'GET /users':
            return sendJson(res, 200, users);

        case 'POST /users': {
            let body;
            try {
                body = JSON.parse(await readBody(req));
            } catch {
                return sendJson(res, 400, { error: 'Body must be JSON' });
            }
            const user = { id: users.length + 1, name: body.name };
            users.push(user);
            return sendJson(res, 201, user);
        }

        default:
            sendJson(res, 404, { error: `No route for ${req.method} ${pathname}` });
    }
});

// GET /users
server.listen(3000);

Send POST /users with the body {"name": "Grace"}: the answer is 201 with {"id":2,"name":"Grace"}, and GET /users now lists both users. Send the same POST with the body hello and you get 400 with {"error":"Body must be JSON"}.

Read a POST body

Node does not parse the body for you. req is a readable stream, and the body arrives in chunks through data events, then end fires once it is complete. readBody() above collects the chunks into a string and returns a promise, so the handler can await it. Since req is async iterable, this loop does the same job:

let data = '';
for await (const chunk of req) data += chunk;
const body = JSON.parse(data);

A real server also limits the size (stop reading and answer 413 once data.length passes a limit) and checks req.headers['content-type'] before calling JSON.parse.

Common mistakes

Forgetting res.end(). A branch that sets a status but never ends the response leaves the client waiting until it times out.

Setting a header after the body. Once res.end() or the first res.write() has run, the headers are sent, and res.setHeader() throws ERR_HTTP_HEADERS_SENT. Use return when you send a response early, as the examples do.

Comparing req.url with a path. req.url includes the query string, so req.url === '/users' is false for /users?limit=1. Compare pathname.

When to use Express instead

The http module is enough for a health check, a webhook receiver or learning how HTTP works. Once you need route parameters like /users/:id, JSON body parsing, middleware and error handling, you end up writing your own small framework. Express is that framework, built on the same req and res objects; Express routing shows the same API with app.get() and app.post().