Built-in Node.js file system module
By Mario Kandut
Europe’s developer-focused job platform
Let companies apply to you
Developer-focused, salary and tech stack upfront.
Just one profile, no job applications!
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.
💰 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.readFileto read data from a file,
fs.writeFileto write data to a file (also replaces the file if it already exists),
fs.watchFileto watch a file and get notified about changes, and
fs.appendFileto append data to a file.
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.
__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
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
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.', );
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
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.
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));
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.
pathmodule to create full paths
Thanks for reading and if you have any questions, use the comment function or send me a message @mariokandut.
Never miss an article.