DEV Community: Razvan

How to Build a Strawpoll-Like Voting System API with Node + Express

Razvan — Fri, 17 Oct 2025 14:55:54 +0000

Welcome back to Code in Action, the series where we build practical backend projects, step by step.

In this tutorial, we're going to build a simplified version of Strawpoll — the popular online service that lets users create quick polls, share them with others, and collect votes in real time.

Our API will include 3 endpoints:

A GET /poll/:id for retrieving polls.
A POST /poll/create for creating polls.
A POST /poll/vote for voting in polls.

Along the way, we'll implement an in-memory SQL-like database to store our data, and a schema validator middleware to ensure the data of every incoming HTTP request is clean and predictable.

Ready? Let's build!

Step 1: Set Up the Project

Let's create and enter the project's directory named strawpoll-lite.

mkdir strawpoll-lite
cd strawpoll-lite

Create the package.json file of the project.

npm init -y

And install both:

The express package for creating web servers.
The joi package for creating object validation schemas.

npm install express joi

Step 2: Create the Database Object

📚 A poll is a simple survey where users can choose one option from a list of possible choices, and each choice submitted by a user is recorded as a vote.

With that in mind, let's create a new file named database.js, that exports an object literal as an in-memory database, that will store the polls, their choices, and the user votes.

// File: database.js

module.exports = {
  _indexes: {
    polls: 1,
    choices: 1,
    votes: 1,
  },
  tables: {
    polls: [],
    choices: [],
    votes: [],
  },
};

Where:

tables is an object used to store poll, choice, and vote objects, each identified by an index, which is a unique, positive integer.
_indexes is an object used to keep track of the indexes in each table.

If you aren't familiar with SQL-like databases, a table is a related collection of records (or entries), where each record is individually identified by a unique property — usually an integer called an index.

This index is often defined as self-incrementing, which means that every time a new record is added to a table, its index value is incremented by 1.

To mimic this behavior, we'll manually use and update the corresponding _indexes property of each record type, every time we add a new one into its corresponding tables object.

Here's for example what the database object would look like if it contained 1 poll with 2 choices and 1 vote:

// File: database.js

module.exports = {
  _indexes: {
    polls: 2,
    choices: 3,
    votes: 2,
  },
  tables: {
    polls: [{
      id: 1,
      title: 'Which one tastes better?',
      closing_date: null,
      result_visibility: 'public',
    }],
    choices: [{
      id: 1,
      poll_id: 1,
      value: 'Pizza',
    }, {
      id: 2,
      poll_id: 1,
      value: 'Burger',
    }],
    votes: [{
      id: 1,
      poll_id: 1,
      choice_id: 2,
      user_name: 'Razvan',
      user_ip_address: '::ffff:127.0.0.1',
    }],
  },
};

Below is a breakdown of each record type.

The poll object

This object represents a poll.

{
  id: <integer>,
  title: <string>,
  closing_date: <timestamp|null>,
  result_visibility: <"public"|"public_end"|"public_vote"|"private">
}

Where:

id: The poll's index, derived from the database._indexes.polls property.
title: The poll's title.
closing_date: The optional poll's date and time in the Unix timestamp format after which participants cannot vote anymore.
result_visibility: The poll's vote results visibility, which can be either:
- "public" to always display the votes.
- "public_end" to display the votes once closing_date is past.
- "public_vote" to display the votes once the user has voted.
- "private" to keep the votes hidden.

For example:

{
  id: 1,
  title: 'Which one tastes better?',
  closing_date: null,
  result_visibility: 'public'
}

The choice object

This object represents a single choice related to a poll.

{
  id: <integer>,
  poll_id: <integer>,
  value: <string>
}

Where:

id: The choice's index, derived from the database._indexes.choices property.
poll_id: The poll's index.
value: The choice's text value.

For example:

{
  id: 1,
  poll_id: 1,
  value: 'Pizza',
}

The vote object

This object represents a vote for a choice.

{
  id: <integer>,
  poll_id: <integer>,
  choice_id: <integer>,
  user_name: <string>,
  user_ip_address: <string>
}

Where:

id: The vote's index, derived from the database._indexes.votes property.
poll_id: The poll's index.
choice_id: The choice's index.
user_name: The voter's username.
user_ip_address: The voter's IP address.

For example:

{
  id: 1,
  poll_id: 1,
  choice_id: 2,
  user_name: 'Razvan',
  user_ip_address: '::ffff:127.0.0.1',
}

💡 New to backend programming in Node.js?

Check out the Learn Backend Mastery Program — a complete zero-to-hired roadmap that takes you from complete beginner to job-ready Node.js backend developer in 12 months.

👉 learnbackend.dev

Step 3: Create the API Endpoints

Let's create a new file named server.js, and within it, write this minimal Express set up, where all the endpoints of the API will be attached to the pollRouter router instance and mounted to the /poll root path.

// File: server.js

const express = require('express');
const database = require('./database');

const server = express();
const pollRouter = express.Router();

// ...

server.use('/poll', pollRouter);

server.listen(3000);

Declare the GET /poll/:id endpoint

Let's declare a new HTTP GET endpoint responsible for retrieving an existing poll, that responds with an HTTP 501 Not Implemented for now.

// File: server.js

const express = require('express');
const database = require('./database');

const server = express();
const pollRouter = express.Router();

pollRouter.get('/:id', (req, res) => {
  res.sendStatus(501);
});

// ...

This endpoint takes a single route parameter named id, that is a positive integer corresponding to the id property of the poll object to retrieve from the database.

Declare the POST /poll/create endpoint

Let's declare a new HTTP POST endpoint responsible for creating a new poll, that uses the Express json() middleware to parse and convert the message body of incoming requests into JSON objects, and that responds with an HTTP 501 Not Implemented for now.

// File: server.js

const express = require('express');
const database = require('./database');

const server = express();
const pollRouter = express.Router();

pollRouter.get('/:id', (req, res) => {
  res.sendStatus(501);
});

pollRouter.post('/create', express.json(), (req, res) => {
  res.sendStatus(501);
});

// ...

The message body of incoming requests on this endpoint should have the following format:

{
  poll: {
    title: <string>
    closing_date: <timestamp|null>,
    result_visibility: <"public"|"public_end"|"public_vote"|"private">,
  },
  choices: [<string>],
}

Where:

poll.title: The poll's title. Must be a string of maximum 255 characters.
poll.closing_date: The date and time limit after which users cannot vote anymore. Must be a Unix timestamp or null.
poll.result_visibility: The vote's visibility. Must be either "public", "public_end", "public_vote", or "private". If the value is "public_end", the value of poll.closing_date must be non-null.
choices: The poll's choices. Must be an array of strings.

Declare the POST /poll/vote endpoint

Declare a new HTTP POST endpoint responsible for voting in an existing poll.

// File: server.js

const express = require('express');
const database = require('./database');

const server = express();
const pollRouter = express.Router();

pollRouter.get('/:id', (req, res) => {
  res.sendStatus(501);
});

pollRouter.post('/create', express.json(), (req, res) => {
  res.sendStatus(501);
});

pollRouter.post('/vote', express.json(), (req, res) => {
  res.sendStatus(501);
});

// ...

The message body of incoming requests on this endpoint should have the following format:

{
  choice_id: <integer>,
  user_name: <string>,
}

Where:

choice_id: The choice's index. Must be a positive integer.
user_name: The user's name. Must be a string of maximum 50 characters.

Step 4: Create the validation schemas

To validate and parse the parameters and message body of incoming HTTP requests, we'll use the Joi package to create a list of validation schemas, that will then be used by a custom middleware function to either reject invalid data or forward the request to the specified endpoint's controller.

Let's create a new file named schemas.js, and within it, let's:

Import the joi package.
Export an object literal that contains a property named after each endpoint.

// File: schemas.js

const Joi = require('joi');

module.exports = {
  getPoll: {},
  createPoll: {},
  votePoll: {},
};

For each of these objects, let's add a property derived from the properties of the request object of the endpoint's controller, indicating where the data to validate comes from, where:

params stands for route parameters
query stands for query string parameters
body stands for message body

// File: schemas.js

const Joi = require('joi');

module.exports = {
  getPoll: {
    params: null,
  },
  createPoll: {
    body: null,
  },
  votePoll: {
    body: null,
  },
};

Define the "get poll" schema

Let's assign to the getPoll.params property a Joi object with a single property named id that corresponds to the route parameter of the HTTP GET /poll/:id endpoint.

// File: schemas.js

const Joi = require('joi');

module.exports = {
  getPoll: {
    params: Joi.object({
      id: Joi.number()
        .integer()
        .min(1)
        .max(Number.MAX_SAFE_INTEGER)
        .required(),
    }),
  },
  // ...
};

Where:

id is a mandatory integer with a minimum value of 1 and a maximum value defined by the built-in MAX_SAFE_INTEGER constant.

Define the "create poll" schema

Let's assign to the createPoll.body property a Joi object that corresponds to the expected message body of the HTTP POST /poll/create endpoint.

// File: schemas.js

// ...

const minOneHourFromNow = (value, helpers) => {
  if (value == null) return value;

  const limit = new Date(Date.now() + 60 * 60 * 1000);

  if (new Date(value) < limit) {
    return helpers.error('date.min', { limit });
  }
  return value;
};

module.exports = {
  // ...
  createPoll: {
    body: Joi.object({
      poll: Joi.object({
        title: Joi.string()
          .max(255)
          .trim()
          .required(),
        closing_date: Joi.alternatives().conditional('result_visibility', {
          is: 'public_end',
          then: Joi.date()
            .custom(minOneHourFromNow, '>= 1h from now')
            .required(),
          otherwise: Joi.date()
            .custom(minOneHourFromNow, '>= 1h from now')
            .allow(null),
        }),
        result_visibility: Joi.string()
          .valid('public', 'public_end', 'public_vote', 'private')
          .default('public')
          .required(),
      }),
      choices: Joi.array()
        .items(Joi.string().trim().min(1))
        .min(1)
        .required(),
    }),
  },
  // ...
};

Where:

poll.title is a mandatory string of maximum 255 characters.
poll.closing_date is either a timestamp that's at least one hour away from now, and is mandatory if the value of the poll.result_visibility property is "public_end", or null otherwise.
poll.result_visibility is a mandatory string that's either "public", "public_end", "public_vote", or "private", and that defaults to "public".
choices is a mandatory array of strings of minimum 1 element of 1 character.

Note that the minOneHourFromNow() helper function is used to ensure that the votes of the newly created poll don't close before at least one hour from its creation time.

Define the "vote poll" schema

Let's assign to the votePoll.body property a Joi object that corresponds to the expected message body of the HTTP POST /poll/vote endpoint.

// File: schemas.js

// ...

module.exports = {
  // ...
  votePoll: {
    body: Joi.object({
      choice_id: Joi.number()
        .integer()
        .min(1)
        .max(Number.MAX_SAFE_INTEGER)
        .required(),
      user_name: Joi.string()
        .max(50)
        .required(),
    }),
  },
};

Where:

choice_id is a mandatory integer with a minimum value of 1 and a maximum value defined by the built-in MAX_SAFE_INTEGER constant.
user_name is a mandatory string of maximum 50 characters.

Step 5: Implement a validation middleware

Let's create a custom Express validation middleware that uses the Joi schemas we've just defined to validate and normalize the data of incoming requests on the various endpoints of our API and either:

Rejects the incoming request with an HTTP 400 Bad Request if any of the values doesn't match the format define by the corresponding schema.
Normalizes the values and forwards the request to the endpoint's controller.

Let's create a new file named schema-validator.js, and within it, let's:

Import the schemas module.
Declare a factory function that takes as parameters a configuration object and returns an Express middleware.

// File: schema-validator.js

const SCHEMAS = require('./schemas');

module.exports = (config) => (req, res, next) => {
  //
};

Where in the config object:

The schema property is the name of the schema to use, including getPoll, createPoll, and votePoll.
The source property is the name of the request's object property to check, including params for route parameters, query for query string parameters, and body for message body.

For example:

schemaValidator({ schema: 'getPoll', source: 'params' });
schemaValidator({ schema: 'createPoll', source: 'body' });
schemaValidator({ schema: 'votePoll', source: 'body' });

Within the middleware function, let's first respond with an HTTP 500 Internal Server Error if the specified name or source within the schemas doesn't exist.

// File: schema-validator.js

const SCHEMAS = require('./schemas');

module.exports = (config) => (req, res, next) => {
  let schema = SCHEMAS?.[config.schema]?.[config.source];

  if (!schema) {
    return res.status(500).json({ error: 'Validation schema unknown' });
  }
};

Invoke the validate() method of the schema to validate and normalize the values of the request's object corresponding to the specified source.

// File: schema-validator.js

const SCHEMAS = require('./schemas');

module.exports = (config) => (req, res, next) => {
  let schema = SCHEMAS?.[config.schema]?.[config.source];

  if (!schema) {
    return res.status(500).json({ error: 'Validation schema unknown' });
  }

  const { value, error } = schema.validate(req[config.source], { convert: true });
};

Note that in order to convert string values passed as route parameters to integers, such as id, we need to set the convert option of the validate() method to true.

Finally, let's either:

Respond with an HTTP 400 Bad Request if the validate() method returns an error.
Add the normalized values to the request's object corresponding to the specified source, and forward the request to the endpoint's controller.

// File: schema-validator.js

const SCHEMAS = require('./schemas');

module.exports = (config) => (req, res, next) => {
  let schema = SCHEMAS?.[config.schema]?.[config.source];

  if (!schema) {
    return res.status(500).json({ error: 'Validation schema unknown' });
  }

  const { value, error } = schema.validate(req[config.source], { convert: true });

  if (error) {
    return res.status(400).json({ error: error.message, source: config.source });
  }

  req[config.source] = { ...req[config.source], ...value };

  next();
};

Use the validation middleware

Within the server.js module, let's import the schema validation middleware, and invoke it on every route with the appropriate configuration object.

// File: server.js

const express = require('express');
const database = require('./database');
const schemaValidator = require('./schema-validator');

const server = express();
const pollRouter = express.Router();

pollRouter.get('/:id', schemaValidator({ schema: 'getPoll', source: 'params' }), (req, res) => {
  res.sendStatus(501);
});

pollRouter.post('/create', express.json(), schemaValidator({ schema: 'createPoll', source: 'body' }), (req, res) => {
  res.sendStatus(501);
});

pollRouter.post('/vote', express.json(), schemaValidator({ schema: 'votePoll', source: 'body' }), (req, res) => {
  res.sendStatus(501);
});

// ...

Step 6: Implement the GET /poll/:id endpoint

Within the HTTP GET /poll/:id endpoint, let's first attempt to retrieve the poll object corresponding to the id route parameter and respond with an HTTP 404 Not Found if the poll doesn't exist.

pollRouter.get('/:id', schemaValidator({ schema: 'getPoll', source: 'params' }), (req, res) => {
  const poll = database.tables.polls.find(poll => poll.id === req.params.id);

  if (!poll) {
    return res.status(404).json({ error: 'Poll not found' });
  }
});

Let's declare a data object that will contain the message body of the response, and include the poll's title, and optionally the list of choices and vote summary.

pollRouter.get('/:id', schemaValidator({ schema: 'getPoll', source: 'params' }), (req, res) => {
  // ...

  let data = {
    form: {
      title: poll.title,
      choices: [],
    },
    votes: [],
  };
});

Let's retrieve the choice and vote objects of the related poll.

pollRouter.get('/:id', schemaValidator({ schema: 'getPoll', source: 'params' }), (req, res) => {
  // ...

  const choices = database.tables.choices.filter(choice => choice.poll_id === req.params.id);
  const votes = database.tables.votes.filter(vote => vote.poll_id === req.params.id);
});

Let's check if the user has already voted by checking if the client's IP address exists in the list of votes, and save the current Unix timestamp.

pollRouter.get('/:id', schemaValidator({ schema: 'getPoll', source: 'params' }), (req, res) => {
  // ...

  const hasUserVoted = votes.find(vote => vote.user_ip_address === req.ip);

  const timestamp = Date.now();
});

Let's iterate on every element of the choice list using a for...of loop.

pollRouter.get('/:id', schemaValidator({ schema: 'getPoll', source: 'params' }), (req, res) => {
  // ...

  for (let choice of choices) {
    //
  }
});

Let's include each choice in the data object if the user hasn't voted yet.

pollRouter.get('/:id', schemaValidator({ schema: 'getPoll', source: 'params' }), (req, res) => {
  // ...

  for (let choice of choices) {
    if (!hasUserVoted) {
      data.form.choices.push({
        id: choice.id,
        value: choice.value,
      });
    }
  }
});

Let's include the vote summary in the data object if the poll's visibility is:

Set to "public".
Set to "public_end" and the current timestamp is greater than the value of the poll's closing_date property.
Set to "public_vote" and the user has already voted.

pollRouter.get('/:id', schemaValidator({ schema: 'getPoll', source: 'params' }), (req, res) => {
  // ...

  for (let choice of choices) {
    if (!hasUserVoted) {
      data.form.choices.push({
        id: choice.id,
        value: choice.value,
      });
    }

    if (
      (poll.result_visibility === 'public') ||
      (poll.result_visibility === 'public_end' && timestamp > poll.closing_date) ||
      (poll.result_visibility === 'public_vote' && hasUserVoted)
    ) {
      data.votes.push({
        value: choice.value,
        total: votes.filter(vote => choice.id === vote.choice_id).length
      });
    }
  }
});

Finally, let's respond to the client with an HTTP 200 OK containing the data object in the JSON format.

pollRouter.get('/:id', schemaValidator({ schema: 'getPoll', source: 'params' }), (req, res) => {
  // ...

  res.json(data);
});

Test the endpoint

To test this endpoint, let's add the following objects into the database.js module.

// File: database.js

module.exports = {
  _indexes: {
    polls: 4,
    choices: 7,
    votes: 2,
  },
  tables: {
    polls: [
      { id: 1, title: 'Which one tastes better?', closing_date: null, result_visibility: 'public' },
      { id: 2, title: 'Will Santa come at midnight?', closing_date: 1767221999000, result_visibility: 'public_end' },
      { id: 3, title: 'Which car is faster?', closing_date: 1767221999000, result_visibility: 'public_vote' },
    ],
    choices: [
      { id: 1, poll_id: 1, value: 'Pizza' },
      { id: 2, poll_id: 1, value: 'Burger' },
      { id: 3, poll_id: 2, value: 'Yes' },
      { id: 4, poll_id: 2, value: 'No' },
      { id: 5, poll_id: 3, value: 'Lamborghini' },
      { id: 6, poll_id: 3, value: 'Ferrari' },
    ],
    votes: [
      { id: 1, poll_id: 1, choice_id: 2, user_name: 'Jackson', user_ip_address: '::ffff:127.0.0.1' }
    ],
  },
};

And let's start the server:

node server.js

When querying the poll with an invalid id, it should respond with an HTTP 400 Bad Request.

$ curl -i 127.0.0.1:3000/poll/x
HTTP/1.1 400 Bad Request
X-Powered-By: Express
Content-Type: application/json; charset=utf-8
Content-Length: 57
ETag: W/"39-mR6PkOBbhBJJAJ4fA9g4i+VgqDU"
Date: Sat, 11 Oct 2025 11:03:22 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"error":"\"id\" must be a number","source":"params"}

When querying the poll whose id equals 1, it should respond with an HTTP 200 OK containing the votes but not the choices, since the user has already voted, as recorded by the IP address ::ffff:127.0.0.1.

$ curl -i 127.0.0.1:3000/poll/1
HTTP/1.1 200 OK
X-Powered-By: Express
Content-Type: application/json; charset=utf-8
Content-Length: 121
ETag: W/"79-XpGX35CnKNaFzfSTxi49RnHyEFU"
Date: Sat, 11 Oct 2025 10:36:20 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"form":{"title":"Which one tastes better?","choices":[]},"votes":[{"value":"Pizza","total":0},{"value":"Burger","total":1}]}

When querying the poll whose id equals 2, it should respond with an HTTP 200 OK containing the choices but not the votes, since the poll's closing date is set to the 1767221999000 timestamp, which is equivalent to 2025/12/31 at 23:59:59.

$ curl -i 127.0.0.1:3000/poll/2
HTTP/1.1 200 OK
X-Powered-By: Express
Content-Type: application/json; charset=utf-8
Content-Length: 117
ETag: W/"75-91j3tJqqn1xsMWS5VSzIOGJEtjk"
Date: Sat, 11 Oct 2025 10:36:23 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"form":{"title":"Will Santa come at midnight?","choices":[{"id":3,"value":"Yes"},{"id":4,"value":"No"}]},"votes":[]}

When querying the poll whose id equals 3, it should respond with an HTTP 200 OK containing the choices but not the votes, since the poll's votes visibility is set to "public_vote" and the user hasn't voted yet.

$ curl -i 127.0.0.1:3000/poll/3
HTTP/1.1 200 OK
X-Powered-By: Express
Content-Type: application/json; charset=utf-8
Content-Length: 122
ETag: W/"7a-k5DedEni/OTb8wTy6MhpJ4G1opI"
Date: Sat, 11 Oct 2025 10:57:40 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"form":{"title":"Which car is faster?","choices":[{"id":5,"value":"Lamborghini"},{"id":6,"value":"Ferrari"}]},"votes":[]}

When querying the poll whose id equals 4, it should respond with an HTTP 404 Not Found.

$ curl -i 127.0.0.1:3000/poll/4
HTTP/1.1 404 Not Found
X-Powered-By: Express
Content-Type: text/plain; charset=utf-8
Content-Length: 9
ETag: W/"9-0gXL1ngzMqISxa6S1zx3F4wtLyg"
Date: Sat, 11 Oct 2025 10:36:25 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"error":"Poll not found"}

Step 7: Implement the POST /poll/create endpoint

Within the HTTP POST /poll/create endpoint, let's create a new poll object using the data parsed by the validation middleware and assign it the next id available from the indexes object, while post-incrementing it at the same time.

pollRouter.post('/create', express.json(), schemaValidator({ schema: 'createPoll', source: 'body' }), (req, res) => {
  const poll = {
    id: database._indexes.polls++,
    ...req.body.poll,
  };
});

Let's store the object into the database.polls table.

pollRouter.post('/create', express.json(), schemaValidator({ schema: 'createPoll', source: 'body' }), (req, res) => {
  const poll = {
    id: database._indexes.polls++,
    ...req.body.poll,
  };

  database.tables.polls.push(poll);
});

Let's store each choice into the choices table, and assign it the next id available, while post-incrementing it at the same time.

pollRouter.post('/create', express.json(), schemaValidator({ schema: 'createPoll', source: 'body' }), (req, res) => {
  // ...

  for (let choice of req.body.choices) {
    database.tables.choices.push({
      id: database._indexes.choices++,
      poll_id: poll.id,
      value: choice,
    });
  }
});

And finally, let's respond with an HTTP 200 OK containing the newly created poll's id.

pollRouter.post('/create', express.json(), schemaValidator({ schema: 'createPoll', source: 'body' }), (req, res) => {
  // ...

  res.json({ poll_id: poll.id });
});

Test the endpoint

To test this endpoint, let's reset the object exported by the database.js module.

// File: database.js

module.exports = {
  _indexes: {
    polls: 1,
    choices: 1,
    votes: 1,
  },
  tables: {
    polls: [],
    choices: [],
    votes: [],
  },
};

Let's kill (using CTRL+C) and restart the server.

$ node server.js
^C
$ node server.js

When creating a poll with a missing list of choices, it should respond with an HTTP 400 Bad Request.

$ curl -i -X POST -H 'Content-Type: application/json' -d '{"poll":{"title":"Which one tastes better?","closing_date":null,"result_visibility":"public"}}' 127.0.0.1:3000/poll/create
HTTP/1.1 400 Bad Request
X-Powered-By: Express
Content-Type: application/json; charset=utf-8
Content-Length: 51
ETag: W/"33-iUbkFOxzZLKsXJpI+yPu7hLKxzA"
Date: Sat, 11 Oct 2025 11:23:45 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"error":"\"choices\" is required","source":"body"}

When creating a poll with a result visibility set to "public_end" and a closing date set to null, it should respond with an HTTP 400 Bad Request.

$ curl -i -X POST -H 'Content-Type: application/json' -d '{"poll":{"title":"Which one tastes better?","closing_date":null,"result_visibility":"public_end"},"choices":["Pizza","Burger"]}' 127.0.0.1:3000/poll/create
HTTP/1.1 400 Bad Request
X-Powered-By: Express
Content-Type: application/json; charset=utf-8
Content-Length: 70
ETag: W/"46-ezrMA+0QQL71WIgvCuXx5h4oM1s"
Date: Sat, 11 Oct 2025 11:24:14 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"error":"\"poll.closing_date\" must be a valid date","source":"body"}

When creating a poll with a closing date set to a past timestamp, it should respond with an HTTP 400 Bad Request.

$ curl -i -X POST -H 'Content-Type: application/json' -d '{"poll":{"title":"Which one tastes better?","closing_date":1735722000000,"result_visibility":"public_end"},"choices":["Pizza","Burger"]}' 127.0.0.1:3000/poll/create
HTTP/1.1 400 Bad Request
X-Powered-By: Express
Content-Type: application/json; charset=utf-8
Content-Length: 111
ETag: W/"6f-mHVPvcnfmJfLGpoqQasL3kO5gU8"
Date: Sat, 11 Oct 2025 11:25:02 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"error":"\"poll.closing_date\" must be greater than or equal to \"2025-10-11T12:25:02.121Z\"","source":"body"}

When creating a valid poll, it should respond with an HTTP 200 OK containing the poll's id.

$ curl -i -X POST -H 'Content-Type: application/json' -d '{"poll":{"title":"Which one tastes better?","closing_date":1767221999000,"result_visibility":"public_end"},"choices":["Pizza","Burger"]}' 127.0.0.1:3000/poll/create
HTTP/1.1 200 OK
X-Powered-By: Express
Content-Type: application/json; charset=utf-8
Content-Length: 13
ETag: W/"d-cHff1Ljgd50XiLS5Skq4iqxEZCg"
Date: Sat, 11 Oct 2025 11:25:23 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"poll_id":1}

When querying the poll using the id returned by the previous request, it should respond with an HTTP 200 OK containing the poll's data.

$ curl -i 127.0.0.1:3000/poll/1
HTTP/1.1 200 OK
X-Powered-By: Express
Content-Type: application/json; charset=utf-8
Content-Length: 119
ETag: W/"77-QQ4/koZFbRWbvl/yYAKAyB6OkZs"
Date: Sat, 11 Oct 2025 11:25:48 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"form":{"title":"Which one tastes better?","choices":[{"id":1,"value":"Pizza"},{"id":2,"value":"Burger"}]},"votes":[]}

Step 8: Implement the POST /poll/vote endpoint

Within the HTTP POST /poll/vote endpoint, let's first retrieve the choice object from the database corresponding to the choice_id property of the request's message body, and respond with an HTTP 404 Not Found if it doesn't exist.

pollRouter.post('/vote', express.json(), schemaValidator({ schema: 'votePoll', source: 'body' }), (req, res) => {
  const choice = database.tables.choices.find(choice => choice.id === req.body.choice_id);

  if (!choice) {
    return res.status(404).json({ error: 'Choice not found' });
  }
});

Let's retrieve the poll object from the database corresponding to the id property of the retrieved choice object, and respond with an HTTP 404 Not Found if it doesn't exist.

pollRouter.post('/vote', express.json(), schemaValidator({ schema: 'votePoll', source: 'body' }), (req, res) => {
  // ...

  const poll = database.tables.polls.find(poll => poll.id === choice.poll_id);

  if (!poll) {
    return res.status(404).json({ error: 'Poll not found' });
  }
});

Let's check if the closing_date property of the poll object is set, and respond with an HTTP 403 Forbidden if the current timestamp is greater, which means that the poll is closed and users can't vote anymore.

pollRouter.post('/vote', express.json(), schemaValidator({ schema: 'votePoll', source: 'body' }), (req, res) => {
  // ...

  if (poll.closing_date && Date.now() > poll.closing_date) {
    return res.status(403).json({ error: 'Poll is closed' });
  }
});

Let's check if the client's IP address exists in the poll's vote list, and respond with an HTTP 403 Forbidden if it does, which means that the user has already voted.

pollRouter.post('/vote', express.json(), schemaValidator({ schema: 'votePoll', source: 'body' }), (req, res) => {
  // ...

  const hasUserVoted = database.tables.votes.findIndex(vote => vote.poll_id === choice.poll_id && vote.user_ip_address === req.ip);

  if (hasUserVoted !== -1) {
    return res.status(403).json({ error: 'User has already voted' });
  }
});

Let's insert a new vote object into the votes table, including the vote's index, the poll's index, the data from the message body, and the client's IP address.

pollRouter.post('/vote', express.json(), schemaValidator({ schema: 'votePoll', source: 'body' }), (req, res) => {
  // ...

  const vote = {
    id: database._indexes.votes++,
    poll_id: choice.poll_id,
    ...req.body,
    user_ip_address: req.ip
  };

  database.tables.votes.push(vote);
});

Finally, let's respond with an HTTP 200 OK containing the id property of the vote object.

pollRouter.post('/vote', express.json(), schemaValidator({ schema: 'votePoll', source: 'body' }), (req, res) => {
  // ...

  res.json({ vote_id: vote.id });
});

Test the endpoint

To test this endpoint, let's kill and restart the server.

$ node server.js
^C
$ node server.js

When creating a new poll, it should respond with an HTTP 200 OK containing the poll's id.

$ curl -i -X POST -H 'Content-Type: application/json' -d '{"poll":{"title":"Which one tastes better?","closing_date":null,"result_visibility":"public_vote"},"choices":["Pizza","Burger"]}' 127.0.0.1:3000/poll/create
HTTP/1.1 200 OK
X-Powered-By: Express
Content-Type: application/json; charset=utf-8
Content-Length: 13
ETag: W/"d-cHff1Ljgd50XiLS5Skq4iqxEZCg"
Date: Sat, 11 Oct 2025 15:38:14 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"poll_id":1}

When querying the poll we've just created using the id returned by the previous query, it should respond with an HTTP 200 OK containing the poll's data, including the choices but not the votes, since the poll's result visibility is set to "public_vote".

$ curl -i 127.0.0.1:3000/poll/1
HTTP/1.1 200 OK
X-Powered-By: Express
Content-Type: application/json; charset=utf-8
Content-Length: 119
ETag: W/"77-QQ4/koZFbRWbvl/yYAKAyB6OkZs"
Date: Sat, 11 Oct 2025 15:38:21 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"form":{"title":"Which one tastes better?","choices":[{"id":1,"value":"Pizza"},{"id":2,"value":"Burger"}]},"votes":[]}

When voting for a poll with an invalid payload, it should respond with an HTTP 400 Bad Request.

$ curl -i -X POST -H 'Content-Type: application/json' -d '{"choice_id":2}' 127.0.0.1:3000/poll/vote
HTTP/1.1 400 Bad Request
X-Powered-By: Express
Content-Type: application/json; charset=utf-8
Content-Length: 53
ETag: W/"35-e+Aj2lGPB4w4JfvHCy/ykC8/7G8"
Date: Sat, 11 Oct 2025 15:53:58 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"error":"\"user_name\" is required","source":"body"}

When voting for a poll with a non-existent choice id, it should respond with an HTTP 404 Not Found.

$ curl -i -X POST -H 'Content-Type: application/json' -d '{"choice_id":3,"user_name":"Jackson"}' 127.0.0.1:3000/poll/vote
HTTP/1.1 404 Not Found
X-Powered-By: Express
Content-Type: application/json; charset=utf-8
Content-Length: 28
ETag: W/"1c-1cCU5TxdKUmlTxzbj9LSDLwyjYM"
Date: Sat, 11 Oct 2025 15:56:00 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"error":"Choice not found"}

When voting for a poll with a valid payload and an existing choice id, it should respond with an HTTP 200 OK containing the newly created vote's id.

$ curl -i -X POST -H 'Content-Type: application/json' -d '{"choice_id":2,"user_name":"Jackson"}' 127.0.0.1:3000/poll/vote
HTTP/1.1 200 OK
X-Powered-By: Express
Content-Type: application/json; charset=utf-8
Content-Length: 13
ETag: W/"d-nisMVKjWYQ6K/DygNQyFrZoaFXU"
Date: Sat, 11 Oct 2025 15:38:28 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"vote_id":1}

When voting again for the same poll, it should respond with an HTTP 403 Forbidden.

$ curl -i -X POST -H 'Content-Type: application/json' -d '{"choice_id":2,"user_name":"Jackson"}' 127.0.0.1:3000/poll/vote
HTTP/1.1 403 Forbidden
X-Powered-By: Express
Content-Type: application/json; charset=utf-8
Content-Length: 34
ETag: W/"22-zN9pQ6+RFSObob4HECP2Wn+TtDc"
Date: Sat, 11 Oct 2025 15:44:59 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"error":"User has already voted"}

Finally, when querying the poll again, it should respond with an HTTP 200 OK containing the poll's data, including the votes but not the choices, since the user has already voted.

$ curl -i 127.0.0.1:3000/poll/1
HTTP/1.1 200 OK
X-Powered-By: Express
Content-Type: application/json; charset=utf-8
Content-Length: 125
ETag: W/"7d-mNH3QPy4zUlnq89V201JwkrDefI"
Date: Sat, 11 Oct 2025 15:38:36 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"form":{"title":"Which one tastes better?","choices":[]},"votes":[{"value":"Pizza","total":0},{"value":"Burger","total":1}]}

Congratulations! 🎉

You now have a working Strawpoll-like API built with Node.js, Express and Joi. 🎉

Want to Learn Backend the Right Way?

✅ Run this project on your own machine - download the source code here.

🚀 If you enjoyed this article and want to go beyond snippets, check out the Learn Backend Mastery program — the complete zero-to-hired roadmap to becoming a job-ready Node.js backend developer, including:

136 premium lessons across CLI, JavaScript, Node.js, MySQL, Express, Git, and more.
25 full-scale projects + commented solutions
Visual progress tracking.
Exclusive student Discord channel
Lifetime access and all future updates

👉 Explore the Mastery program

3 Rate-Limiting Strategies for Your API Endpoints in Node.js

Razvan — Fri, 03 Oct 2025 15:13:34 +0000

In backend development, rate limiting is a strategy for controlling how many requests clients can make to an API endpoint within a given time window before being rejected.

Rate limiting is essential for:

Protection from abuse / DoS — A client or attacker might try to flood your API and tie up resources.
Fairness & QoS — You ensure clients can’t hog all your capacity, hijacking performance.
Cost control — External services might have rate limits or incur cost per request.
User experience — Better to throttle politely than crash or slow to a crawl.

But rate limiting isn't just about stopping "bad guys" — it's also about making your API predictable and reliable under load.

In this post, I'll walk you through 3 classic rate-limiting strategies called: fixed window, sliding window, and token bucket.

💡 New to backend programming in Node.js?

Check out the Learn Backend Mastery Program — a complete zero-to-hired roadmap that takes you from complete beginner to job-ready Node.js backend developer in 12 months.

👉 learnbackend.dev

Strategy 1: Fixed Window

The fixed window strategy consists in dividing time into fixed slots (e.g., 1 minute) and counting how many requests a client makes within this slot.

Once the client exceeds the defined maximum amount of requests per slot, all further requests are blocked until the slot resets.

For example, a fixed window of 10 requests per minute means that a client can only make 10 requests between 12:00:00–12:00:59, then another 10 between 12:01:00–12:01:59, and so on.

This strategy is often used for internal/admin endpoints.

Pros and cons

✅ Very simple to implement.
✅ Minimal memory usage.
❌ Bursty at window boundaries — a client could send 10 requests at 12:00:59 and another 10 at 12:01:00, effectively making 20 requests in 2 seconds.

Implementation example

Here's an implementation example of the fixed window strategy using a function that takes as parameters the maximum amount of requests a client can make (limit) and the duration in milliseconds of the time slot (windowMs), and returns an Express middleware.

function fixedWindow(limit, windowMs) {
  // Create an in-memory store, where:
  // - key: the client IP address
  // - value: { count: the number of requests in current window, windowStart: the window start timestamp }
  const store = new Map();

  // Return an Express middleware
  return (req, res, next) => {
    // The client's IP address
    const key = req.ip;

    // The current time in milliseconds
    const now = Date.now();

    // The start time of the current fixed window slot
    const slotStart = Math.floor(now / windowMs) * windowMs;

    // The client's entry
    let entry = store.get(key);

    // If no entry exists yet, or we've moved into a new time slot,
    // initialize/reset the counter for the new window
    if (!entry || entry.windowStart !== slotStart) {
      entry = {
        count: 0,
        windowStart: slotStart
      };
      store.set(key, entry);
    }

    // Increment the request counter
    entry.count++;

    // If the request count exceeds the allowed limit for this window,
    // reject with HTTP 429 Too Many Requests
    if (entry.count > limit) {
      return res.status(429).json({ error: 'Too Many Requests' });
    }

    // Allow and forward the request to the next middleware
    next();
  };
}

Strategy 2: Sliding Window

The sliding window strategy consists in looking back over the last N seconds (or milliseconds) from right now and counting how many requests a client makes within that rolling window.

Once the client exceeds the defined maximum amount of requests in that rolling period, all further requests are blocked until enough time has passed for older requests to fall outside of the window.

For example, a sliding window of 10 requests per minute means that if a client makes 10 requests between 12:00:15 and 12:01:15, any additional request at 12:01:10 will be blocked, but a new request at 12:01:16 will be allowed because the first request (from 12:00:15) is no longer within the last 60 seconds.

This strategy is often used for public APIs.

Pros and Cons

✅ No boundary burst exploits.
✅ Matches the natural meaning of "10 per minute".
❌ Slightly more memory and compute (tracking timestamps).

Implementation example

Here's an implementation example of the sliding window strategy using a function that takes as parameters the maximum amount of requests a client can make (limit) and the duration in milliseconds of the rolling window (windowMs), and returns an Express middleware.

function slidingWindow(limit, windowMs) {
  const store = new Map();

  return (req, res, next) => {
    const key = req.ip;
    const now = Date.now();

    // The client's recent request times
    // Start with empty array if none
    let times = store.get(key) || [];

    // Ensure the map has an entry
    store.set(key, times);

    // Compute the oldest timestamp we still care about for the rolling window
    const cutoff = now - windowMs;

    // Keep only timestamps within the last `windowMs`
    times = times.filter(time => time > cutoff);

    // Save the pruned list back to the store
    store.set(key, times);

    // Reject the request if the count exceeds the limit
    if (times.length >= limit) {
      return res.status(429).json({ error: 'Too Many Requests' });
    }

    // Record the request's timestamp
    times.push(now);

    // Allow and forward the request to the next middleware
    next();
  };
}

Strategy 3: Token Bucket

The token bucket strategy consists in assigning each client a bucket that fills with tokens at a steady rate over time (e.g., 10 tokens per second).

Each request the client makes consumes one token from the bucket. If the bucket has tokens available, the request is allowed; if it's empty, the request is blocked until new tokens are added.

For example, a token bucket of 60 tokens refilled at a rate of 1 token per second means a client can make short bursts of up to 60 requests at once, but after that, they will only be able to send 1 new request per second as the bucket refills.

This strategy is can be used for all types of endpoints as it combines steady rates with short bursts.

Pros and Cons

✅ Best balance of fairness and flexibility.
✅ Supports controlled bursts.
❌ A bit more logic to implement and maintain.

Implementation example

Here's an implementation example of the token bucket strategy using a function that takes as parameters the number of tokens to refill (refill), the refill rate in seconds (rate), and the maximum amount of tokens a bucket can hold (burst), and returns an Express middleware.

function tokenBucket(refill, rate, burst) {
  const store = new Map();

  return (req, res, next) => {
    const key = req.ip;
    const now = Date.now();
    let bucket = store.get(key);

    if (!bucket) {
      // Create a new bucket filled at capacity (bust)
      bucket = {
        tokens: burst,
        lastRefill: now
      };
      store.set(key, bucket);
    }

    // The refill interval in milliseconds
    const intervalMs = rate * 1000;

    // The number of intervals elapsed between now and the last refill
    const intervalsElapsed = Math.floor((now - bucket.lastRefill) / intervalMs);

    // If at least one full interval passed
    // Either fill the bucket to capacity
    // Or add `refill` number of tokens multiplied by the number of passed intervals
    if (intervalsElapsed > 0) {
      // Fill the bucket to capacity or to 
      bucket.tokens = Math.min(
        burst,
        bucket.tokens + intervalsElapsed * refill
      );

      bucket.lastRefill += intervalsElapsed * intervalMs;
    }

    // Reject the request if the bucket is empty
    if (bucket.tokens < 1) {
      return res.status(429).json({ error: 'Too Many Requests' });
    }

    // Decrement the amount of tokens by 1
    bucket.tokens -= 1;

    // Allow and forward the request to the next middleware
    next();
  };
}

Want to Learn Backend the Right Way?

If you enjoyed this article and want to go beyond snippets, check out the Learn Backend Mastery program — the complete zero-to-hired roadmap to becoming a job-ready Node.js backend developer, including:

136 premium lessons across CLI, JavaScript, Node.js, MySQL, Express, Git, and more.
25 full-scale projects + commented solutions
Visual progress tracking.
Exclusive student Discord channel
Lifetime access and all future updates

👉 Explore the Mastery program

How to Build a Bitly-Like URL Shortener API with Node + Express

Razvan — Mon, 29 Sep 2025 07:00:00 +0000

Welcome back to Code in Action, the series where we build practical backend projects step by step.

In this tutorial, we're going to recreate a simplified version of Bitly—the popular online service that allows you to convert long URLs into shorter and easier to share ones.

Our API will include two endpoints:

HTTP POST /shorten for storing the original URL and responding with a custom link containing a short ID.
HTTP GET /:shortId for redirecting the client to the original URL corresponding to the short ID.

By the end of this tutorial, you'll know how to:

Validate and normalize user-provided URLs
Generate short, unique IDs
Store and retrieve data in an in-memory object
Redirect clients from short links to original URLs
Return appropriate HTTP status codes for errors and edge cases
Protect your service by blacklisting malicious or sensitive addresses

Ready? Let's build!

Step 1: Set Up the Project

Let's create and enter a new directory named bitly-lite.

mkdir bitly-lite
cd bitly-lite

Let's initialize the project, and install the express package for implementing the API and the nanoid package for generating secure URL-friendly unique string IDs

npm init
npm install express nanoid

Step 2: Create the Server

Within the root directory, let's create a new file for the API named server.js.

touch server.js

And within it:

Import the express package.
Create a new server instance by invoking the top-level function exported by the package.
Bind the server to the development port 5000 using the listen() method of the server instance.

const express = require('express');

const server = express();

server.listen(5000, () => {
  console.log('Server running on port 5000...');
});

Step 3: Create the Database Object

In order to keep this project simple, we'll use a global object literal named urls as in-memory database.

let urls = {
  <shortId>: <originalUrl>
};

Where:

<shortId> is a unique string identifier for a shortened URL of 6 characters exactly generated using the nanoid package.
<originalUrl> is the full-length original URL string.

For example:

let urls = {
  '0si_Cq': 'https://learnbackend.dev',
  'X_dCS1': 'https://learnbackend.dev/get-started'
};

So, let's declare a urls variable right after the server instantiation.

const express = require('express');

const server = express();

let urls = {};

server.listen(5000, () => {
  console.log('Server running on port 5000...');
});

It's important to note that this type of in-memory storage is not suitable for production as the data will be erased every time the server crashes or restarts.

You should consider persisting the data using either a JSON file for simplicity, a database like MySQL for extended capabilities, or a caching software like Redis for efficiency.

Step 4: Shorten URLs

Implement the endpoint

Let's declare a new HTTP POST /shorten endpoint responsible for storing a URL and responding with a shortened one.

const express = require('express');

const server = express();

let urls = {};

server.post('/shorten', express.json(), (req, res) => {
  //
});

// ...

As we expect the message body of the incoming HTTP requests to be in the JSON format, we'll use the express.json() middleware to automatically convert it into usable JSON objects.

Extract the URL

The message body of the incoming HTTP request should contain an object with a single property named originalUrl whose value is a valid URL. For example: { "originalUrl": "https://learnbackend.dev" }.

So, let's extract the originalUrl property from the request's message body that contains the original URL to shorten, and respond with an HTTP 400 Bad Request if it is null or undefined.

server.post('/shorten', express.json(), (req, res) => {
  let originalUrl = req.body?.originalUrl;

  if (!originalUrl) {
    return res.sendStatus(400);
  }
});

Normalize the URL

At first glance, two URLs may look different but actually point to the same place. For example, https://learnbackend.dev/get-started, learnbackend.dev//get-started/ are equivalent.

Normalization allows us to bring consistency to our API by trimming spaces, forcing lowercase domains, stripping unnecessary slashes, and so on, in order to avoid storing two identical URLs as separate entries, therefore wasting IDs and creating duplicates.

So, let's start by removing whitespace from both ends of the URL.

server.post('/shorten', express.json(), (req, res) => {
  let originalUrl = req.body?.originalUrl;

  if (!originalUrl) {
    return res.sendStatus(400);
  }

  originalUrl = originalUrl.trim();
});

Let's then prefix the URL with https:// if it doesn't start with a scheme (e.g., http://, ftp://, irc://).

server.post('/shorten', express.json(), (req, res) => {
  let originalUrl = req.body?.originalUrl;

  if (!originalUrl) {
    return res.sendStatus(400);
  }

  originalUrl = originalUrl.trim();

  if (!/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(originalUrl)) {
    originalUrl = 'https://' + originalUrl;
  }
});

Let's initialize a new URL object within a try…catch block using the built-in URL class, and respond with an HTTP 400 Bad Request if it throws an error during instantiation - which means that the URL format is invalid.

server.post('/shorten', express.json(), (req, res) => {
  let originalUrl = req.body?.originalUrl;

  if (!originalUrl) {
    return res.sendStatus(400);
  }

  originalUrl = originalUrl.trim();

  if (!/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(originalUrl)) {
    originalUrl = 'https://' + originalUrl;
  }

  try {
    originalUrl = new URL(originalUrl);
  } catch (error) {
    return res.sendStatus(400);
  }
});

Let's remove any duplicate and trailing slashes from the URL's pathname.

server.post('/shorten', express.json(), (req, res) => {
  let originalUrl = req.body?.originalUrl;

  if (!originalUrl) {
    return res.sendStatus(400);
  }

  originalUrl = originalUrl.trim();

  if (!/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(originalUrl)) {
    originalUrl = 'https://' + originalUrl;
  }

  try {
    originalUrl = new URL(originalUrl);
  } catch (error) {
    return res.sendStatus(400);
  }

  originalUrl.pathname = originalUrl.pathname
    .replace(/\/{2,}/g, '/')
    .replace(/\/+$/, '');
});

Let's sort the URL's query string parameters in alphabetical order for consistency.

server.post('/shorten', express.json(), (req, res) => {
  let originalUrl = req.body?.originalUrl;

  if (!originalUrl) {
    return res.sendStatus(400);
  }

  originalUrl = originalUrl.trim();

  if (!/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(originalUrl)) {
    originalUrl = 'https://' + originalUrl;
  }

  try {
    originalUrl = new URL(originalUrl);
  } catch (error) {
    return res.sendStatus(400);
  }

  originalUrl.pathname = originalUrl.pathname
    .replace(/\/{2,}/g, '/')
    .replace(/\/+$/, '');

  originalUrl.searchParams.sort();
});

Let's remove the port number from the URL if it matches the standard HTTP and HTTPs ports.

server.post('/shorten', express.json(), (req, res) => {
  let originalUrl = req.body?.originalUrl;

  if (!originalUrl) {
    return res.sendStatus(400);
  }

  originalUrl = originalUrl.trim();

  if (!/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(originalUrl)) {
    originalUrl = 'https://' + originalUrl;
  }

  try {
    originalUrl = new URL(originalUrl);
  } catch (error) {
    return res.sendStatus(400);
  }

  originalUrl.pathname = originalUrl.pathname
    .replace(/\/{2,}/g, '/')
    .replace(/\/+$/, '');

  originalUrl.searchParams.sort();

  if (
    (originalUrl.protocol === 'http:' && originalUrl.port === '80') ||
    (originalUrl.protocol === 'https:' && originalUrl.port === '443')
  ) {
    originalUrl.port = '';
  }
});

And finally, let's convert the URL object back into a string.

server.post('/shorten', express.json(), (req, res) => {
  let originalUrl = req.body?.originalUrl;

  if (!originalUrl) {
    return res.sendStatus(400);
  }

  originalUrl = originalUrl.trim();

  if (!/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(originalUrl)) {
    originalUrl = 'https://' + originalUrl;
  }

  try {
    originalUrl = new URL(originalUrl);
  } catch (error) {
    return res.sendStatus(400);
  }

  originalUrl.pathname = originalUrl.pathname
    .replace(/\/{2,}/g, '/')
    .replace(/\/+$/, '');

  originalUrl.searchParams.sort();

  if (
    (originalUrl.protocol === 'http:' && originalUrl.port === '80') ||
    (originalUrl.protocol === 'https:' && originalUrl.port === '443')
  ) {
    originalUrl.port = '';
  }

  originalUrl = originalUrl.toString();
});

💡 New to backend programming in Node.js?

Check out the Learn Backend Mastery Program - a complete zero-to-hero roadmap that takes you from beginner to job-ready junior Node.js backend developer in 12 months.

👉 learnbackend.dev

Store and shorten the URL

Let's first import the nanoid package at the top of the file for generating unique identifiers.

const express = require('express');
const { nanoid } = require('nanoid');

// ...

Then, in order to avoid unnecessarily storing duplicate URLs, let's implement a simple caching mechanism that iterates on each property of the urls database object and returns the corresponding shortened URL if it already exists using the json() method of the response object.

server.post('/shorten', express.json(), (req, res) => {
  // ...

  for (let shortId in urls) {
    if (urls[shortId] === originalUrl) {
      return res.json({
        shortUrl: `http://127.0.0.1:5000/${shortId}`
      });
    }
  }
});

Finally, if the URL hasn't been previously stored, let's generate a new unique identifier using the nanoid package, use this identifier as key to store the URL in the urls object, and return a custom URL that includes the identifier.

server.post('/shorten', express.json(), (req, res) => {
  // ...

  let shortId;

  do {
    shortId = nanoid(6);
  } while (urls[shortId]);

  urls[shortId] = originalUrl;

  res.json({
    shortUrl: `http://127.0.0.1:5000/${shortId}`
  });
});

Note that while it's unlikely that the nanoid package would produce two identical IDs, as a rule of thumb, we should always code for the worst case scenario.

Test the endpoint

Let's now test our endpoint by adding a temporary log that outputs the content of the urls object every time a new URL is added.

server.post('/shorten', express.json(), (req, res) => {
  // ...

  urls[shortId] = originalUrl;

  console.log(urls);

  res.json({
    shortUrl: `http://127.0.0.1:5000/${shortId}`
  });
});

Let's start the server using the node utility, and let's test various scenarios using the curl command to send HTTP POST requests to the endpoint.

$ node server.js
Server running on port 5000...

When sending any of the following requests:

curl -i -X POST \
-H 'Content-Type: application/json' \
127.0.0.1:5000/shorten

curl -i -X POST \
-H 'Content-Type: application/json' \
-d '{"url":"https://learnbackend.dev"}' \
127.0.0.1:5000/shorten

curl -i -X POST \
-H 'Content-Type: application/json' \
-d '{"originalUrl":""}' \
127.0.0.1:5000/shorten

The endpoint should respond with an HTTP 400.

HTTP/1.1 400 Bad Request
X-Powered-By: Express
Content-Type: text/plain; charset=utf-8
Content-Length: 11
ETag: W/"b-EFiDB1U+dmqzx9Mo2UjcZ1SJPO8"
Date: Thu, 25 Sep 2025 10:01:36 GMT
Connection: keep-alive
Keep-Alive: timeout=5

Bad Request

When sending a request with a valid property and a valid URL, the endpoint should respond with an HTTP 200 containing a custom URL.

$ curl -i -X POST \
-H 'Content-Type: application/json' \
-d '{"originalUrl":"https://learnbackend.dev"}' \
127.0.0.1:5000/shorten
HTTP/1.1 200 OK
X-Powered-By: Express
Content-Type: application/json; charset=utf-8
Content-Length: 43
ETag: W/"2b-XW53NJg2Zk58niT3W5OsFqP6Mcc"
Date: Thu, 25 Sep 2025 10:02:38 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"shortUrl":"http://127.0.0.1:5000/0k99y7"}

And the server should output the following log.

$ node server.js
Server running on port 5000...
{ '0k99y7': 'https://learnbackend.dev' }

When sending the same request twice, the endpoint should respond with an HTTP 200 containing the same custom URL, and the server should not output a new log.

$ curl -i -X POST \
-H 'Content-Type: application/json' \
-d '{"originalUrl":"https://learnbackend.dev"}' \
127.0.0.1:5000/shorten
HTTP/1.1 200 OK
X-Powered-By: Express
Content-Type: application/json; charset=utf-8
Content-Length: 43
ETag: W/"2b-XW53NJg2Zk58niT3W5OsFqP6Mcc"
Date: Thu, 25 Sep 2025 10:02:52 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"shortUrl":"http://127.0.0.1:5000/0k99y7"}

Step 5: Redirect Clients to Original URLs

Let's now declare a new HTTP GET endpoint responsible for retrieving an original URL based on its identifier and redirecting the client to it.

// ...

server.post('/shorten', express.json(), (req, res) => {
  // ...
});

server.get('/:shortId', (req, res) => {
  //
});

// ...

Let's extract the shortId property from the query string parameters object, and respond with an HTTP 400 Bad Request if it's not 6 characters long or includes characters that are not letters, digits, underscores, or dashes.

server.get('/:shortId', (req, res) => {
  const shortId = req.params?.shortId;
  const shortIdRegex = /^[A-Za-z0-9_-]{6}$/;

  if (!shortIdRegex.test(shortId)) {
    return res.sendStatus(400);
  }
});

Let's then attempt to retrieve the original URL from the urls object using the shortId variable as key, and respond with an HTTP 404 Not Found if the key doesn't exist.

server.get('/:shortId', (req, res) => {
  const shortId = req.params?.shortId;
  const shortIdRegex = /^[A-Za-z0-9_-]{6}$/;

  if (!shortIdRegex.test(shortId)) {
    return res.sendStatus(400);
  }

  const originalUrl = urls[shortId];

  if (!originalUrl) {
    return res.sendStatus(404);
  }
});

Finally, let's redirect the user to the original URL using the redirect() method of the response object.

server.get('/:shortId', (req, res) => {
  const shortId = req.params?.shortId;
  const shortIdRegex = /^[A-Za-z0-9_-]{6}$/;

  if (!shortIdRegex.test(shortId)) {
    return res.sendStatus(400);
  }

  const originalUrl = urls[shortId];

  if (!originalUrl) {
    return res.sendStatus(404);
  }

  res.redirect(originalUrl);
});

Test the endpoint

Let's now test our endpoint by first killing the server using CTRL+C, restarting it, and sending various HTTP GET requests to it using the following curl commands.

$ node server.js
Server running on port 5000...
{ '0k99y7': 'https://learnbackend.dev' }
^C
$ node server.js
Server running on port 5000...

When sending a request with a valid property and a valid URL, the endpoint should respond with an HTTP 200 containing a custom URL.

$ curl -i -X POST \
-H 'Content-Type: application/json' \
-d '{"originalUrl":"https://learnbackend.dev"}' \
127.0.0.1:5000/shorten
HTTP/1.1 200 OK
X-Powered-By: Express
Content-Type: application/json; charset=utf-8
Content-Length: 43
ETag: W/"2b-hZUEAXMO2zK+xyNW4ixhoCwEcmo"
Date: Thu, 25 Sep 2025 10:07:56 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"shortUrl":"http://127.0.0.1:5000/2zvE-2"}

When sending a request with an invalid ID format, the endpoint should respond with an HTTP 400.

$ curl -i 127.0.0.1:5000/xxx
HTTP/1.1 400 Bad Request
X-Powered-By: Express
Content-Type: text/plain; charset=utf-8
Content-Length: 11
ETag: W/"b-EFiDB1U+dmqzx9Mo2UjcZ1SJPO8"
Date: Thu, 25 Sep 2025 10:09:15 GMT
Connection: keep-alive
Keep-Alive: timeout=5

Bad Request

When sending a request with a valid but non-existent ID, the endpoint should respond with an HTTP 404.

$ curl -i 127.0.0.1:5000/xxxxxx
HTTP/1.1 404 Not Found
X-Powered-By: Express
Content-Type: text/plain; charset=utf-8
Content-Length: 9
ETag: W/"9-0gXL1ngzMqISxa6S1zx3F4wtLyg"
Date: Thu, 25 Sep 2025 10:09:59 GMT
Connection: keep-alive
Keep-Alive: timeout=5

Not Found

When sending a request with a valid and existing ID, the endpoint should respond with an HTTP 302, including the original URL.

$ curl -i 127.0.0.1:5000/2zvE-2
HTTP/1.1 302 Found
X-Powered-By: Express
Location: https://learnbackend.dev
Vary: Accept
Content-Type: text/plain; charset=utf-8
Content-Length: 46
Date: Thu, 25 Sep 2025 10:11:29 GMT
Connection: keep-alive
Keep-Alive: timeout=5

Found. Redirecting to https://learnbackend.dev

Step 6: Blacklist Malicious and Sensitive URLs

URL shorteners are easy targets for abuse.

As attackers often try to hide links to local machines or private networks behind short IDs, we'll add a tiny policy layer that refuses to shorten URLs pointing to these special ranges:

localhost
Loopback: 127.0.0.0/8
Private LANs: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
Link-local: 169.254.0.0/16

Implement a blacklist policy check

At the top of the file, let's declare a new global constant named blacklist, and initialize it with an array of undesirable hostnames.

const express = require('express');
const { nanoid } = require('nanoid');

const server = express();

let urls = {};

const blacklist = ['scam.com', 'phishing.net'];

// ...

Let's then update the /shorten endpoint one last time to check if the URL's hostname is in the blacklist array or matches any of the IP patterns specified above, and respond with an HTTP 403 Forbidden indicating that the request is valid but not allowed by policy.

server.post('/shorten', express.json(), (req, res) => {
  // ...

  if (
    blacklist.includes(originalUrl.hostname) ||
    originalUrl.hostname === 'localhost' || 
    /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(originalUrl.hostname) ||
    /^10\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(originalUrl.hostname) ||
    /^172\.(1[6-9]|2\d|3[0-1])\.\d{1,3}\.\d{1,3}$/.test(originalUrl.hostname) ||
    /^192\.168\.\d{1,3}\.\d{1,3}$/.test(originalUrl.hostname) ||
    /^169\.254\.\d{1,3}\.\d{1,3}$/.test(originalUrl.hostname)
  ) {
    return res.sendStatus(403);
  }

  originalUrl = originalUrl.toString();

  // ...
});

Test the endpoint

Let's now test our endpoint by first killing the server using CTRL+C, restarting it one last time.

$ node server.js
Server running on port 5000...
{ '0k99y7': 'https://learnbackend.dev' }
^C
$ node server.js
Server running on port 5000...

When sending any of the following requests to the HTTP POST /shorten endpoint:

curl -i -X POST \
-H 'Content-Type: application/json' \
-d '{"originalUrl":"localhost"}' \
127.0.0.1:5000/shorten

curl -i -X POST \
-H 'Content-Type: application/json' \
-d '{"originalUrl":"http://127.0.0.1:3000"}' \
127.0.0.1:5000/shorten

curl -i -X POST \
-H 'Content-Type: application/json' \
-d '{"originalUrl":"https://scam.com/signup"}' \
127.0.0.1:5000/shorten

curl -i -X POST \
-H 'Content-Type: application/json' \
-d '{"originalUrl":"https://172.16.12.1"}' \
127.0.0.1:5000/shorten

It should respond with an HTTP 403 Forbidden.

HTTP/1.1 403 Forbidden
X-Powered-By: Express
Content-Type: text/plain; charset=utf-8
Content-Length: 9
ETag: W/"9-PatfYBLj4Um1qTm5zrukoLhNyPU"
Date: Fri, 26 Sep 2025 09:52:18 GMT
Connection: keep-alive
Keep-Alive: timeout=5

Forbidden

Conclusion

Congratulations! 🎉

You now have a working Bitly-like URL shortener built with Node.js and Express, complete with validation, normalization, redirects, and basic security checks.

What's next?

✅ Get the code: Run this project on your own machine - download the source code here.

🚀 Go further: If you're serious about backend development, check out the Learn Backend Mastery Program - a complete zero-to-hired roadmap to become a job-ready Node.js backend developer in 12 months.

How to Build a Minesweeper CLI Game in Node.js (Part 3/3)

Razvan — Fri, 26 Sep 2025 08:57:18 +0000

Welcome back to Minesweeper Part 3.

Last time you built the display: terminal UI, game loop, command parsing and validation, win/lose checks.

In this final part, you’ll ask the player for their username, keep track of their score, and display the list of high score at the end of each game.

Let’s build!

Step 12: Ask for the username

First, let’s slightly modify the printWelcome() function so that instead of outputting a message with the game commands, it asks for the player’s username.

function printWelcome() {
  process.stdout.write('Welcome to MinesweeperJS!\n\n');
  process.stdout.write('> Enter your username: ');
}

And let’s create a new function named printCommands() that outputs the game commands.

function printCommands() {
  process.stdout.write('\nHow to play:\n\n');
  process.stdout.write('> Type "rROW,COL" to reveal a square (e.g., r0,3).\n');
  process.stdout.write('> Type "fROW,COL" to flag/unflag a square (e.g., f2,4).\n\n');
  process.stdout.write('Got it? Let\'s play!\n\n');
}

Within the IIFE block, let’s declare a new undefined variable named username and let’s remove the first calls to the printGrid() and printPrompt() functions for now.

(() => {
  const size = parseGridSize();
  const grid = createGrid(size);
  let flags = size;
  let username;

  clearScreen();
  printWelcome();

  process.stdin.on('data', input => {
    // ...
  });
})();

Then, within the body of the event listener’s callback function, let’s declare an if statement that will only be executed if the username variable is undefined, update the value of the username variable, and print the game commands, grid, and prompt.

(() => {
  const size = parseGridSize();
  const grid = createGrid(size);
  let flags = size;
  let username;

  clearScreen();
  printWelcome();

  process.stdin.on('data', input => {
    const line = input.toString().trim();

    if (!username) {
      username = line;
      printCommands();
      printGrid(grid);
      printPrompt();
    } else {
      const match = line.match(/^(r|f)(\d+),(\d+)$/i);

      // ...
    }
  });
})();

Which will ultimately produce the following output when running the script.

$ node minesweeper.js
Welcome to MinesweeperJS!

> Enter your username: razvan

How to play:

> Type "rROW,COL" to reveal a square (e.g., r0,3).
> Type "fROW,COL" to flag/unflag a square (e.g., f2,4).

Got it? Let's play!

    0  1  2  3  4  5 
   ──────────────────
0 │ ■  ■  ■  ■  ■  ■ │
1 │ ■  ■  ■  ■  ■  ■ │
2 │ ■  ■  ■  ■  ■  ■ │
3 │ ■  ■  ■  ■  ■  ■ │
4 │ ■  ■  ■  ■  ■  ■ │
5 │ ■  ■  ■  ■  ■  ■ │
   ──────────────────

>

Step 13: Keep track of the score

Within the IIFE, let’s declare a new variable named score and initialize it with an object where:

time is used to store the number of milliseconds elapsed since the epoch at the beginning of the game.
revealed is used to count the number of safe squares revealed by the player.
flagged is used to count the number of mines correctly flagged by the player.
exploded is used to store whether the player revealed a mine or not.

(() => {
  const size = parseGridSize();
  const grid = createGrid(size);
  let flags = size;
  let username;
  let score = {
    time: 0,
    revealed: 0,
    flagged: 0,
    exploded: false
  };

  // ...
})();

Keep track of the game duration

To keep track of the game’ start time, let’s update the score.time property with the value returned by the Date.now() method, as soon as the player enters their first valid command.

Then within the wining/losing conditions, let’s calculate the difference between the game start and now, and divide it by 1000 to express it in seconds.

(() => {
  // ...

  process.stdin.on('data', input => {
    const line = input.toString().trim();

    if (!username) {
      // ...
    } else {
      const match = line.match(/^(r|f)(\d+),(\d+)$/i);

      if (!match) {
        // ...
      }
      else {
        // ...

        if (row < 0 || col < 0 || row > grid.length - 1 || col > grid.length - 1) {
          // ...
        }
        else {
          let square = grid[row][col];

          if (!score.time) {
            score.time = Date.now();
          }

          // ...

          if (square.revealed && square.mine) {
            score.time = (Date.now() - score.time) / 1000;
            process.stdout.write('💥 Boooooom! Game over...\n\n');
            process.exit(0);
          }
          else if (checkRevealedSquares(grid) || checkFlaggedMines(grid)) {
            score.time = (Date.now() - score.time) / 1000;
            process.stdout.write('🏆 You win!\n\n');
            process.exit(0);
          }

          printPrompt();
        }
      }
    }
  });
})();

Keep track of revealed squares

To keep track of revealed squares, let’s increment the score.revealed property every time the square doesn’t hold a mine within the condition that checks if the played command is “reveal”.

(() => {
  // ...

  process.stdin.on('data', input => {
    const line = input.toString().trim();

    if (!username) {
      // ...
    } else {
      const match = line.match(/^(r|f)(\d+),(\d+)$/i);

      if (!match) {
        // ...
      }
      else {
        // ...

        if (row < 0 || col < 0 || row > grid.length - 1 || col > grid.length - 1) {
          // ...
        }
        else {
          let square = grid[row][col];

          if (!score.time) {
            score.time = Date.now();
          }

          clearScreen();

          if (cmd === 'r') {
            square.revealed = true;

            if (!square.mine) {
              score.revealed++;
            }

            if (square.flagged) {
              square.flagged = false;
              flags++;
            }
          }

          // ...
        }
      }
    }
  });
})();

Keep track of flagged mines

To keep track of flagged mines:

Let’s decrement the score.flagged property every time the number of flags available is incremented — which implies that the flagged square was either revealed (and therefore didn’t hold a mine) or just unflagged.
Let’s increment the score.flagged property every time an unrevealed square that holds a mine is correctly flagged.

(() => {
  // ...

  process.stdin.on('data', input => {
    const line = input.toString().trim();

    if (!username) {
      // ...
    } else {
      const match = line.match(/^(r|f)(\d+),(\d+)$/i);

      if (!match) {
        // ...
      }
      else {
        // ...

        if (row < 0 || col < 0 || row > grid.length - 1 || col > grid.length - 1) {
          // ...
        }
        else {
          let square = grid[row][col];

          if (!score.time) {
            score.time = Date.now();
          }

          clearScreen();

          if (cmd === 'r') {
            square.revealed = true;

            if (!square.mine) {
              score.revealed++;
            }

            if (square.flagged) {
              square.flagged = false;
              flags++;
              score.flagged--;
            }
          }
          else if (cmd === 'f') {
            if (!square.flagged && !flags) {
              process.stdout.write('Error: No more flags\n\n');
            }
            else if (square.flagged) {
              square.flagged = false;
              flags++;
              score.flagged--;
            }
            else if (!square.revealed) {
              square.flagged = true;
              flags--;

              if (square.mine) {
                score.flagged++;
              }
            }
          }

          // ...
        }
      }
    }
  });
})();

Keep track of an exploded mine

Finally, to keep track of whether the player exploded a mine while revealing a square, let’s set the score.exploded property to true within the lose condition.

(() => {
  // ...

  process.stdin.on('data', input => {
    const line = input.toString().trim();

    if (!username) {
      // ...
    } else {
      const match = line.match(/^(r|f)(\d+),(\d+)$/i);

      if (!match) {
        // ...
      }
      else {
        // ...

        if (row < 0 || col < 0 || row > grid.length - 1 || col > grid.length - 1) {
          // ...
        }
        else {
          // ...
          if (square.revealed && square.mine) {
            score.exploded = true;
            score.time = (Date.now() - score.time) / 1000;
            process.stdout.write('💥 Boooooom! Game over...\n\n');
            process.exit(0);
          }
          else if (checkRevealedSquares(grid) || checkFlaggedMines(grid)) {
            // ...
          }

          // ...
        }
      }
    }
  });
})();

💡 New to backend programming in Node.js?

Check out the Learn Backend Mastery Program — a complete zero-to-hero roadmap that takes you from beginner to job-ready junior Node.js backend developer in 12 months.

👉 learnbackend.dev

Step 14: Output the score

Calculate the total amount of points

Let’s define a new function named calculatePoints() that returns the total amount of points scored by the player using this formula: points = 10 x the number of safe squares revealed + 25 x the number of correctly flagged mines + 100 if the player won the game.

function calculatePoints(score) {
  return 10 * score.revealed + 25 * score.flagged + (score.exploded ? 0 : 100);
}

Save the score into a file

First, let’s create a new file named scores.json within the same directory as the minesweeper.js script, and write an empty array into it.

$ echo '[]' > scores.json

At the top of the script, let’s import the core Node.js fs module used to interact with the file system.

const fs = require('node:fs');

// ...

To save the player’s score into a file, let’s create a new function named updateScores() that:

Reads and parses the contents of JSON file that contains all the scores of all the games.
Adds the new score to the list.
Writes this list back into the file.
Returns the list.

function updateScores(username, score) {
  //
}

Within the function’s body, let’s:

Declare a new variable named file and initialize it with the path to the file that contains the list of scores.
Declare a new variable named scores and initialize it with null.
Return the scores variable.

function updateScores(username, score) {
  const file = './scores.json';
  let scores = null;

  return scores;
}

Let’s declare a try...catch block that will be used to gracefully handle and log any potential errors that may be thrown while attempting to read, parse, or write the file.

function updateScores(username, score) {
  const file = './scores.json';
  let scores = null;

  try {
    //
  }
  catch(error) {
    console.error(error.message);
  }

  return scores;
}

Let’s read the contents of the file using the fs.readFileSync() method and store it into the scores variable.

function updateScores(username, score) {
  const file = './scores.json';
  let scores = null;

  try {
    scores = fs.readFileSync(file, { encoding: 'utf8' });
  }
  catch(error) {
    console.error(error.message);
  }

  return scores;
}

Let’s convert the contents of the scores variable from a string to an array using the JSON.parse() method.

function updateScores(username, score) {
  const file = './scores.json';
  let scores = null;

  try {
    scores = fs.readFileSync(file, { encoding: 'utf8' });
    scores = JSON.parse(scores);
  }
  catch(error) {
    console.error(error.message);
  }

  return scores;
}

Let’s format and add the player’s username and new score to the array contained in the scores variable.

function updateScores(username, score) {
  const file = './scores.json';
  let scores = null;

  try {
    scores = fs.readFileSync(file, { encoding: 'utf8' });
    scores = JSON.parse(scores);
    scores.push({
      username,
      points: calculatePoints(score),
      time: score.time,
    });
  }
  catch(error) {
    console.error(error.message);
  }

  return scores;
}

Let’s stringify and write the scores array back into the file using the JSON.stringify() and fs.writeFileSync() methods.

function updateScores(username, score) {
  const file = './scores.json';
  let scores = null;

  try {
    scores = fs.readFileSync(file, { encoding: 'utf8' });
    scores = JSON.parse(scores);
    scores.push({
      username,
      points: calculatePoints(score),
      time: score.time,
    });
    fs.writeFileSync(file, JSON.stringify(scores), { encoding: 'utf8' });
  }
  catch(error) {
    console.error(error.message);
  }

  return scores;
}

Finally, within the IIFE, let’s declare a new undefined variable named scores and update its value by invoking the updateScores() function within both the winning and the losing conditions.

(() => {
  const size = parseGridSize();
  const grid = createGrid(size);
  let flags = size;
  let username;
  let score = {
    revealed: 0,
    flagged: 0,
    exploded: false,
    time: 0,
  };
  let scores;

  clearScreen();
  printWelcome();

  process.stdin.on('data', input => {
    // ...

    if (!username) {
      // ...
    } else {
      const match = line.match(/^(r|f)(\d+),(\d+)$/i);

      if (!match) {
        // ...
      }
      else {
        // ...

        if (row < 0 || col < 0 || row > grid.length - 1 || col > grid.length - 1) {
          // ...
        }
        else {
          // ...

          if (square.revealed && square.mine) {
            score.exploded = true;
            score.time = (Date.now() - score.time) / 1000;
            process.stdout.write('💥 Boooooom! Game over...\n\n');
            scores = updateScores(username, score);
            process.exit(0);
          }
          else if (checkRevealedSquares(grid) || checkFlaggedMines(grid)) {
            score.time = (Date.now() - score.time) / 1000;
            process.stdout.write('🏆 You win!\n\n');
            scores = updateScores(username, score);
            process.exit(0);
          }

          printPrompt();
        }
      }
    }
  });
})();

Output the score and the high scores

Let’s declare a new function named printScore() that outputs the player’s score, as well as the 10 highest scores saved in the scores.json file

function printScore(username, score, scores) {
  //
}

In the following format.

@razvan
Score: 20
Time: 5.397s
Revealed: 2
Flagged: 0

=== TOP 10 ===

1. V1kt0R       185    76.896s
2. john         30     71.991s
3. razvan       20     5.397s

Within the function’s body, let’s output the player’s username, points, game duration, number of safe squares revealed, and number of correctly flagged mines.

function printScore(username, score, scores) {
  process.stdout.write(`@${username}\n`);
  process.stdout.write(`Score: ${calculatePoints(score)}\n`);
  process.stdout.write(`Time: ${score.time}s\n`);
  process.stdout.write(`Revealed: ${score.revealed}\n`);
  process.stdout.write(`Flagged: ${score.flagged}\n`);
}

Let’s then:

Sort the scores in descending order based on their amount of points using the sort() method of the scores array
Only keep the first 10 elements of the array using the slice() method
Output each element using a for loop

function printScore(username, score, scores) {
  process.stdout.write(`@${username}\n`);
  process.stdout.write(`Score: ${calculatePoints(score)}\n`);
  process.stdout.write(`Time: ${score.time}s\n`);
  process.stdout.write(`Revealed: ${score.revealed}\n`);
  process.stdout.write(`Flagged: ${score.flagged}\n`);

  if (scores) {
    process.stdout.write('\n=== TOP 10 ===\n\n');

    let highScores = scores.sort((a, b) => {
      if (a.points > b.points) {
        return -1
      } else if (a.points < b.points) {
        return 1;
      } else {
        if (a.time < b.time) {
          return -1
        } else if (a.time > b.time) {
          return 1;
        }
        return 0;
      }
    }).slice(0, 10);

    for (let i = 0 ; i < highScores.length ; i++) {
      process.stdout.write(`${i + 1}. ${highScores[i].username.padEnd(12, ' ')} ${highScores[i].points.toString().padEnd(6, ' ')} ${highScores[i].time}s\n`);
    }
  }
}

Finally, let’s invoke the printScore() function within both the winning and the losing conditions using the value returned by the updateScores() function.

(() => {
  const size = parseGridSize();
  const grid = createGrid(size);
  let flags = size;
  let username;
  let score = {
    revealed: 0,
    flagged: 0,
    exploded: false,
    time: 0,
  };
  let scores;

  clearScreen();
  printWelcome();

  process.stdin.on('data', input => {
    // ...

    if (!username) {
      // ...
    } else {
      const match = line.match(/^(r|f)(\d+),(\d+)$/i);

      if (!match) {
        // ...
      }
      else {
        // ...

        if (row < 0 || col < 0 || row > grid.length - 1 || col > grid.length - 1) {
          // ...
        }
        else {
          // ...

          if (square.revealed && square.mine) {
            score.exploded = true;
            score.time = (Date.now() - score.time) / 1000;
            process.stdout.write('💥 Boooooom! Game over...\n\n');
            scores = updateScores(username, score);
            printScore(username, score, scores);
            process.exit(0);
          }
          else if (checkRevealedSquares(grid) || checkFlaggedMines(grid)) {
            score.time = (Date.now() - score.time) / 1000;
            process.stdout.write('🏆 You win!\n\n');
            scores = updateScores(username, score);
            printScore(username, score, scores);
            process.exit(0);
          }

          printPrompt();
        }
      }
    }
  });
})();

Final thoughts

Congratulations — you’ve built a fully playable Minesweeper CLI in Node.js with high score capabilities!

Thank you for reading and don’t hesitate to like, comment, and share if you enjoy my work

What’s next?

💾 Want to run this project on your machine? Download the source code for free here.

🚀 Go further: If you’re serious about backend development, check out the Learn Backend Mastery Program — a complete zero-to-hero roadmap to become a professional Node.js backend developer and land your first job in 12 months.

How to Build a Minesweeper CLI Game in Node.js (Part 2/3)

Razvan — Thu, 25 Sep 2025 07:13:32 +0000

Welcome back to Minesweeper Part 2.

Last time you built the core: grid, mine placement, and adjacency counts. Now you’ll wire it up into a fully playable CLI game.

Here's what you’ll add in this part:

A clean terminal UI: headers, separators, and aligned columns
A game loop with a visible prompt
Command parser for rROW,COL (reveal) and fROW,COL (flag)
Input validation + helpful error messages
Win/lose checks (boom vs. all mines flagged)

By the end, a single node minesweeper.js 9 gives you a working game you can extend in minutes.

Let’s build!

Step 6: Set up the game loop

Now that our grid generation process is complete, let’s initialize our game by:

Clearing the terminal window.
Printing a “Welcome” message that tells the user how to play the game.
Printing the formatted grid.
Prompting the user to play by typing a command.

Clear the terminal window

Let’s define a new function named clearScreen() that outputs the \x1Bc escape code to the standard output, which clears the console from any previous output.

function clearScreen() {
  process.stdout.write('\x1Bc');
}

Print a “Welcome” message

Let’s define a new function named printWelcome() that greets the user and tells them how to play.

Whenever prompted the user can:

Type rROW,COL to reveal a square (e.g., r0,3).
Type fROW,COL to flag/unflag a square (e.g., f2,4).

function printWelcome() {
  process.stdout.write('Welcome to MinesweeperJS!\n\n');
  process.stdout.write('> Type "rROW,COL" to reveal a square (e.g., r0,3).\n');
  process.stdout.write('> Type "fROW,COL" to flag/unflag a square (e.g., f2,4).\n\n');
  process.stdout.write('Got it? Let\'s play!\n\n');
}

For example:

r0,0 reveals the square at row 0, column 0.
f1,1 flags the square at row 1, column 1.

    0  1  2  3 
   ────────────
0 │ 2  ■  ■  ■ │
1 │ ■  ⚑  ■  ■ │
2 │ ■  ■  ■  ■ │
3 │ ■  ■  ■  ■ │
   ────────────

Prompt the user to play

Let’s define a new function named printPrompt() that outputs a > symbol, prompting the user to enter a command (e.g., r1,3 for revealing the square at row 1, column 3).

function printPrompt() {
  process.stdout.write('> ');
}

Print the formatted grid

Let’s define a new function named printGrid() that outputs the updated grid in the following format:

    0  1  2  3  4  5  6  7  8  9 
   ──────────────────────────────
0 │ 0  1  1  ■  *  ■  ■  ■  ■  ■ │
1 │ 0  2  ⚑  ■  ■  ■  ■  ■  ■  ■ │
2 │ 0  0  ⚑  ■  ■  ■  ■  ■  ■  ■ │
3 │ ■  ■  ■  ■  ■  ■  ■  ■  ■  ■ │
4 │ ■  ■  ■  ■  ■  ■  ■  ■  ■  ■ │
5 │ ■  ■  ■  ■  ■  ■  ■  ■  ■  ■ │
6 │ ■  ■  ■  ■  ■  ■  ■  ■  ■  ■ │
7 │ ■  ■  ■  ■  ■  ■  ■  ■  ■  ■ │
8 │ ■  ■  ■  ■  ■  ■  ■  ■  ■  ■ │
9 │ ■  ■  ■  ■  ■  ■  ■  ■  ■  ■ │
   ──────────────────────────────

Where:

The numbers at the top of the grid represent the column numbers of the grid.
The numbers on the side of the grid represent the row numbers of the grid.
The ■ symbols inside the grid represent the squares that haven’t yet been revealed.
The numbers inside the grid represent the squares that have already been revealed.
The ⚑ symbols inside the grid represent the squares that have been flagged.
The * symbols inside the grid represent a mine that exploded.

Within the function’s body, let’s first output the column numbers and the top grid separation line under each number.

function printGrid(grid) {
  process.stdout.write('   ');
  for (let i = 0 ; i < grid.length ; i++) {
    process.stdout.write(` ${i} `);
  }

  process.stdout.write('\n   ');
  for (let i = 0 ; i < grid.length ; i++) {
    process.stdout.write('───');
  }
  process.stdout.write('\n');
}

Let’s then start a for loop that, for each row, outputs:

The row number
The state of the square (unrevealed, adjacent mines, mine, or flagged)
The right grid separation line

function printGrid(grid) {
  process.stdout.write('   ');
  for (let i = 0 ; i < grid.length ; i++) {
    process.stdout.write(` ${i} `);
  }

  process.stdout.write('\n   ');
  for (let i = 0 ; i < grid.length ; i++) {
    process.stdout.write('───');
  }
  process.stdout.write('\n');

  for (let row = 0 ; row < grid.length ; row++) {
    process.stdout.write(`${row} │`);

    for (let col = 0 ; col < grid.length ; col++) {
      let square = grid[row][col];
      let char = '■';

      if (square.revealed) {
        char = square.mine ? '*' : String(square.adjacent);
      }
      else if (square.flagged) {
        char = '⚑';
      }
      process.stdout.write(` ${char} `);
    }
    process.stdout.write('│\n');
  }
}

Finally, let’s output the bottom grid separation line.

function printGrid(grid) {
  process.stdout.write('   ');
  for (let i = 0 ; i < grid.length ; i++) {
    process.stdout.write(` ${i} `);
  }

  process.stdout.write('\n   ');
  for (let i = 0 ; i < grid.length ; i++) {
    process.stdout.write('───');
  }
  process.stdout.write('\n');

  for (let row = 0 ; row < grid.length ; row++) {
    process.stdout.write(`${row} │`);

    for (let col = 0 ; col < grid.length ; col++) {
      let square = grid[row][col];
      let char = '■';

      if (square.revealed) {
        char = square.mine ? '*' : String(square.adjacent);
      }
      else if (square.flagged) {
        char = '⚑';
      }
      process.stdout.write(` ${char} `);
    }
    process.stdout.write('│\n');
  }

  process.stdout.write('   ');
  for (let i = 0 ; i < grid.length ; i++) {
    process.stdout.write('───');
  }
  process.stdout.write('\n\n');
}

Put it together

Let’s now invoke each of these functions within the IIFE in the following order.

(() => {
  const size = parseGridSize();
  const grid = createGrid(size);

  clearScreen();
  printWelcome();
  printGrid(grid);
  printPrompt();
})();

When launching the script, you should now see something similar in your terminal window.

$ node minesweeper.js 10
Welcome to MinesweeperJS!

> Type "rROW,COL" to reveal a square (e.g., r0,3).
> Type "fROW,COL" to flag/unflag a square (e.g., f2,4).

Got it? Let's play!

    0  1  2  3  4  5  6  7  8  9 
   ──────────────────────────────
0 │ ■  ■  ■  ■  ■  ■  ■  ■  ■  ■ │
1 │ ■  ■  ■  ■  ■  ■  ■  ■  ■  ■ │
2 │ ■  ■  ■  ■  ■  ■  ■  ■  ■  ■ │
3 │ ■  ■  ■  ■  ■  ■  ■  ■  ■  ■ │
4 │ ■  ■  ■  ■  ■  ■  ■  ■  ■  ■ │
5 │ ■  ■  ■  ■  ■  ■  ■  ■  ■  ■ │
6 │ ■  ■  ■  ■  ■  ■  ■  ■  ■  ■ │
7 │ ■  ■  ■  ■  ■  ■  ■  ■  ■  ■ │
8 │ ■  ■  ■  ■  ■  ■  ■  ■  ■  ■ │
9 │ ■  ■  ■  ■  ■  ■  ■  ■  ■  ■ │
   ──────────────────────────────
>

💡 New to backend programming in Node.js?

Check out the Learn Backend Mastery Program — a complete zero-to-hero roadmap that takes you from beginner to job-ready junior Node.js backend developer in 12 months.

👉 learnbackend.dev

Step 7: Read and parse user input

Let’s set up an event listener that will execute a callback function every time the standard input stream receives a 'data' event, which will be in turn triggered when the user presses the ENTER key.

(() => {
  // ...

  process.stdin.on('data', input => {
    //
  });
})();

Let’s convert the input into a string using the toString() method and clean it by removing any whitespaces and newlines before and after using the trim() method.

(() => {
  // ...

  process.stdin.on('data', input => {
    const line = input.toString().trim();
  });
})();

Step 8: Check the command format

Let’s use a regular expression that will match and extract the following pattern r|fROW,COL from the user input line, where:

rROW,COL is a command used to reveal a square at row ROW and column COL in the grid (e.g., r0,2).
fROW,COL is a command used to flag/unflag a square at row ROW and column COL in the grid (e.g., f3,9).

(() => {
  // ...

  process.stdin.on('data', input => {
    const line = input.toString().trim();
    const match = line.match(/^(r|f)(\d+),(\d+)$/i);
  });
})();

If the command is invalid because it doesn’t match the regular expression format:

Clear the terminal screen
Output an error message
Print the grid
Print the prompt

(() => {
  // ...

  process.stdin.on('data', input => {
    const line = input.toString().trim();
    const match = line.match(/^(r|f)(\d+),(\d+)$/i);

    if (!match) {
      clearScreen();
      process.stdout.write('Error: Invalid command\n\n');
      printGrid(grid);
      printPrompt();
    }
  });
})();

Step 9: Check the square position

If the command format is valid, extract and convert the command, the row number, and the column number.

(() => {
  // ...

  process.stdin.on('data', input => {
    const line = input.toString().trim();
    const match = line.match(/^(r|f)(\d+),(\d+)$/i);

    if (!match) {
      clearScreen();
      process.stdout.write('Error: Invalid command\n\n');
      printGrid(grid);
      printPrompt();
    }
    else {
      const cmd = match[1];
      const row = parseInt(match[2]);
      const col = parseInt(match[3]);
    }
  });
})();

If the square position is out of bounds (negative or greater than the grid’s last index):

Clear the terminal screen
Output an error message
Print the grid
Print the prompt

(() => {
  // ...

  process.stdin.on('data', input => {
    const line = input.toString().trim();
    const match = line.match(/^(r|f)(\d+),(\d+)$/i);

    if (!match) {
      clearScreen();
      process.stdout.write('Error: Invalid command\n\n');
      printGrid(grid);
      printPrompt();
    }
    else {
      const cmd = match[1];
      const row = parseInt(match[2]);
      const col = parseInt(match[3]);

      if (row < 0 || col < 0 || row > grid.length - 1 || col > grid.length - 1) {
        clearScreen();
        process.stdout.write('Error: Invalid square\n\n');
        printGrid(grid);
        printPrompt();
      }
    }
  });
})();

Step 10: Reveal a square

If the square position is valid and the command is rROW,COL:

Clear the terminal screen
Mark the square as revealed
Print the updated grid
Check if the square was a mine, output a “Game over” message, and terminate the process
Print the prompt

(() => {
  // ...

  process.stdin.on('data', input => {
    const line = input.toString().trim();
    const match = line.match(/^(r|f)(\d+),(\d+)$/i);

    if (!match) {
      clearScreen();
      process.stdout.write('Error: Invalid command\n\n');
      printGrid(grid);
      printPrompt();
    }
    else {
      const cmd = match[1];
      const row = parseInt(match[2]);
      const col = parseInt(match[3]);

      if (row < 0 || col < 0 || row > grid.length - 1 || col > grid.length - 1) {
        clearScreen();
        process.stdout.write('Error: Invalid square\n\n');
        printGrid(grid);
        printPrompt();
      }
      else {
        let square = grid[row][col];

        clearScreen();

        if (cmd === 'r') {
          square.revealed = true;
        }

        printGrid(grid);

        if (square.revealed && square.mine) {
          process.stdout.write('💥 Boooooom! Game over...\n\n');
          process.exit(0);
        }

        printPrompt();
      }
    }
  });
})();

Check if all squares are revealed

Let’s define a new function named checkRevealedSquares() that returns true if all the safe squares (the ones without mines) have been revealed, and false otherwise.

function checkRevealedSquares(grid) {
  const maxRevealed = (grid.length * grid.length) - grid.length;
  let count = 0;

  for (let row = 0 ; row < grid.length ; row++) {
    for (let col = 0 ; col < grid.length ; col++) {
      let square = grid[row][col];

      if (!square.mine && square.revealed) {
        count++;
      }
    }
  }
  return count === maxRevealed;
}

Let’s update the IIFE to invoke this function, output a “win” message if it returns true, and immediately terminate the process.

(() => {
  // ...
  let flags = size;

  process.stdin.on('data', input => {
    // ...

    if (!match) {
      // ...
    }
    else {
      const cmd = match[1];
      const row = parseInt(match[2]);
      const col = parseInt(match[3]);

      if (/* ... */) {
        // ...
      }
      else {
        // ...

        if (square.revealed && square.mine) {
          process.stdout.write('💥 Boooooom! Game over...\n\n');
          process.exit(0);
        }
        else if (checkRevealedSquares(grid)) {
          process.stdout.write('🏆 You win!\n\n');
          process.exit(0);
        }

        printPrompt();
      }
    }
  });
})();

Step 11: Flag a square

At the top of the IIFE, let’s declare a new variable named flags that will keep track of the number of flags available and initialize it to the size of the grid. Note that the number of flags available should equal the number of mines in the grid.

(() => {
  const size = parseGridSize();
  const grid = createGrid(size);
  let flags = size;

  // ...
})();

Within the if block that handles the “reveal” command, let’s add a condition that checks if the revealed square was previously flagged, unflag it and increase the number of flags available.

(() => {
  // ...
  let flags = size;

  process.stdin.on('data', input => {
    // ...

    if (!match) {
      // ...
    }
    else {
      const cmd = match[1];
      const row = parseInt(match[2]);
      const col = parseInt(match[3]);

      if (/* ... */) {
        // ...
      }
      else {
        let square = grid[row][col];

        clearScreen();

        if (cmd === 'r') {
          square.revealed = true;

          if (square.flagged) {
            square.flagged = false;
            flags++;
          }
        }

        // ...
      }
    }
  });
})();

Let’s create a new else...if block to handle the “flag” command, and within it let’s add 3 more checks:

If the square is unflagged and there are no more flags available, output an error message.
If the square is already flagged, unflag it and increase the number of available flags.
If the square is not yet revealed, flag it and decrease the number of available flags.

(() => {
  // ...
  let flags = size;

  process.stdin.on('data', input => {
    // ...

    if (!match) {
      // ...
    }
    else {
      const cmd = match[1];
      const row = parseInt(match[2]);
      const col = parseInt(match[3]);

      if (/* ... */) {
        // ...
      }
      else {
        let square = grid[row][col];

        clearScreen();

        if (cmd === 'r') {
          square.revealed = true;

          if (square.flagged) {
            square.flagged = false;
            flags++;
          }
        }
        else if (cmd === 'f') {
          if (!square.flagged && !flags) {
            process.stdout.write('Error: No more flags\n\n');
          }
          else if (square.flagged) {
            square.flagged = false;
            flags++;
          }
          else if (!square.revealed) {
            square.flagged = true;
            flags--;
          }
        }

        // ...
      }
    }
  });
})();

Check if all mines are flagged

Let’s define a new function named checkFlaggedMines() that returns true if all the mines have been correctly flagged, and false otherwise.

function checkFlaggedMines(grid) {
  let count = 0;

  for (let row = 0 ; row < grid.length ; row++) {
    for (let col = 0 ; col < grid.length ; col++) {
      let square = grid[row][col];

      if (square.mine && square.flagged) {
        count++;
      }
    }
  }

  return count === grid.length;
}

Let’s update the IIFE to invoke this function, output a “win” message if it returns true, and immediately terminate the process.

(() => {
  // ...
  let flags = size;

  process.stdin.on('data', input => {
    // ...

    if (!match) {
      // ...
    }
    else {
      const cmd = match[1];
      const row = parseInt(match[2]);
      const col = parseInt(match[3]);

      if (/* ... */) {
        // ...
      }
      else {
        // ...

        if (square.revealed && square.mine) {
          process.stdout.write('💥 Boooooom! Game over...\n\n');
          process.exit(0);
        }
        else if (checkFlaggedMines(grid) || checkRevealedSquares(grid)) {
          process.stdout.write('🏆 You win!\n\n');
          process.exit(0);
        }

        printPrompt();
      }
    }
  });
})();

Final thoughts

Congratulations!

You’ve built a playable Minesweeper CLI in Node.js — from grid generation and random mine placement to adjacency counts, flagging, and a simple command parser.

In Part 3, we’ll add the final touch to our game by storing the player’s username, score, and game duration into a file on the disk to create a “high score” screen.

Thank you for reading and see you in Part 3.

What’s next?

💾 Want to run this project on your machine? Download the source code for free here.

How to Build a Minesweeper CLI Game in Node.js (Part 1/3)

Razvan — Wed, 24 Sep 2025 06:48:16 +0000

In this tutorial, you’ll implement the classic Minesweeper game in its command-line interface version using nothing but Node, standard input/output, and a few clean algorithms.

Here’s a preview of what you’ll build:

In this part, you’ll learn how to:

Parse the grid size from the CLI
Generate a 2D grid and place random mines
Count adjacent mines using neighbor deltas

We’ll start from an empty file and finish in Part 3 with a fully functional game you can extend.

Ready? Let’s build!

Game Rules

At the start of the game, a fixed number of mines are randomly placed across a grid of size N by N, where each mine occupies a hidden square. The goal is to uncover all the safe squares on the grid without revealing a mine.

When you reveal a square:

If it contains a mine → you lose (game over).
If it does not contain a mine, it shows a number (0–8).

That number is the count of mines in the 8 surrounding squares (up, down, left, right, and diagonals). For example, if a square shows 2, exactly two of its neighbors contain mines.

You can also “flag” a square if you suspect it contains a mine.

You win either by:

Revealing all safe squares.
Correctly flagging all mines.

Step 0: Create the script

Let’s start by creating a new file named minesweeper.js and open it in a text editor.

$ code minesweeper.js

Step 1: Create an IIFE entry point

Within this file, let’s create the script’s entry point using an Immediately Invoked Function Expression (IIFE).

(() => {
  //
})();

Step 2: Create an empty grid

Above the IIFE, let’s define a new function named createGrid() that will be used to generate a new square grid of an arbitrary size.

function createGrid() {
  //
}

Within the function’s body, let’s declare a constant named size used to define the size of the grid and initialize with 6.

function createGrid() {
  const size = 6;
}

Next, let’s declare a constant named grid used to represent the two-dimensional grid, and initialize it with an array of arrays, where each element of the subarrays contains an object that represents a square, where:

mine indicates if it holds a mine
adjacent indicates how many mines are around
revealed indicates if the square was revealed
flagged indicates if the square was flagged

And let's return the grid array.

function createGrid() {
  const size = 6;
  const grid = Array.from({ length: size }, () => Array.from({ length: size }, () => ({
    mine: false,
    adjacent: 0,
    revealed: false,
    flagged: false
  })));

  return grid;
}

Finally, within the entry point, let’s declare a new constant named grid and initialize it with the value returned by the createGrid() function.

function createGrid() {
  /* ... */
}

(() => {
  const grid = createGrid();
})();

Note that in order the keep the code and the changes made to it as readable as possible, I’ll often comment already written parts using either one of the following expressions:

// ...
/* ... */

Step 3: Parse the grid size from the CLI

Let’s define a new function named parseGridSize() used to dynamically determine and set the size of the grid from the command-line interface.

function parseGridSize() {
  //
}

Within the function’s body, let’s declare a constant named size and initialize it with the value of the 3rd command-line argument of the script converted to an integer in base 10 using the parseInt() function.

function parseGridSize() {
  const size = parseInt(process.argv[2], 10);
}

Next, let’s return the converted value if it is a valid number comprised between 3 and 10 included, or 6 otherwise.

function parseGridSize() {
  const size = parseInt(process.argv[2], 10);
  return isNaN(size) || size < 3 || size > 10 ? 6 : size;
}

Then, let’s update the createGrid() function by:

Changing its signature to include a new parameter named size.
Removing the size constant from its body.
Invoking the createGrid() function using the value returned by the parseGridSize() function as argument.

function parseGridSize() {
  // ...
}

function createGrid(size) {
  const grid = Array.from(/* ... */);

  return grid;
}

(() => {
  const size = parseGridSize();
  const grid = createGrid(size);
})();

Which now allows us to execute the minesweeper.js script with an additional (and optional) argument .

$ node minesweeper.js 9

Step 4: Place random mines in the grid

Generate random number in a range

To be able to generate a random position in the grid, let’s first define a new helper function named generateRandomNumber() that returns a random integer in a range of values.

function generateRandomNumber(min, max) {
  return Math.floor(Math.random() * (max - min + 1)) + min;
}

Place mines in the grid

Let’s now define another function named placeMines() that randomly places N mines in the grid, where N is an integer equal to the size of the grid.

function placeMines(grid) {
  //
}

Within its body, let’s define two constants named min and max and initialize them with the lowest and the highest defined indexes in the grid array.

function placeMines(grid) {
  const min = 0;
  const max = grid.length - 1;
}

Let’s declare a variable named mines to count the number of mines placed in the grid and initialize it with 0.

function placeMines(grid) {
  const min = 0;
  const max = grid.length - 1;
  let mines = 0;
}

And let’s use a while loop to:

Generate at each iteration a random row and column number.
Check if the square at this position doesn’t already hold a mine.
Place a mine at this position.
Update the mines counter to keep track of how many mines have been placed.

function placeMines(grid) {
  const min = 0;
  const max = grid.length - 1;
  let mines = 0;

  while (mines < grid.length) {
    let row = generateRandomNumber(min, max);
    let col = generateRandomNumber(min, max);
    let square = grid[row][col];

    if (!square.mine) {
      square.mine = true;
      mines++;
    }
  }
}

Update the grid

Let’s update the createGrid() function and invoke the placeMines() function within it to update the newly generated grid.

function createGrid(size) {
  const grid = Array.from(/* ... */);

  placeMines(grid);
  return grid;
}

💡 New to backend programming in Node.js?

Check out the Learn Backend Mastery Program — a complete zero-to-hero roadmap that takes you from beginner to job-ready junior Node.js backend developer in 12 months.

👉 learnbackend.dev

Step 5: Compute and place numbers in the grid

Compute adjacent mines

Let’s define a new function named placeNumbers() that will for each square of the grid count how many adjacent squares hold a mine and update the value of its adjacent property accordingly.

function placeNumbers(grid) {
  //
}

Within its body, let’s set up two nested loops that will iterate on each square of each row, column by column, and skip the squares that hold a mine.

function placeNumbers(grid) {
  for (let row = 0 ; row < grid.length ; row++) {
    for (let col = 0 ; col < grid.length ; col++) {
      let square = grid[row][col];

      if (square.mine) {
        continue;
      }
    }
  }
}

Let’s declare a constant named deltas that contains a list of all the relative positions of the squares around.

function placeNumbers(grid) {
  const deltas = [
    [-1, -1], // top-left
    [-1, 0],  // top
    [-1, 1],  // top-right
    [0, 1],   // right
    [1, 1],   // bottom-right
    [1, 0],   // bottom
    [1, -1],  // bottom-left
    [0, -1],  // left
  ];

  for (let row = 0 ; row < grid.length ; row++) {
    for (let col = 0 ; col < grid.length ; col++) {
      let square = grid[row][col];

      if (square.mine) {
        continue;
      }
    }
  }
}

Let’s declare a for...of loop that iterates on each element of the deltas array, and checks if the position of the square minus or plus the value of the current delta is out of the bounds of the grid.

function placeNumbers(grid) {
  const deltas = [[-1, -1], [-1, 0], [-1, 1], [0, 1], [1, 1], [1, 0], [1, -1], [0, -1]];

  for (let row = 0 ; row < grid.length ; row++) {
    for (let col = 0 ; col < grid.length ; col++) {
      let square = grid[row][col];

      if (square.mine) {
        continue;
      }

      for (const [deltaX, deltaY] of deltas) {
        if (row + deltaX < 0 || row + deltaX > grid.length - 1 || col + deltaY < 0 || col + deltaY > grid.length - 1) {
          continue;
        }
      }
    }
  }
}

Let’s declare a variable named count that will keep track of the mines held in the adjacent squares present within the bounds of the grid, and update the adjacent property of the current square once the for...of loop has terminated.

function placeNumbers(grid) {
  const deltas = [[-1, -1], [-1, 0], [-1, 1], [0, 1], [1, 1], [1, 0], [1, -1], [0, -1]];

  for (let row = 0 ; row < grid.length ; row++) {
    for (let col = 0 ; col < grid.length ; col++) {
      let square = grid[row][col];

      if (square.mine) {
        continue;
      }

      let count = 0;

      for (const [deltaX, deltaY] of deltas) {
        if (row + deltaX < 0 || row + deltaX > grid.length - 1 || col + deltaY < 0 || col + deltaY > grid.length - 1) {
          continue;
        }
        if (grid[row + deltaX][col + deltaY].mine) {
          count++;
        }
      }

      square.adjacent = count;
    }
  }
}

Update the grid

Let’s update the createGrid() function and invoke the placeNumbers() function within it to update the grid.

function createGrid(size) {
  const grid = Array.from(/* ... */);

  placeMines(grid);
  placeNumbers(grid);
  return grid;
}

Final thoughts

Congratulations — you’ve built the full Minesweeper model: a square grid, randomly placed mines, and correctly computed adjacency numbers for every safe cell.

In Part 2, you’ll turn this model into a playable terminal game: render a readable grid, parse commands, update state, and handle win/lose conditions.

Thank you for reading and see you in Part 2.

What’s next?

💾 Want to run this project on your machine? Download the source code for free here.

How to Build a Guess-the-Number Game in Node.js (Step by Step)

Razvan — Wed, 24 Sep 2025 06:30:57 +0000

Welcome to Code in Action, a series where I walk you through coding a small project in Node.js.

Today’s project is a simple but powerful one: a Guess-the-Number game in the terminal.

Here’s what it does:

Asks the user to guess a random number between 1 and 100.
Tells the user if their guess is too high or too low.
Outputs the number of attempts it took to guess correctly.

Here’s a preview:

Ready? Let’s build it.

Step 1: Create the script

Let’s start by creating a new file named guess_the_number.js and opening it in your code editor:

$ touch guess_the_number.js

Step 2: Generate a random number

Inside this file, let’s create a helper function called generateRandomNumber() that returns a random integer between 1 and 100:

function generateRandomNumber() {
  const MIN = 1;
  const MAX = 100;

  return Math.floor(Math.random() * (MAX - MIN + 1)) + MIN;
}

Step 3: Set up the game

Now, let’s define a runGame() function that will generate the secret number, track the number of attempts made by the player, and print a “Welcome” message:

function runGame() {
  const number = generateRandomNumber();
  let attempts = 0;

  process.stdout.write('Welcome to Guess-the-Number!\n');
  process.stdout.write('\nGuess a number: ');
}

Step 4: Capture user input

Let’s set up an event listener that will fire every time the standard input stream receives a 'data' event:

function runGame() {
  const number = generateRandomNumber();
  let attempts = 0;

  process.stdout.write('Welcome to Guess-the-Number!\n');
  process.stdout.write('\nGuess a number: ');

  process.stdin.on('data', function (input) {
    //
  });
}

Then, let’s convert the user input into an integer and increment the attempts counter:

function runGame() {
  // ...
  process.stdin.on('data', function (input) {
    input = parseInt(input.toString().trim());
    attempts++;
  });
}

Step 5: Handle errors and winning condition

Let’s add a first condition that checks if the input is invalid and outputs an error message:

function runGame() {
  // ...
  process.stdin.on('data', function (input) {
    input = parseInt(input.toString().trim());
    attempts++;

    if (isNaN(input)) {
      process.stdout.write('\nError: Please enter a valid number\n');
    }
  });
}

Let’s add a second condition that checks if the input equals the secret number, output a “game over” message, and immediately terminate the script’s execution:

function runGame() {
  // ...
  process.stdin.on('data', function (input) {
    input = parseInt(input.toString().trim());
    attempts++;

    if (isNaN(input)) {
      process.stdout.write('\nError: Please enter a valid number\n');
    }
    else if (input === number) {
      process.stdout.write(`\n🏆 You win!\n📈 Attempts: ${attempts}\n`);
      process.exit(0);
    }
  });
}

Step 6: Handle wrong guesses

Let’s add two more conditions that check if the input is higher or lower than the secret number, and output an indicative message accordingly:

function runGame() {
  // ...
  process.stdin.on('data', function (input) {
    input = parseInt(input.toString().trim());
    attempts++;

    if (isNaN(input)) {
      process.stdout.write('\nError: Please enter a valid number\n');
    }
    else if (input === number) {
      process.stdout.write(`\n🏆 You win!\n📈 Attempts: ${attempts}\n`);
      process.exit(0);
    }
    else if (input > number) {
      process.stdout.write('🔺 Too high!\n');
    }
    else {
      process.stdout.write('🔻 Too low!\n');
    }
  });
}

Step 7: Wrap up the script

Let’s output a new prompt at the end of the callback to invite the user to enter a new number and execute the runGame() function at the end of the script:

function runGame() {
  // ...
  process.stdin.on('data', function (input) {
    // ...
    process.stdout.write('\nGuess a number: ');
  });
}

runGame();

Step 8: Put it together

Here’s the complete script for this project:

function generateRandomNumber() {
  const MIN = 1;
  const MAX = 100;

  return Math.floor(Math.random() * (MAX - MIN + 1)) + MIN;
}

function runGame() {
  const number = generateRandomNumber();
  let attempts = 0;

  process.stdout.write('Welcome to Guess-The-Number!\n');
  process.stdout.write('\nGuess the number: ');

  process.stdin.on('data', function(input) {
    input = parseInt(input.toString().trim());
    attempts++;

    if (isNaN(input)) {
      process.stdout.write('\nError: Please enter a valid number\n');
    }
    else if (input === number) {
      process.stdout.write(`\n🏆 You win!\n📈 Attempts: ${attempts}\n`);
      process.exit(0);
    }
    else if (input > number) {
      process.stdout.write('🔺 Too high!\n');
    }
    else {
      process.stdout.write('🔻 Too low!\n');
    }

    process.stdout.write('\nGuess a number: ');
  });
}

runGame();

Step 9: Run the game

Open a new terminal window and run your script with node:

$ node guess_the_number.js 
Welcome to Guess-The-Number!

Guess the number: 10
🔺 Too high!

Guess a number: 1
🔻 Too low!

Guess a number: 5
🔻 Too low!

Guess a number: 7
🔻 Too low!

Guess a number: 9

🏆 You win!
📈 Attempts: 5

You’ll be prompted to start guessing. Keep trying until you hit the right number!

Wrapping up

That’s it — you’ve built a complete CLI game in Node.js!

Along the way, you practiced:

Generating random numbers
Reading and validating user input
Using conditionals to branch logic
Tracking attempts with variables

What’s next?

👉 Want to run this project on your machine?
Download the source code for free at https://learnbackend.dev/code-in-action/guess-the-number

👉 Ready to go pro with backend development?
Join the Learn Backend Mastery Program today — a zero-to-hero roadmap to become a professional Node.js backend developer and land your first job in 12 months.

How to Build Your Own Linktree with Node.js + Express + Mustache (API + Frontend Page)

Razvan — Mon, 22 Sep 2025 06:47:40 +0000

Welcome back to Code in Action, the series where we build practical backend projects step by step.

In this tutorial, we’re going to recreate a simplified version of Linktree — the popular website that lets you share all your links from one single page.

Our version will be Linktree-Lite, built with Node.js + Express + Mustache, and it will include both:

A backend API to store and serve your links.
A simple frontend page that displays them in a clean list.

Why this project? Because it’s small enough to build in an afternoon, but realistic enough to show you how backends and frontends talk to each other.

You’ll practice API routes, Express basics, and even return a dynamic HTML page — skills that transfer directly into more advanced backend work.

By the end, you’ll have a working Linktree clone you can extend, customize, or add to your portfolio.

Step 1: Set Up the Project

Let’s start by creating a new directory named linktree-lite, and within it other directories named public/avatars for storing profile pictures and views for storing frontend templates.

$ mkdir -p linktree-lite/public/avatars linktree-lite/views

Let’s then add a picture in the PNG format into the public/avatars directory.

$ cp ~/Downloads/learnbackend.png linktree-lite/public/avatars/.

And let’s enter the project’s directory, initialize it (i.e. create the package.json file) and install the Express framework for building the API, as well as the Mustache template engine for converting templates into HTML files.

$ cd linktree-lite
$ npm init
$ npm install express mustache-express

Step 2: Create the Server

Within the root directory, let’s create a new file named server.js:

$ touch server.js

And within this file, let’s:

Import the express package.
Create a new server instance by invoking the top-level function exported by the package.
Bind the server to the development port 5000 using the listen() method of the server instance.

const express = require('express');

const server = express();

server.listen(5000, () => {
  console.log('Server running on port 5000...');
});

Step 3: Create a Database Object

In order to keep this project as simple as possible and focus on the logic of the endpoints, we’ll use an object literal as database with a single property named users, which will contains the entire list of user profiles.

let database = {
  users: {
    //
  }
};

Each profile will be stored under its unique username, and contain the following properties:

bio: a string that contains a short description of the profile
links: an array of objects that contains a list of personal URLs
socials: an object that contains a list of social platform handles
stats: an object that contains statistics about client IP addresses and link clicks

For example:

const express = require('express');

const server = express();

let database = {
  users: {
    'learnbackend': {
      bio: 'A zero-to-hero roadmap to become a professional Node.js backend developer in 12 months.',
      links: [
        {
          label: 'Learn Backend',
          url: 'https://learnbackend.dev'
        },
        {
          label: 'Mastery Program',
          url: 'https://learnbackend.dev/get-started'
        },
        {
          label: 'Skill Surge Challenge',
          url: 'https://learnbackend.dev/challenges/skillsurge'
        },
      ],
      socials: {
        youtube: 'learnbackend',
        medium: 'learnbackend'
      },
      stats: {
        ips: [],
        clicks: {
          links: [],
          socials: {},
        }
      }
    }
  }
};

server.listen(5000, () => {
  console.log('Server running on port 5000...');
});

Step 4: Render the Profile Page

Let’s declare a new HTTP GET endpoint in charge of retrieving a user profile based on its username, and serving it to the client in the form of an HTML file.

const express = require('express');

const server = express();

let database = {/* ... */};

server.get('/@:username', (req, res) => {
  //
});

server.listen(5000, () => {
  console.log('Server running on port 5000...');
});

Retrieve user data

Within the controller, let’s extract the username variable from the req.params query string parameters object, and convert it to lowercase using its toLowerCase() method.

// ...

server.get('/@:username', (req, res) => {
  const username = req.params.username.toLowerCase();
});

// ...

Let’s then use the username as key to retrieve the corresponding data from the database.users object, and respond with an HTTP 404 Not Found using the sendStatus() method of the response object if the username is not a valid key.

// ...

server.get('/@:username', (req, res) => {
  const username = req.params.username.toLowerCase();
  const user = database.users[username];

  if (!user) {
    return res.sendStatus(404);
  }
});

// ...

Format user data

If the username exists, let’s first declare an object named data that will contain the formatted data displayed on the HTML profile page, and let’s add the user’s username, bio, avatar URL, and personal links to it.

// ...

server.get('/@:username', (req, res) => {
  const username = req.params.username.toLowerCase();
  const user = database.users[username];

  if (!user) {
    return res.sendStatus(404);
  }

  let data = {
    username,
    bio: user.bio,
    avatar: `/avatars/${username}.png`,
    links: user.links
  };
});

// ...

Let’s then declare a socialUrlsMap object that implements a list of helper functions that take a social media handle and return the full URL to the profile on that platform.

// ...

server.get('/@:username', (req, res) => {
  const username = req.params.username.toLowerCase();
  const user = database.users[username];

  if (!user) {
    return res.sendStatus(404);
  }

  let data = {
    username,
    bio: user.bio,
    avatar: `/avatars/${username}.png`,
    links: user.links
  };

  const socialUrlsMap = {
    facebook: handle => `https://facebook.com/${handle}`,
    instagram: handle => `https://instagram.com/${handle}`,
    youtube: handle => `https://youtube.com/@${handle}`,
    x: handle => `https://x.com/${handle}`,
    medium: handle => `https://medium.com/@${handle}`
  };
});

// ...

Let’s use the methods of the socialUrlsMap object to map each account handle to its corresponding URL on the platform, and add it to the data object.

// ...

server.get('/@:username', (req, res) => {
  const username = req.params.username.toLowerCase();
  const user = database.users[username];

  if (!user) {
    return res.sendStatus(404);
  }

  let data = {
    username,
    bio: user.bio,
    avatar: `/avatars/${username}.png`,
    links: user.links
  };

  const socialUrlsMap = {
    facebook: handle => `https://facebook.com/${handle}`,
    instagram: handle => `https://instagram.com/${handle}`,
    youtube: handle => `https://youtube.com/@${handle}`,
    x: handle => `https://x.com/${handle}`,
    medium: handle => `https://medium.com/@${handle}`
  };

  data.socials = Object.keys(user.socials).map(platform => ({
    platform,
    url: socialUrlsMap[platform](user.socials[platform])
  }));
});

// ...

Finally, let’s temporarily respond to the client with an HTTP 200 OK containing the data object in the JSON format using the json() method of the response object until the rest of the implementation is complete.

// ...

server.get('/@:username', (req, res) => {
  const username = req.params.username.toLowerCase();
  const user = database.users[username];

  if (!user) {
    return res.sendStatus(404);
  }

  let data = {
    username,
    bio: user.bio,
    avatar: `/avatars/${username}.png`,
    links: user.links
  };

  const socialUrlsMap = {
    facebook: handle => `https://facebook.com/${handle}`,
    instagram: handle => `https://instagram.com/${handle}`,
    youtube: handle => `https://youtube.com/@${handle}`,
    x: handle => `https://x.com/${handle}`,
    medium: handle => `https://medium.com/@${handle}`
  };

  data.socials = Object.keys(user.socials).map(platform => ({
    platform,
    url: socialUrlsMap[platform](user.socials[platform])
  }));

  res.json({ data });
});

// ...

Set Up the Template Engine

In order to convert a template into a valid HTML page and serve it to the client, we need to tell Express which engine to use and how to use it.

So, let’s import the Node.js core path module and the mustache-express module, and:

Register the Mustache rendering function as the template engine.
Set 'mustache' as the file extension used for templates.
Set the ./views folder as the templates folder.

const express = require('express');
const path = require('node:path');
const mustacheExpress = require('mustache-express');

const server = express();

let database = {/* ... */};

server.engine('mustache', mustacheExpress());
server.set('view engine', 'mustache');
server.set('views', path.join(process.cwd(), 'views'));

// ...

And let’s not forget to tell Express to serve static assets, such as images, from the ./public directory, which will be used to include the avatar pictures in the profile page.

const express = require('express');
const path = require('node:path');
const mustacheExpress = require('mustache-express');

const server = express();

let database = {/* ... */};

server.engine('mustache', mustacheExpress());
server.set('view engine', 'mustache');
server.set('views', path.join(process.cwd(), 'views'));

server.use(express.static('public'));

// ...

Create the profile template

Within the ./views directory, let’s create a new file named profile.mustache.

$ touch views/profile.mustache

Within this file, let’s write the following Mustache template, where expressions such as {{username}} or {{platform}} will be replaced by the Mustache engine with actual values from the data object, such as learnbackend or instagram.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width,initial-scale=1" />
  <title>@{{username}} | Linktree-Lite</title>
  <style>
    body { font: 16px/1.4 system-ui, -apple-system, Segoe UI, Roboto, sans-serif; background:#0b0f14; color:#e6e6e6; display:grid; place-items:center; min-height:100vh; margin:0; }
    main { width: 560px; max-width: 92vw; padding: 60px 24px; border-radius: 16px; background:#121821; box-shadow: 0 8px 32px rgba(0,0,0,.35); }
    header { text-align:center; margin-bottom: 30px; }
    .avatar { width: 88px; height: 88px; border-radius: 999px; display:block; margin: 0 auto 8px auto; object-fit: cover; }
    .username { margin: 0 0 12px; font-size: 20px; }
    .bio { margin: 0 0 16px; color:#b8c1cc; }
    .socials { display:flex; gap:8px; justify-content:center; margin-top: 10px; margin-bottom: 40px; }
    .socials a { padding: 8px 10px; border-radius: 999px; background:#1b2431; text-decoration:none; color:#e6e6e6; }
    .socials a:hover { background:#232e3e; }
    .links a { display:block; margin: 10px 0; padding: 12px 14px; border-radius: 10px; background:#1b2431; text-decoration:none; color:#e6e6e6; text-align:center; }
    .links a:hover { background:#232e3e; }
  </style>
</head>
<body>
  <main>
    <header>
      <img class="avatar" src="{{avatar}}" alt="@{{username}} avatar" />
      <h1 class="username">@{{username}}</h1>
      <p class="bio">{{bio}}</p>
    </header>

    <div class="socials">
      {{#socials}}
        <a href="{{url}}">{{platform}}</a>
      {{/socials}}
    </div>

    <div class="links">
      {{#links}}
        <a href="{{url}}">{{label}}</a>
      {{/links}}
    </div>
  </main>
</body>
</html>

Render the template

Now that everything is set, let’s render the template and send an actual HTML profile page to the client by replacing the call to the json() method by the render() method, and pass it as arguments the name of the template file (without its extension) and the data object.

// ...

server.get('/@:username', (req, res) => {
  // ...

  res.render('profile', data);
});

server.listen(5000, () => {
  console.log('Server running on port 5000...');
});

Test the endpoint

You can now start the server by passing the server.js file as argument of the node utility.

$ node server.js

And open the following URL in your web browser 127.0.0.1:5000/@learnbackend, which should display a similar page.

Step 5: Count Profile Visits

To create simple statistics about profile visits, let’s store the IP address of each client into the stats.ips array of the user in the database object every time a request is routed to the HTTP GET /@:username endpoint.

// ...

server.get('/@:username', (req, res) => {
  const username = req.params.username.toLowerCase();
  const user = database.users[username];

  if (!user) {
    return res.sendStatus(404);
  }

  database.users[username].stats.ips.push(req.ip);

  // ...
});

// ...

Step 6: Count Links Clicked

To count how many times the links of a profile page have been clicked, we’ll use a mechanism called redirection.

Instead of directly displaying the personal and social media links to the profile page, we’re going to generate custom links that point to special API endpoints in charge of counting the clicks, then redirecting the users to the original URLs.

Count personal links clicked

Let’s declare a new HTTP GET endpoint in charge of counting how many times each personal link is clicked, and redirecting the user to the original URL.

// ...

server.get('/redirect/:username/link/:index', (req, res) => {
  //
});

// ...

Let’s extract and normalize the username and the index variables from the query string parameters object.

// ...

server.get('/redirect/:username/link/:index', (req, res) => {
  const username = req.params.username.toLowerCase();
  const index = parseInt(req.params.index, 10);
});

// ...

Let’s retrieve the user corresponding to the username in the database, and respond to the client with an HTTP 404 Not Found if the username doesn’t exist in the database.

// ...

server.get('/redirect/:username/link/:index', (req, res) => {
  const username = req.params.username.toLowerCase();
  const index = parseInt(req.params.index, 10);
  const user = database.users[username];

  if (!user) {
    return res.sendStatus(404);
  }
});

// ...

Let’s retrieve the original URL located at the specified index in the links array, and respond to the client with an HTTP 404 Not Found if the index doesn’t point to an existing element.

// ...

server.get('/redirect/:username/link/:index', (req, res) => {
  const username = req.params.username.toLowerCase();
  const index = parseInt(req.params.index, 10);
  const user = database.users[username];

  if (!user) {
    return res.sendStatus(404);
  }

  const url = user.links[parseInt(index)]?.url;

  if (!url) {
    return res.sendStatus(404);
  }
});

// ...

Let’s then increment the clicks counter of the corresponding element in the stats object by 1.

// ...

server.get('/redirect/:username/link/:index', (req, res) => {
  const username = req.params.username.toLowerCase();
  const index = parseInt(req.params.index, 10);
  const user = database.users[username];

  if (!user) {
    return res.sendStatus(404);
  }

  const url = user.links[parseInt(index)]?.url;

  if (!url) {
    return res.sendStatus(404);
  }

  user.stats.clicks.links[index] = (user.stats.clicks.links[index] || 0) + 1;
});

// ...

And finally, let’s check if the original URL starts with the string 'https://', prefix the URL with it if it doesn’t, and redirect the user to the URL using the redirect() method of the response object.

// ...

server.get('/redirect/:username/link/:index', (req, res) => {
  const username = req.params.username.toLowerCase();
  const index = parseInt(req.params.index, 10);
  const user = database.users[username];

  if (!user) {
    return res.sendStatus(404);
  }

  const url = user.links[parseInt(index)].url;

  if (!url) {
    return res.sendStatus(404);
  }

  user.stats.clicks.links[index] = (user.stats.clicks.links[index] || 0) + 1;

  res.redirect(/^https?:\/\//.test(url) ? url : `https://${url}`);
});

// ...

Update personal links in the template

Let’s now update the data.links array in the first endpoint, so that instead of including the personal URLs, it includes a list of special links that point to the previously defined API endpoint.

// ...

server.get('/@:username', (req, res) => {
  const username = req.params.username.toLowerCase();
  const user = database.users[username];

  if (!user) {
    return res.sendStatus(404);
  }

  let data = {
    username,
    bio: user.bio,
    avatar: `/avatars/${username}.png`,
    links: user.links.map((link, index) => ({
      label: link.label,
      url: `/redirect/${username}/link/${index}`
    }))
  };

  // ...
});

// ...

Count social media links clicked

Let’s declare a new HTTP GET endpoint in charge of counting how many times each social media link is clicked, and redirecting the user to the specified platform.

// ...

server.get('/redirect/:username/social/:platform', (req, res) => {
  //
});

// ...

Let’s extract and normalize the username and the platform variables from the query string parameters object.

// ...

server.get('/redirect/:username/social/:platform', (req, res) => {
  const username = req.params.username.toLowerCase();
  const platform = req.params.platform.toLowerCase();
});

// ...

Let’s retrieve the user corresponding to the username in the database, and respond to the client with an HTTP 404 Not Found if the username doesn’t exist in the database.

// ...

server.get('/redirect/:username/social/:platform', (req, res) => {
  const username = req.params.username.toLowerCase();
  const platform = req.params.platform.toLowerCase();
  const user = database.users[username];

  if (!user) {
    return res.sendStatus(404);
  }
});

// ...

Let’s remove the socialUrlsMap object from the HTTP GET /@:username endpoint and add it to this one instead, and respond with an HTTP 404 Not Found if the socialUrlsMap of the user’ socials object doesn't include the specified platform.

// ...

server.get('/redirect/:username/social/:platform', (req, res) => {
  const username = req.params.username.toLowerCase();
  const platform = req.params.platform.toLowerCase();
  const user = database.users[username];

  if (!user) {
    return res.sendStatus(404);
  }

  const socialUrlsMap = {
    facebook: handle => `https://facebook.com/${handle}`,
    instagram: handle => `https://instagram.com/${handle}`,
    youtube: handle => `https://youtube.com/@${handle}`,
    x: handle => `https://x.com/${handle}`,
    medium: handle => `https://medium.com/@${handle}`
  };

  if (!Object.keys(socialUrlsMap).includes(platform) || !user.socials[platform]) {
    return res.sendStatus(404);
  }
});

// ...

Finally, let’s increment the clicks counter of the corresponding social platform in the stats object by 1, and redirect the user to their profile on that platform.

// ...

server.get('/redirect/:username/social/:platform', (req, res) => {
  const username = req.params.username.toLowerCase();
  const platform = req.params.platform.toLowerCase();
  const user = database.users[username];

  if (!user) {
    return res.sendStatus(404);
  }

  const socialUrlsMap = {
    facebook: handle => `https://facebook.com/${handle}`,
    instagram: handle => `https://instagram.com/${handle}`,
    youtube: handle => `https://youtube.com/@${handle}`,
    x: handle => `https://x.com/${handle}`,
    medium: handle => `https://medium.com/@${handle}`
  };

  if (!Object.keys(socialUrlsMap).includes(platform) || !user.socials[platform]) {
    return res.sendStatus(404);
  }

  user.stats.clicks.socials[platform] = (user.stats.clicks.socials[platform] || 0) + 1;

  res.redirect(socialUrlsMap[platform](user.socials[platform]));
});

// ...

Update social links in the template

Let’s now update the first endpoint, so that the data.socials object contains an array of custom links that point to the new endpoint we’ve just defined.

// ...

server.get('/@:username', (req, res) => {
  const username = req.params.username.toLowerCase();
  const user = database.users[username];

  if (!user) {
    return res.sendStatus(404);
  }

  database.users[username].stats.ips.push(req.ip);

  let data = {
    username,
    bio: user.bio,
    avatar: `/avatars/${username}.png`,
    links: user.links.map((link, index) => ({
      label: link.label,
      url: `/redirect/${username}/link/${index}`
    })),
    socials: Object.keys(user.socials).map(platform => ({
      platform,
      url: `/redirect/${username}/social/${platform}`
    }))
  };

  res.render('profile', data);
});

// ...

Step 7: Retrieve User Visits and Clicks

Let’s declare a new HTTP GET endpoint in charge of retrieving a user statistics based on its username, and serving it to the client in the form of a JSON object.

// ...

server.get('/stats/:username', (req, res) => {
  //
});

// ...

Within the controller, let’s extract and normalize the username variable from the query string parameters object.

// ...

server.get('/stats/:username', (req, res) => {
  const username = req.params.username.toLowerCase();
});

// ...

Let’s use the username as key to retrieve its stats object, and respond with an HTTP 404 Not Found if the returned value is null.

// ...

server.get('/stats/:username', (req, res) => {
  const username = req.params.username.toLowerCase();
  let stats = database.users[username]?.stats;

  if (!stats) {
    return res.sendStatus(404);
  }
});

// ...

Let’s add a new property to the stats object called visits, and within it two properties called total and unique, where:

total: the total number of client IP addresses that connected to the server and loaded the profile page.
unique: the total number of unique IP address.

// ...

server.get('/stats/:username', (req, res) => {
  const username = req.params.username.toLowerCase();
  let stats = database.users[username]?.stats;

  if (!stats) {
    return res.sendStatus(404);
  }

  stats.visits = {
    total: stats.ips.length,
    unique: new Set(stats.ips).size
  };
});

// ...

Finally, let’s respond with an HTTP 200 OK containing the number of visits and clicks in the JSON format using the json() method of the response object.

// ...

server.get('/stats/:username', (req, res) => {
  const username = req.params.username.toLowerCase();
  let stats = database.users[username]?.stats;

  if (!stats) {
    return res.sendStatus(404);
  }

  stats.visits = {
    total: stats.ips.length,
    unique: new Set(stats.ips).size
  };

  return res.json({
    stats: {
      visits: stats.visits,
      clicks: stats.clicks
    }
  });
});

// ...

Test the endpoint

You can now press CTRL+C to stop the server and restart it with the following command.

$ node server.js

Then, you can run the following cURL command in your terminal, which should produce a similar output.

$ curl 127.0.0.1:5000/stats/learnbackend
{"stats":{"visits":{"total":10,"unique":3},"clicks":{"links":[1,2],"socials":{"youtube":2,"medium":1}}}}

Final thoughts

Congratulations!

You just shipped a working Linktree-Lite: one SSR profile page, clean JSON view-modeling, and click/visit analytics powered by server-side redirects.

Along the way you practiced Express routing, template rendering, data shaping, and simple tracking — exactly the building blocks real backends are made of.

Development ideas:

Add rate-limits to visits/clicks and ignore rapid repeats.
Persist data and create a tiny admin form to edit links.
Support themes and a “featured” link.

What’s next?

👉 Want to run this project on your machine?
Download the source code for free at https://learnbackend.dev/code-in-action/linktree-lite