DEV Community: Ernesto Bellei

Documentation Should Not Be a Project

Ernesto Bellei — Thu, 11 Dec 2025 21:06:16 +0000

When developing an application ecosystem, be it large or small, complete and up-to-date documentation is a necessary foundation. As projects scale and evolve — such as the trend toward consolidating various applications into a monorepo — the documentation is under constant pressure for change. Maintaining a simple, universal structure across these different projects is vital for development speed and code comprehension.

Existing Solutions

When the moment arrives to share this documentation publicly, the available options generally fall into two main categories:

Static Site Generators (e.g., Docusaurus, VuePress, Jekyll): These offer maximum customization and are free to use, but they quickly become a separate software project to maintain. Dealing with dependency updates, theme management, and build issues adds significant maintenance overhead.
Hosted SaaS Platforms: Solutions like Read the Docs or other subscription-based services offer a ready-to-use hosting infrastructure. The primary drawback? A recurring monthly cost, which often seems disproportionate if you're only hosting a few basic Markdown pages.

Both paths inherently force a trade-off: time/maintenance versus operational cost.

Static Documentation, Client-Side Generation

Tired of the constant search for the ideal documentation management method, I set out to develop a hybrid, zero-maintenance solution to ensure clarity and simplicity for our smaller projects: mdGen.

mdGen is a static documentation generator designed to do one simple thing: take a folder full of .md files and instantly transform it into a navigable static HTML/CSS/JS website, ready to be downloaded and hosted anywhere.

Crucially, it uses neither cloud services nor server-side generators. Everything is generated statically and instantly within the user's browser (client-side).

By leveraging modern Filesystem APIs (where available), mdGen allows users to select a local folder and generate a real-time preview. This means the repository only contains the source .md files, and the preview can be managed completely independently.

Simplified Workflow and Advantages

Folder Selection: Simply load your local documentation folder.
Real-Time Preview: Thanks to Filesystem API Observers (all experimental features), any changes you save locally in your editor (VS Code, Sublime, etc.) are instantly reflected in the mdGen browser preview.
Instant Deploy: When satisfied, you simply click a button and download a .zip archive containing all the static assets (HTML, CSS, JS). These files can be uploaded to Netlify, Vercel, or any static CDN with zero ongoing maintenance or build costs.

Note: Filesystem APIs are not yet fully supported on Firefox and Safari, which currently limits the optimal user experience on those browsers.

Contribute

The project is still in an embryonic, primarily personal-use phase, but it is functional enough to be adopted:

Live Demo: mdgen.hund.studio
Source Code: GitHub - hund-studio/mdgen

While several limitations remain (e.g., the JS bundle can be optimized with chunk splitting, and the routing system is basic), the core goal is to deliver a lightweight, fast, and free solution.

MyNPM

Ernesto Bellei — Wed, 01 Oct 2025 15:37:15 +0000

Code 📄: https://github.com/hund-studio/mynpm

As projects grow, being able to rely on reusable packages — and why not, local ones — can become very convenient.
MyNPM makes managing local packages easy in 2 steps:

Add the paths containing your packages;
Install your local packages as a priority, and then, if necessary, fallback to public ones.

An example: When I work on a UI package, I always use a CSS helper function that helps me manage different conditional classes:

const css = (...classNames: (string \| number \| boolean \| null \| undefined)[]) =>
  classNames.flatMap((i) => (!!i ? [i] : [])).join(" ");

export default css;

It's just two lines of code, but repeating it in every project is a waste of time.
With MyNPM, I easily created a folder:

mkdir /home/ernesto/@packages/npm

I added it to my MyNPM sources:

mynpm add /home/ernesto/@packages/npm

And now I can install it in 2 ways:

Directly as a file: mynpm install css;
As a local package via the local package server: npm i css.

What’s the difference with a local package?

I can install packages from paths with unusual names or special characters;
The server will always provide the package updated with local changes, so I can test the latest code without bumping the version;
I can organize my packages under custom namespaces.

Installation

Currently, installation is quite basic:

Clone the repository;
Enter the package directory;
Run npm i -g --force (the --force flag allows updating older versions that are already installed)

After that, the mynpm command is available.

Commands

Command	Description
`mynpm add <pathname>`	Adds a source to the local NPM server
`mynpm start`	Starts the local NPM server
`mynpm startup`	Configures automatic startup
`mynpm help`	Shows the available commands
`mynpm install`	Installs a package (tries to install from path first, then locally, then from the public registry)

Contributing

Feel free to contribute! I acknowledge this is a very rough tool, but I add features as I need them.

Filesystem API-powered web apps are interesting

Ernesto Bellei — Mon, 06 May 2024 22:52:33 +0000

In the rapidly evolving landscape of web development, new frameworks, languages, and tools constantly emerge to fade into obscurity as quickly as they arise.

Find 5 minutes to read this

Nevertheless, there are other times when seemingly insignificant forum (and Google+, 🪦) discussions come out years later from the drawer of your subconscious ready to solve an annoying problem from your last project.

Filesystem APIs are one of those epiphany. One day, while working on our internal tool to manage the generation of internal documentation (quotations, contracts, etc.), I faced a dilemma: Where should I save this documentation?

Initially, I toyed with the idea of building an isolated database to store the generated documents for each project. However, the thought of not saving everything within the same filesystem, thus further fragmenting our already precarious folder organization, caused me a severe headache that triggered the retrieval of a feature I had heard about years before and had completely forgotten. I opened MDN, typed in "Filesystem," and there it was: Filesystem API, 90% fully supported by almost all browsers (damn you, Firefox), ready to be used.

Filesystem APIs are a feature that allows browsers to access and manipulate (as the name suggests) the filesystem on the user's computer. Of course, this is only possible with the user's authorization, similar to webcam or GPS location access. However, this feature enables the development of peculiar projects: projects that do not require a database as they directly interact with and write local files to disk, a sort of editor, you could say.

In the case of the project I was working on, this is how our studio filesystem works: At the base, there is a list of folders representing clients, each containing folders for individual projects.

AA-FirstClient/
├─ Project/
├─ Project/
AB-SecondClient/
├─ Project/
AC-ThirdClient/
├─ Project/

Using the Filesystem API, I can write a web app that, through a file picker, allows me to open a client's folder and create a new quotation, contract, or other documentation. This leads to another side effect: since the studio's filesystem automatically uploads to Dropbox and files are saved directly in the folders, they will sync online being available to the other team members who can access them using the online web app.

To quickly list the problems solved:

Filesystem API allows, for example, working with very large or heavy files without worrying about online storage as they will only live on the user's computer.
Filesystem API adds better security as files not being transferred over the network have much lower chances of being leaked.
Making the filesystem available through a cloud service (and clouds like Dropbox have rollback capabilities enabling a file history feature).

Another example

Once I understood the mechanism and functioning, I had fun finding other applications I had developed earlier to convert using the Filesystem API, and one in particular worked very well. For some months, I have been working on a tool (a collection of tools to manage music, combat, quick notes, etc) to help me master the role-playing game sessions I play with my friends. Before the introduction of Filesystem API, everything was handled from a local Node server to read and write files. Now I can quickly open a different folder for each played adventure, keeping everything separate and organized.

Conclusions

In conclusion, this article doesn't have a particular lesson or moral, and it will also need to be revised as I'm writing it very late at night. However, I hope it has sparked an idea in you, just as it did in me.

My failsafe development environment

Ernesto Bellei — Sun, 05 May 2024 11:19:48 +0000

The problem

As a developer, I live in the constant fear of losing my source code or ending up with an out-of-date branch on Git Hub due to last-minute-almost-on-production changes.
Besides that, I have to handle project synchronization between my devices...

Desktop workstation (where most of the work is done);
Laptop workstation (to work on-premises fix);
Local server (which is both a NAS and a dev-test server). ...and my cloud storage:
Github;
Dropbox;

That's how I solved my problem using:

Dropbox;
A BTRFS filesystem shared with NFS on my Local Ubuntu Server.

The workflow

Typically, when working on a project, I go through two phases:

The playground phase where code parts are tested/produced for general evaluations. Any material produced in this phase can be safely deleted afterward or doesn't need to be saved;
The development phase where the code specific to the application is actually produced and should only be saved on Dropbox if they are modules containing partial functionalities or test environments, and on both Dropbox and GitHub if it's final application code.

The setup

With that said, the solution I've found that works best for each device is outlined below.

Server

Starting with the server since it's the core of the entire system.
It's a small server I assembled myself, running Ubuntu Server 22.04 LTS to use it as both a NAS and a test server for applications.
The operating system is installed on a 250GB WD SSD, and it's connected with 2 WD Red Pro 6TB HDDs specifically designed for NAS. The disk configuration is as follows:

250GB SSD: Contains only the operating system;
2x 6TB HDDs: Configured in RAID1 using BTRFS and mounted on the OS at boot to /mnt/data.

All data is contained in the BTRFS filesystem (named "data") shared over the network using NFS share (which, from my tests, seems to be the only sharing system capable of decently supporting intensive write operations).

The "data" filesystem is organized as follows:

cloud/
├─ Dropbox/
local/
├─ ernesto-desktop/
│  ├─ bin/
│  ├─ bkp/
├─ ernesto-laptop/
│  ├─ bin/
│  ├─ bkp/
├─ ernesto-server/
│  ├─ bin/
│  ├─ bkp/
├─ playground/

The local folder should contain all the data that is needed to survive a device reinstall or configuration backup.
The cloud folder is where Dropbox will perform a complete sync of the entire cloud (to have a local copy of the entire cloud in case of emergency).

Note that I use a Dropbox business account, so I have no limits in terms of cloud space. If you're interested in how I installed Dropbox to work in a folder other than the user's home, leave me a comment, and I'll write an article about it.

Desktop & Laptop

Once the server is configured, all that's left is to install Dropbox on both the desktop and the laptop and mount the NFS share containing our cloud backup at startup.

Conclusion

This way, I can comfortably work on my code from the NFS share in both the playground and development phases. If I need to work on the go with my laptop, I can sync the projects I'm interested in using Dropbox and have a single control point (my dev server, which always contains the latest version of the code saved by Dropbox) to ensure that my GitHub repositories are in sync with the local ones.

How close are we to being able to create CLI executables with Node.js?

Ernesto Bellei — Wed, 20 Mar 2024 22:16:51 +0000

In recent days, I had the opportunity to revisit and reorganize the tools we use to set up our development environments. When we start a new development project, we always need two things:

A web server (usually Nginx);
A proxy to quickly share local or test instances both publicly and internally.

In addition to those two, many other secondary tools are currently all managed through a Node.js CLI tool. Hence my concern: before even being able to run the configuration tools, there is the need to install Node.js.

"And what if I wanted to get rid of this additional initial step as well?" — No one

In the past, I had already experimented with pkg (now archived), so I decided to dedicate a day to updating myself on the topic and improving our tools.

Step 1: Creating the bundle

The first step towards creating an executable is to generate a bundle of the CLI tool. I've delved into the tool I know best: Webpack.
Given that build efficiency and speed are not variables of our problem, Webpack allows me, with a couple of loaders, to quickly create a single entry point:

File webpack.config.js

...
{
    test: /\.tsx?$/,
    use: "ts-loader",
    exclude: /node_modules/,
},
{
    test: /\.(node)$/,
    loader: "node-loader",
},
...

In a few minutes, the bundle task is solved; we add a script to the package.json, and we are ready to proceed.

File package.json

"scripts" : {
...
    "bundle": "webpack",
...
}

Step 2: Creating a .blob file

The next step, now that we have our cli.js bundle in the dist folder, is to generate a .blob file that we will use to create our executable file. To do this, the first step is to define within a configuration file:

the entry point of our .blob (i.e., the bundle just created);
the output where the .blob file will be generate.

File seaconfig.json

{
    "main": "./dist/cli.js",
    "output": "./dist/cli.blob",
}

Once the configuration file is ready, the next step is to create our executable... here all the credit goes to Chad R. Stewart for saving me a lot of work. Here's a link to his article where he goes into more detail for each platform.

I will report here only the steps I had to execute on my Ubuntu machine:

Generate the .blob file:

node --experimental-sea-config seaconfig.json

Prepare the Node.js executable into which we will inject our file in order to prepare the final file.

Note: Currently, the version of Node.js I'm working with is 21.7.1.

cp $(command -v node) ./dist/server-tools

Finally, we inject the .blob file into our Node.js executable to complete the task (Depending on the platform, refer to the article linked above):

npx postject ./dist/server-tools NODE_SEA_BLOB ./dist/cli.blob --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2

At this point, I was ecstatic to have obtained a perfectly functioning executable of my CLI tool... until...

Step 3: Managing Static Assets

Testing it, I realized that, being a configuration tool, it used various static files as configuration templates, and those static files were not included inside my executable.

Fortunately, while researching how to work around this problem, I came across two useful resources:

With just a few modifications to the configuration file, I included the necessary files in the executable:

File seaconfig.json

{
    "main": "./dist/cli.js",
    "output": "./dist/cli.blob",
    "assets": {
        "default.txt": "./templates/default.txt",
        "default--ssl.txt": "./templates/default--ssl.txt",
        "next-js.txt": "./templates/next-js.txt",
        "next-js--ssl.txt": "./templates/next-js--ssl.txt",
        "patched.txt": "./templates/patched.txt"
    }
}

At this point, the last remaining step was to fix the code (in a very raw and quick way) from:

File addTemplate.ts

import { readFileSync } from "fs";
...
const content = readFileSync(resolve(__dirname, "templates", `${template}${ssl ? "--ssl" : ""}.txt`);

to:

File addTemplate.ts

import { getAsset } from "node:sea";
import { readFileSync } from "fs";
...
const content = (() => {
    try {
        return readFileSync( resolve(__dirname, "templates", `${template}${ssl ? "--ssl" : ""}.txt`), "utf-8" );
    } catch (error) {
        return getAsset(`${template}${ssl ? "--ssl" : ""}.txt`, "utf-8");
    }
})();

Only note: I also had to add a declaration to ensure that TypeScript didn't complain about the missing module:

File types.d.ts

declare module 'node:sea' {
    export function getAsset(filename: string, encoding: string): string;
}

Final thoughts

By the end of the day, I successfully achieved the desired outcome: My executable functions flawlessly on a pristine VPS without the need to install Node.js in advance.

Array iteration examples

Ernesto Bellei — Sun, 20 Nov 2022 18:52:24 +0000

This article tries to examine different real-life use cases which can be solved with Array methods.
For a technical definition of each method, every section has a link to the official 📄 MDN Reference. This article is about examples and tips, not documentation.

	Table of contents
	`map()`
	`every()`
	`find()`
	`filter()`
	`reduce()`
	`sort()`
	`every()`
BONUS	The spread iterator `...`

Map

📄 MDN REference

map() is probably the most used and versatile method out there, as MDN states:

Returns a new array containing the results of invoking a function on every element in the calling array.

Execute the same function on every item of the array

👨‍🏫 You have a bunch of data and want to run the same action on all of them.

const numbers = [1, 2, 3];

const numbersPlusOne = numbers.map((number) => number + 1);

// expected:
// numbersPlusOne: 2, 3, 4

Convert an array of configuration options to Class Instances

👨‍🏫 You have an array of different arguments and want to change them into Class Instances.

const peopleOptions = [
    {
        name: "Antonio",
        age: 13,
        height: 1.83,
    },
    {
        name: "Federico",
        age: 54,
        height: 0.9,
    },
    {
        name: "Ernesto",
        age: 27,
        height: 2.2,
    },
];

const people = peopleOptions.map((personOptions) => new Person(personOptions));

// expected:
// people: 👦, 👩, 👱

In React, render a list of whatever object

👨‍🏫 You want to render some UI elements using React.

// ... some React Component logic

const list = ["milk", "eggs", "cucumbers"];

return (
    <ul>
        {list.map((item, index) => (
            <li key={index}>{item}</li>
        ))}
    </ul>
);

Bonus Track: In combination with Promise.all()

In combination with Promise.all() can be used to wait for multiple async operations BUT:

⚠️ When using Promise.all() the asynchronous functions are not executed in the same order as the initial array. If you have asynchronous functions which need to run in an exact sequence (ae. update a record after a creation) you must use forEach() which will wait for each loop to be complete before continuing.

⚠️ Even though the asynchronous functions are executed in random order the output results array will preserve the same order as the initial array.

const membersName = ["Antonio", "Ernesto", "Federico"];

const membersAge = await Promise.all(
    members.map(async (memberName) => {
        const age = await getAgeFromDbWhereNameIs(memberName);

        return age;
    })
);

// Wait untill Promise is fullfilled

// expected:
// membersAge: 13, 27, 54

Every

📄 MDN Reference

This method can be used to check whether all elements inside an array fulfill a specific requirement.
This method is the only one that does not return an array whereas a boolean.

👨‍🏫 You want to filter an array and detect which items for a specific order are in stock and ready for shipment.

const order = [
    {
        name: "Tea Shirt",
        availableStock: 10,
    },
    {
        name: "Jeans",
        availableStock: 0,
    },
    {
        name: "Filp Flops",
        availableStock: 3,
    },
];

const isOrderReadyForShipment = order.every(
    (product) => product.availableStock > 0
);

// expected:
// isOrderReadyForShipment: false

Find

📄 MDN Reference

This method can be used to find the first element which matches a condition.

⚠️ This method will only return THE FIRST matching element, if there is more than one element that matches the condition it will be ignored.

👨‍🏫 You have a list of posts and want to get the first matching the tag yes.

const posts = [
    {
        title: "How to open your mind using a knife",
        author: "Ernesto",
        tag: "yes",
    },
    {
        title: "Let your dog do wathever he wants",
        author: "Federico",
        tag: "no",
    },
    {
        title: "How to escape from a glass cage",
        author: "Ernesto",
        tag: "yes",
    },
];

const yesPost = posts.find((post) => post.tag === "yes");

/**
 * expected:
 * yesPost:  {
 *    title: "How to open your mind using a knife",
 *    author: "Ernesto",
 *    tag: "yes",
 *  },
 */

Filter

📄 MDN Reference

Now that you are a find expert we can bring it to the next level. The filter method works the same as find but it returns all matching values instead.

It can be used for a couple of things such as...

Filter values that match certain criteria

👨‍🏫 You have a list of posts and want to get all posts matching the tag yes.

const posts = [
    {
        title: "How to open your mind using a knife",
        author: "Ernesto",
        tag: "yes",
    },
    {
        title: "Let your dog do wathever he wants",
        author: "Federico",
        tag: "no",
    },
    {
        title: "How to escape from a glass cage",
        author: "Ernesto",
        tag: "yes",
    },
];

const yesPosts = posts.filter((post) => post.tag === "yes");

/**
 * expected:
 * yesPost: [
 *  {
 *     title: "How to open your mind using a knife",
 *     author: "Ernesto",
 *     tag: "yes",
 *   },
 *  {
 *     title: "How to open your mind using a knife",
 *     author: "Ernesto",
 *     tag: "yes",
 *  }
 * ]
 */

Clean an array from unwanted/falsy values

When working with React you might have noticed that when using classes to style an is-active state sometimes you get dirty class names:

" undefined";
"false null another-class-name".

👨‍🏫 You want to create a function to clean classNames from unwanted/falsy values.

const active = false;

return <div className={[active && "is-active", "round-borders"].join(" ")} />;
// expected <div class="false round-borders">

const css = (...classNames: (string | undefined | null | false)[]) =>
    classNames.filter((className) => !className).join(" ");

return <div className={css(active && "is-active", "round-borders")} />;
// expected <div class="round-borders">

Sort

📄 MDN Reference

You have an array with 3 numbers [3, 18, 7, 18] which need to be sorted in "ASCending" order.
The sort method compares values two by two and depending on the value obtained subtracting one from another decide whether:

Condition			New order
`< 0`	3 - 18 = -15	keep 3 before 18	`[3, 18, 7, 18]`
`> 0`	18 - 7 = +11	exchange 18 with 7	`[3, 7, 18, 18]`
`= 0`	18 - 18 = 0	keep the same order	`[3, 7, 18, 18]`

const numbers = [3, 18, 7];

const sortedNumbers = numbers.sort((current, next) => curremt - next);

// expected:
// sortedNumbers: 3, 7, 18

The same method works with any kind of data:

Sorting dates

const events = [
    { name: "Social pic-nic", date: "12/11/2022" },
    { name: "Karate Lesson", date: "3/8/2022" },
    { name: "Pay Rent", date: "23/12/2022" },
];

const sortedEvents = events.sort((current, next) => current.date > next.date);

// expected:
// sortedNumbers: Karate Lesson, Social pic-nic, Pay Rent

Sorting alphabetical order

const words = ["alpha", "beta", "gamma"];

const sortedWords = events.sort((current, next) => current > next);

// expected:
// sortedWords: alpha, bbeta, gamma

Reduce

📄 MDN Reference

Reduce is so far the most complex but the most versatile method.
That said it can be used to run a function through every element of the array.

Get the sum of a specific item key value inside an array

👨‍🏫 Calculate the subtotal of all items inside a cart.

const cart = [
    {
        name: "T-shirt",
        qty: 1,
        price: 10000,
    },
    {
        name: "Hat",
        qty: 2,
        price: 20000,
    },
    {
        name: "T-shirt",
        qty: 1,
        price: 15000,
    },
];

const cartSubtotal = cart.reduce((cartSubtotal, item) => {
    const itemSubtotal = item.qty * item.price;
    return cartSubtotal + itemSubbtotal;
}, 0);

Manipulate data inside objects

In combination with Object.keys() the reduce method can be used to loop through javascript objects and manipulate their data.

👨‍🏫 Create two functions to remove or add given quantities of items from a cart.

⚠️ This cart variable is different from the previous. Previous one was an array, this is an object.

const cart = {
  productCodeSample1234: {
    name: "T-shirt",
    qty: 1,
    price: 10000,
  },
  sampleuniqueCode1234: {
    name: "Hat",
    qty: 2,
    price: 20000,
  },
  otherCodeSample01234: {
    name: "T-shirt",
    qty: 1,
    price: 15000,
  },
};

const addToCart = (uniqueCode: string, qty: number | undefined = 1) =>
  Object.keys(cart).reduce((cart, cartProductCode) => {
    if (cartProductCode === uniqueCode) cart[uniqueCode].qty += qty;
    return cart;
  }, cart); // add a given qty of products from your cart

const removeFromCart = (uniqueCode: string, qty: number | undefined = 1) =>{
  const updateItemsQuantity = Object.keys(cart).reduce((cart, cartProductCode) => {
    if (cartProductCode === uniqueCode) cart[uniqueCode].qty -= qty;
    return cart;
  }, cart); // remove a given qty of products from your cart}

  const updateItemsQuantity.filter(item => item.qty > 0); // remove ites with 0 or negative qty

The spread operator

📄 MDN Reference

Even though the spread operator is not directly related to array methods, rather than to all generic iterable objects, I thought it would have been useful to mention it in this compendium.

Add elements to an array

The ... spread operator means: repeating the items of an array (or the object keypairs) inside a new iterable object.
This allows us to clone an array inside another one while we add new items in between.

const lunchbbox = ["apple", "banana"];
const pencilCase = ["pen", "pencil"];

const backpack = ["tablet", ...lunchBox, "laptop", ...pencilCase];

// expected:
// backpack = ['tablet', 'apple', 'banana', 'laptop', 'pen', 'pencil']

👨‍🏫 If we need to create one function to add items from an array we will use the ... spread operator whereas we will use a filter method to remove them.

Override a default configuration

When you create a slider you probably set some default options (such as animation speed, and transition type ...) which can be overridden by another developer to customize it.

interface SliderConfig {
  animationSpeed: number;
  transitionType: "fade" | "slide",;
}

const defaultConfig: SliderConfig = {
  animationSpeed: 0.2,
  transitionType: 'slide'
};

const applyUserConfig = (userConfig: SliderConfig) => {
  return {
    ...defaultConfig,
    ...userConfig,
  };
};

const sliderConfig = applyUserConfig({
  animationSpeed: 0.4
})

/**
 * expected:
 * {
 *    animationSpeed: 0.4
 *    transitionType: 'slide'
 * }

Repeat arguments of concatenated complex functions

This is a complex and probably uncommon case but it can be useful to store it somewhere in your mind when difficult times will come.

The spread operator can be used to spread function arguments with a function that accepts a subset of given args. Its only need is to make the code more readable BUT it will require more attention because it reduces how freely you can edit and change the structure of your functions...as I said store it somewhere in your mind when difficult times will come.

const createAChocolateEgg = (
    height: number,
    width: number,
    chocolateType: string
) => {
    return `A ${chocolateType} chocolate egg, height: ${height}, width: ${width}`;
};

const createADecoratedChocolateEgg = (
    color: string,
    ...chocolateEggArgs: [number, number, string]
) => {
    return `${createAChocolateEgg(
        ...chocolateEggArgs
    )} whith ${color} sprinkles on it.`;
};

Dominate routing in Express

Ernesto Bellei — Sun, 23 Oct 2022 19:40:59 +0000

When a project starts growing in complexity, you might end up with different routes for API handling, page-serving, webhooks etc...

To avoid your index.ts to grow indefinitely one smart approach would be to divide all the different routes into groups (ae. by path, functionality, auth type etc...) and load them into your file. It can be done using different approaches to fit different levels of complexity.

I'm not a fan of overcomplicating the project with sophisticated dynamic loading if not strictly required.

Step 1: Create groups of routes

Let's say you want to group all API routes under the same /api URL path. The easiest solution would be to create a new express.Router;

const apiRouter = express.Router();

Append all the needed POST and GET routes to the newly created apiRouter...

apiRouter.get("/hello", async (request, response, next) => {
    try {
        return response.status(200).json({ foo: "bar" });
    } catch (e) {
        const error = createHttpError(500);
        return response.status(error.statusCode).json(error);
    }
});

apiRouter.get("/world", async (request, response, next) => {
    try {
        return response.status(200).json({ hello: "world" });
    } catch (e) {
        const error = createHttpError(500);
        return response.status(error.statusCode).json(error);
    }
});

...and finally, add your apiRouter to the express app

app.use("/api", apiRouter);

In my opinion, if your app has two or three /api routes grouping them using this system would be enough.
This configuration will allow you to apply specific middleware and custom rules to your /api routes with ease.

app.use("/api", apiRouter, passwordAuthenticationMiddleware);

Step 2: Store groups of routes inside different files

By now we grouped all the different routes but everything it is still inside the main index.ts file. As stated before, this is ok for a rather simple API with two or three small routes. As soon as the project grows in size and complexity grouping routes together wouldn't be enough and moving those routes to a different file will be necessary.

I would probably use a file structure similar to this one:

.
|--routes
|  |--api
|  |  |--hello
|  |  |  |--index.ts
|  |  |  |--get.ts
|  |  |--world
|  |  |  |--index.ts
|  |  |  |--get.ts
|  |  |  `--post.ts
|  |  `--index.ts
|  `--index.ts
|--public
`--index.ts

First of all, we have to 'pack' everything inside a ./routes folder and then import using a structure which mimics the routes paths structure:

GET  /api/hello

GET  /api/world
POST /api/world

Starting from the 'deeper' file which identifies the request type (GET, POST, PUT, PATCH...)and will contain the actual response return:

// 📄 ./routes/api/hello/get.ts
import { NextFunction, Request, Response } from "express";
import createHttpError from "http-errors";

const get = async (
    request: Request,
    response: Response,
    next: NextFunction
) => {
    try {
        return response.status(200).json({ foo: "bar" });
    } catch (e) {
        const error = createHttpError(500);
        return response.status(error.statusCode).json(error);
    }
};

export { get };

// 📄 ./routes/api/hello/index.ts
export { get } from "./get";

It is long and boring but always tries to create an index.ts file to export your function (you can eventually use a vsCode plugin).

Going up to ./routes/api we will need to assemble all our API routes using an /api router...

// 📄 ./routes/api/index.ts
import express from "express";
import { get as helloGet } from "./hello";
import { get as worldGet } from "./world";
import { post as worldPost } from "./world";

const router = express.Router();

router.get("hello", helloGet);
router.get("world", worldGet);
router.post("world", worldPost);

export { router };

// 📄 ./routes/index.ts
export { router as apiRouter } from "./api";

...and we are now ready to consume it...

// 📄 ./index.ts
import { apiRouter } from "./routes";

/* ...some in between code here... */

app.use("/api", apiRouter);

/* ...some in between code here... */

Now things are getting quite complex... but hey! your index.ts file is much clearer now and going through it in the distant future will be painless than using a single huge file.

I'm not a fan of overcomplicating the project with sophisticated dynamic loading if not strictly required.

Even though it might seem a huge Matrioska of code at some point it will be inevitable (unless you are planning to use some different framework, which is a smart choice too).

This brings us straight to...

Step 3: Create an automation to load all those routes automatically

Now. I know that many of you directly jump to this point because usually, the last point is the one which assembles everything in a working piece of code...BUT

I'm not a fan of overcomplicating the project with sophisticated dynamic loading if not strictly required.

For this reason, unless you are crying in pain because adding new routes has become impossible yet... you should give it a shot at Step 1 or Step 2 and check out if it is not worth stopping at that stage.

That said. Let's move forward.

⚠️ This solution might not fit your case: it has been written assuming that you are working on a plain and basic express application bundled with webpack >5.

Starting from here...

app.use("/api", apiRouter);

...our goal is to achieve something like that:

await loadRoutes(path.join(__dirname, "routes"), app);

A function that, given one entry path, load all our routes on our app.

First and foremost we need to define two functions which will allow us to get files and folders in a specific path, something like this perhaps:

const getSubfolders = (path: string) =>
    fs
        .readdirSync(path, { withFileTypes: true })
        .filter((file) => file.isDirectory());

const getFiles = (path: string) =>
    fs
        .readdirSync(path, { withFileTypes: true })
        .filter((file) => !file.isDirectory());

To start scraping recursively from top to bottom we need to wrap everything in a function which will lately call itself, starting from the routesRoot folder and will append all the found middlewares to the generated routes. Let's do it one step at a time.

const loadRoutes = async (routesRoot: string, router: Router) => {};

Inside our loadRoutes folder we will start looking for subfolders (we are not interested in files here since we are inside the root and we do not expect to find any middleware here).

To import all routers and middlewares from the routes tree we will use a dynamic import, this way webpack will be aware of what kind of chunks has to bundle separately.

Since dynamic imports are async functions we need to use a lot of await and Promise.all().

Let's start scraping our root folder and create relative paths which we will use inside dynamic imports (disclaimer: this relative path is requested to use dynamic imports. It won't work with absolute paths):

const loadRoutes = async (routesRoot: string, router: Router) => {
    await Promise.all(
        getSubfolders(routesRoot).map(async ({ name }) => {
            const subFolder = `${routesRoot}/${name}`;
            const relativePath = path.relative(__dirname, subFolder);
        })
    );
};

Given this structure:

.
|--routes
|  |--api
|  |  |--hello
|  |     `-get.ts
|  `--welcome
|     |--index.ts
|     |--get.ts
|     `--post.ts
|--public
`--index.ts

We are now mapping api and welcome folders and their relative path will be routes/api and routes/welcome.

Next step is to create/import an express.Router() our rule will be:

If the subfolder contains an index.ts file we will try to export an express.Router() out of it;
If the index.ts file does not exist we will create a brand new router to handle the routes;

We can do something like this:

const loadRoutes = async (routesRoot: string, router: Router) => {
    await Promise.all(
        getSubfolders(routesRoot).map(async ({ name }) => {
            const subFolder = `${routesRoot}/${name}`;
            const relativePath = path.relative(__dirname, subFolder);

            let subRouter: Router;

            try {
                const { default: customRouter } = await import(
                    `./${relativePath}/index.ts`
                );
                subRouter = customRouter;
            } catch (e) {
                subRouter = express.Router();
            }

            router.use(`/${name}`, subRouter);
        })
    );
};

You might have noticed that our loadRoutes accepts two parameters:

routesRoot: is the path of our routes root folder form which we will start importing files and folders;
router: is the initial router that we want to attach our routes (ad example the app router created with the express app).

Ok, let's recap a bit. Now we are scraping each subfolder and creating a sub router which will handle all routes contained in the such folder;

routers:
app.use(apiRouter)
  `--apiRouter.use(helloRouter)

app.use(welcomeRouter)

Now we must implement our scraping folder to look not only for subfolders and index.ts files but for get, post, put etc... files

Something like this:

type ExpressRouterRequestMethod =
    | "all"
    | "get"
    | "post"
    | "put"
    | "delete"
    | "patch";

const loadRoutes = async (routesRoot: string, router: Router) => {
    const expressRouterRequestMethod = [
        "all",
        "get",
        "post",
        "put",
        "delete",
        "patch",
    ];

    await Promise.all(
        getSubfolders(routesRoot).map(async ({ name }) => {
            const subFolder = `${routesRoot}/${name}`;
            const relativePath = path.relative(__dirname, subFolder);

            let subRouter: Router;

            try {
                const { default: customRouter } = await import(
                    `./${relativePath}/index.ts`
                );
                subRouter = customRouter;
            } catch (e) {
                subRouter = express.Router();
            }

            await Promise.all(
                getFiles(subFolder).map(async ({ name }) => {
                    const requestMethodName = name.replace(".ts", "");

                    try {
                        if (expressRouterRequestMethod.includes(requestMethodName)) {
                            const { default: customMiddleware } = await import(
                                `./${relativePath}/${requestMethodName}.ts`
                            );

                            subRouter[requestMethodName as ExpressRouterRequestMethod](
                                "/",
                                customMiddleware
                            );
                        }
                    } catch (e) {
                        console.log(e);
                    }
                })
            );

            await loadRoutes(path.join(__dirname, subFolder), subRouter);

            router.use(`/${name}`, subRouter);
        })
    );
};

As you can see, at the time of writing, I Had to manually specify the accepted request method and check them manually otherwise typescript will complain a lot. This is ugly and dirty so comment/writes to me if you find a more elegant way. Check out the express docs here.

This way we are basically importing every valid router request type and attaching it to the right router in order to have a structure like this one:

routers:
app.use(apiRouter)
  `--apiRouter.use(helloRouter)
    `--helloRouter.get(getHelloMiddleware)

app.use(welcomeRouter)
  |--welcomeRouter.get(getWelcomeMiddleware)
  `--welcomeRouter.get(postWelcomeMiddleware)

The last step is to export everything in the right format. In step 2 we grouped everything using routers to apply middlewares to multiple routes. We can keep that structure by reworking it a bit to simply our dynamic import

// 📄 ./routes/api/hello/get.ts
import { NextFunction, Request, Response } from "express";
import createHttpError from "http-errors";

- const get = async (
+ const middleware = async(
    request: Request,
    response: Response,
    next: NextFunction
) => {
    try {
        return response.status(200).json({ foo: "bar" });
    } catch (e) {
        const error = createHttpError(500);
        return response.status(error.statusCode).json(error);
    }
};

- export { get };
+ export default middleware;

// 📄 ./routes/api/index.ts
import express from "express";
- import { get as helloGet } from "./hello";
- import { get as worldGet } from "./world";
- import { post as worldPost } from "./world";

const router = express.Router();

+ router.use(authMiddleware); // this is useful to apply a middleware to all subroutes

- router.get("hello", helloGet);
- router.get("world", worldGet);
- router.post("world", worldPost);

- export { router };
+ export default router; // export default instead of named export

The next step will probably create a separate file and import this function from there or whatever you like the most.

This is my five cents about express routing handling on small applications.
The entire article could be resumed as follows:

Don't overcomplicate your application ahead of time, with 2 routes you don't need anything overcomplicated as it will cause stupid problems during the prototyping phase;
Beware of copy/pasting because once you start adding ts + webpack + custom loaders + whatever you will have to adjust your setup accordingly.

Stupid problems I faced while writing this

To read, write and scan files and directories freely on webpack remember to enable this option inside your webpack.config.js;

node: {
__dirname: true,
}

When using dynamic import webpack automatically manage the bundle without specifying any particular entry option to create custom output bundles;
When using dynamic imports try to keep as much as possible plain string paths. That's why I'm using ./${relativePath}/${requestMethodName}.ts instead of ${name}, when using variables webpack will try to match all possible escaped paths warning you for each not existing file.

That's it, I guess. Bye 👋