What is the Node.js fs module?
Tags: node, javascript
Published: 2021-05-05 22:48:34

---
title: What is the Node.js fs module?
published: true
date: 2021-02-24 00:00:00 UTC
tags: node, javascript
canonical_url: https://www.mariokandut.com/what-is-the-node-fs-file-system-module/
---

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](https://nodejs.org/api/fs.html) for a full overview.

## [<svg aria-hidden="true" focusable="false" height="16" version="1.1" viewbox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg>](#using-the-fs-module)Using the fs module

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.

### [<svg aria-hidden="true" focusable="false" height="16" version="1.1" viewbox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg>](#relative-file-paths)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.',
);
```

### [<svg aria-hidden="true" focusable="false" height="16" version="1.1" viewbox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg>](#asynchronous--synchronous)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.

### [<svg aria-hidden="true" focusable="false" height="16" version="1.1" viewbox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg>](#promises-and-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](https://nodejs.org/api/fs.html#fs_promises_api). 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));
```

### [<svg aria-hidden="true" focusable="false" height="16" version="1.1" viewbox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg>](#filesystem-in-a-cloud-environment-ephemeral-filesystems)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.

## [<svg aria-hidden="true" focusable="false" height="16" version="1.1" viewbox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg>](#tldr)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](https://www.twitter.com/mariokandut)**.

If you want to know more about **[Node](https://www.mariokandut.com/tags/node)**, have a look at these [Node Tutorials](https://www.mariokandut.com/tags/node).

### [<svg aria-hidden="true" focusable="false" height="16" version="1.1" viewbox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg>](#references-and-big-thanks)References (and Big thanks):

[Node.js](https://nodejs.org/api/fs.html), [HeyNode](https://heynode.com/)