What is the Node.js fs module?

This article is based on Node v16.14.0.

The built-in Node.js file system module enables interaction with the file system on the operating system. It is available in every Node.js project, there is no need to install it. The file system module gives us access to useful functions for reading files, writing to files, watching for file changes and many more. Have a look at the official documentation for a full overview.

Using the fs module

💰 The Pragmatic Programmer: journey to mastery. 💰 One of the best books in software development, sold over 200,000 times.

To use the file system module, require it. No need to install it, since it's part of the core module.

const fs = require('fs');

Commonly used features of the fs module to store, access, and manage data are:

• fs.readFile to read data from a file,
• fs.writeFile to write data to a file (also replaces the file if it already exists),
• fs.watchFile to watch a file and get notified about changes, and
• fs.appendFile to append data to a file.

Relative file paths

The majority of the fs methods take the file path as the first argument. You have to option an absolute or a relative path. Relative paths will begin with a single dot (.), which indicates from the current directory, or two dots (..), which indicates from the parent directory.

When using a relative path (like ../file.md) with the fs module the path will be resolved from the perspective of the current working directory where you run the script in or where the program was executed, not from the current file. This behaviour is different compared to require. This is prone to errors, and you have to pay close attention to how you specify paths.

To specify a path relative to the file it is being executed in the __dirname keyword is of specific help. The __dirname keyword expands to the absolute path of the directory of the file it is used in. For example, if you use __dirname from a file in /folder/subfolder/file.js, the value would be /folder/subfolder. Relative file paths and __dirname can also be combined to create a relative lookup.

To join the two paths (from __dirname and the relative path to the file) and create a full path, you can use a Node.js core module path. The method join from the path module allows us to create a cross-platform filepath.

const fs = require('fs');
const path = require('path');

fs.writeFile(
  path.join(__dirname, '/output.md'),
  'Hello World! I am relative to the directory this scripts inherits.',
);

Asynchronous || Synchronous

All I/O operations in Node.js are done async to avoid blocking the event loop. Hence, the methods provided by the fs module are, by default, async and callback-based. As many modules in the Node.js ecosystem, there is a synchronous version as well, for example readFileSync.

In general, the best practice is to use async code, when working with the filesystem or other heavy operations. In some rare cases it could be that you want to do something first and block the execution until this specific thing is done. Loading configuration data on application startup could be such a case, see code below.

const fs = require('fs');
const config = JSON.parse(fs.readFileSync('./configFile.json');

Besides, this rare use case, always use async code when accessing the file system.

Promises and File System

The fs/promises API provides asynchronous file system methods that return promises. It was added in 2018 in Node.js v.10.0.0. In Node.js version 10 the promise support is experimental (console warnings), since Node.js version 11 it's fully supported.

The promise-based file system methods work the same as the callback-based ones, though there is no synchronous version of promises. Basically, instead of a callback a Promise is returned, see code snippet below:

const fs = require('fs').promises;

const writePromise = fs.writeFile('./output.txt', 'Hello World!');

writePromise
  .then(() => console.log('success!'))
  .catch(err => console.error(err));

Filesystem in a cloud environment (ephemeral filesystems)

There is not always a persistent filesystem in the current environment available. Locally it is easy to persist files and interact with them later again. In cloud environments this is not always possible. For example the filesystem in AWS Lambda functions is only persisted for a short period. With the cloud host Heroku this is the same case, because of an ephemeral filesystem for the virtual machines used. Ephemeral file system only persist files for a short time, on a restart of a virtual machine the files created at runtime are gone.

Don't store state or uploads as files on a ephemeral file system, because the data can't be persisted.

TL;DR

• FS enables interactions with the file system
• Consider using __dirname and the path module to create full paths
• Use ASYNC methods to not block execution.
• Use SYNC methods only in rare cases (for example: loading configs before execution)
• You can use promises with the fs (since Node.js v.10)
• Don't store state or uploads as files on a ephemeral file system.

Thanks for reading and if you have any questions, use the comment function or send me a message @mariokandut.

If you want to know more about Node, have a look at these Node Tutorials.

References (and Big thanks):

Node.js, HeyNode