What is the Node.js fs module?
© https://nodejs.org/en/

What is the Node.js fs module?

Built-in Node.js file system module

ByMario Kandut

honey pot logo

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.

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');

  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!');

  .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.


  • 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

More node articles:

Getting started with Webpack

How to list/debug npm packages?

How to specify a Node.js version

How to create a web server in Node.js

How to dynamically load ESM in CJS

How to convert a CJS module to an ESM

How to create a CJS module

How to stream to an HTTP response

How to handle binary data in Node.js?

How to use streams to ETL data?

How to connect streams with pipeline?

How to handle stream errors?

How to connect streams with pipe?

What Is a Node.js Stream?

Handling Errors in Node (asynchronous)

Handling Errors in Node.js (synchronous)

Introduction to errors in Node.js

Callback to promise-based functions

ETL: Load Data to Destination with Node.js

ETL: Transform Data with Node.js

ETL: Extract Data with Node.js

Event Emitters in Node.js

How to set up SSL locally with Node.js?

How to use async/await in Node.js

What is an API proxy?

How to make an API request in Node.js?

How does the Event Loop work in Node.js

How to wait for multiple Promises?

How to organize Node.js code

Understanding Promises in Node.js

How does the Node.js module system work?

Set up and test a .env file in Node

How to Use Environment Variables in Node

How to clean up node modules?

Restart a Node.js app automatically

How to update a Node dependency - NPM?

What are NPM scripts?

How to uninstall npm packages?

How to install npm packages?

How to create a package.json file?

What Is the Node.js ETL Pipeline?

What is data brokering in Node.js?

How to read and write JSON Files with Node.js?

What is package-lock.json?

How to install Node.js locally with nvm?

How to update Node.js?

How to check unused npm packages?

What is the Node.js fs module?

What is Semantic versioning?

The Basics of Package.json explained

How to patch an NPM dependency

What is NPM audit?

Beginner`s guide to NPM

Getting started with Node.js

Scroll to top ↑