File-Based Routing in Node.js: A Brief Guide

About a year ago, I tried Next.js for the first time and was so impressed by their file-based routing that I decided to implement a similar system on the backend. I couldn't find anything suitable, so I took it upon myself to create my own solution. It turned out to be technology-agnostic and works with both pure Node.js and the popular Express.js.

In this brief guide, we will attempt to partially implement a shop's API. This tutorial uses JavaScript and CommonJS module types to keep things simple and quick to get started.

1. Installation

💿 Install :

npm install node-file-router

2. Initialization

Create a server.js file and do the following:

If you use pure Node.js:

// 1. Import default http module and node-file-router
const http = require('node:http');
const { initFileRouter } = require('node-file-router');

// 2. Create an entry-point function
async function run() {
  // 3. Initialize node-file-router and the handler function
  const useFileRouter = await initFileRouter();

  const server = http.createServer((req, res) => {
    // 4. Create a server and invoke created function on each request
    useFileRouter(req, res);
  });

  // 5. Start listening a server on 4000 port
  const port = 4000;
  server.listen(port, () =>
    console.log(`Server running at //localhost:${port}/`)
  );
}

// 6. Run entry-point function
run();

If you use Express.js:

const { initFileRouter } = require('node-file-router');
const express = require('express');

async function run() {
  const fileRouter = await initFileRouter();

  const app = express();

  app.listen(4000);
  app.use(fileRouter);
}

run();

2. A first route

🏡 We will create a home route that displays welcome content.

1. Create an api folder at the root of your project.

├── api/ <-
├── server.js
└── package.json

2. Create a file named index.js inside this folder:

├── api/
│  └── index.js <-
├── server.js
└── package.json

module.exports = function index(req, res) {
  res.end("Welcome to our shop!");
}

3. Run a server using: node server.js command 4. Open a browser and navigate to //localhost:4000. You should see the message Welcome to our shop! displayed.

Congratulations! 🎉 You've created a first file route

3. Add HTTP methods

1. Before we start, we need a small utility function that will parse JSON from a request. Create a folder utils and put http.utils.js the file inside.

├── api/
├── ...
├── utils/
│  └── http.utils.js <-
...

module.exports = {
  parseJson(request) {
    return new Promise((resolve, reject) => {
      let data = '';

      request.on('data', (chunk) => {
        data += chunk;
      });

      request.on('end', () => {
        try {
          const parsedData = JSON.parse(data);
          resolve(parsedData);
        } catch (e) {
          reject(e);
        }
      });
    });
  }
}

2. Create a folder called products and an index.js file inside it.

├── api/
│  ├── products/ <-
│  │  └── index.js <-
│  └── ...
...

3. Implement get and post methods:

const { parseJson } = require('../../utils/http.utils');

module.exports = {
  get: (req, res) => {
    res.end('list of products');
  },
  post: async (req, res) => {
    const newProduct = await parseJson(req);
    res.end(`a product will be created: ${JSON.stringify(newProduct)}`);
  }
}

3. Open a browser and go to . You should see a list of products message displayed.

4. Make a POST request using curl, Postman or any tool you like on . The response should display a product will be created along with your content.

Perfect! 🎉 Let's move on

4. Dynamic routes

1. Create a new file with the name [id] inside the product folder.

├── api/
│  ├── products/
│  │  ├── ...
│  │  └── [id].js <-
│  └── index.js
...

2. Fill it the same way as you did before:

module.exports = {
  // Add the `routeParams` argument as the final argument to the function. This argument will contain
  // all the taken route parameters.
  get: (req, res, routeParams) => {
    const { id } = routeParams;
    res.end(`product ${id} info`);
  }
};

3. Open a browser and go to . <br/> The page should display a message: product 123.

Alright, let's make it more sophisticated.

Say, we want to address the following case: /catalog/tag-1/tag-2/tag-n

4. Create a catalog folder with [[...categories]].js inside.

├── api/
│  ├── catalog/
│  │  ├── ...
│  │  └── [[...categories]].js <-
│  ├── index.js
...

And add a single get method:

module.exports = {
  get: (req, res, routeParams) => {
    const { categories } = routeParams;

    // This type of route also covers just "/catalog"
    if (!categories) {
      return res.end('all products');
    }

    res.end(`get products that have such tags: ${categories}`);
  },
};

5. Open a browser and go to . The page should display a list of categories: men, sneakers, Nike.

🥁 That's it!

What's next?