How to Use fs.readdir in Node.js?

fs.readdir() is an essential method in Node.js vital for file management tasks. It enables the reading of a directory’s contents. As a component of the built-in ‘fs’ module, it asynchronously retrieves the names of files and subdirectories within a specified path.

This simple yet potent function enables developers to efficiently enumerate and process directory contents, which makes it an essential tool for JavaScript applications on the server and backend.

By mastering fs.readdir(), developers can perform more sophisticated file system operations in Node.js.

What is NodeJS?

NodeJS is an open-source, server-side JavaScript runtime environment built on Chrome’s V8 JavaScript engine. It enables developers to use JavaScript for both front-end and back-end development.

It supports cross-platform compatibility and offers non-blocking, event-driven architecture that enhances system performance and data transfer speed. Integrated with NPM (Node Package Manager), NodeJS provides access to a vast ecosystem of packages and tools.

Its lightweight design and efficient handling of simultaneous tasks make it ideal for developing scalable, high-performance web applications.

What is the fs.readdir() method?

fs.readdir() is a method in Node.js that is used to read the contents of a directory asynchronously. This method returns an array of file and subdirectory names within the specified directory.

Imagine a digital filing cabinet explored through Node.js, with fs.readdir() as a trusty assistant for peeking inside any chosen folder.

Once invoked, fs.readdir() diligently rummages through the specified directory, compiling a comprehensive list of its contents, including files and subfolders. The result is a neatly packaged array containing all the discovered names, making it a valuable tool for beginners and experienced developers.

Syntax of fs.readdir() method

The fs.readdir() method’s standard syntax follows the structure

fs.readdir(path, options, callback)

• path: represents the target directory for exploration
• options: provides an optional configuration object for customizing the search parameters
• callback: defines the function responsible for processing the retrieved results.

This will be better illustrated using the examples in the next section.

Examples of fs.readdir() method

This section discusses some real-time examples of how the fs.readdir() method can be used.

Example 1: Basic Directory Reading

This example demonstrates how to read the contents of the current directory using fs.readdir(). It lists all files and subdirectories in the console.

Assume the directory in question is the one shown in the screenshot below

The code can look something like this :

const fs = require('fs');



// Read the contents of the Sample Directory

fs.readdir('C:\\Users\\itadmin\\Desktop\\Sample Directory', (err, files) => {

  if (err) console.log(err);

  else {

    console.log("Contents of Sample Directory:");

    // Iterate through the array of file names and log each one

    files.forEach(file => {

      console.log(file);

    });

  }

});

And the output will be –

Contents of Sample Directory:
report1.pdf
presentation.pdf
screenshot.png
document.pdf
diagram.png
Contract.pdf

Example 2: Reading with File Types

This example shows how to use the withFileTypes option to get additional information about each entry, distinguishing between files and directories.

For this example, a folder called images has been added to the directory used in the previous example

const fs = require('fs');



// Read directory contents with additional file type information

fs.readdir('C:\\Users\\itadmin\\Desktop\\Sample Directory', { withFileTypes: true }, (err, files) => {

  if (err) console.log(err);

  else {

    console.log("Contents of Sample Directory with file types:");

    // Iterate through the array of Dirent objects

    files.forEach(entry => {

      // Log the name and whether it's a directory or file

      console.log(`${entry.name}, ${entry.isDirectory() ? "directory" : "file"}`);

    });

  }

});

And the output will be

Contents of Sample Directory with file types:
report1.pdf, file
presentation.pdf, file
screenshot.png, file
document.pdf, file
diagram.png, file
contract.pdf, file
images, directory

How to use fs.readdir() in Node.js?

The following steps offer a simple guide to use fs.readdir() in Node.js

Step 1: Setting Up the Project

• Verify that Node.js is installed on the system.
• Create a new folder for the project and navigate to it using a terminal or command prompt.
• Create a JavaScript file, such as readDirectory.js.

Step 2: Importing the fs Module

The fs module, which handles file system operations, is required at the start of the script.

const fs = require('fs');

Step 3: Using fs.readdir()

The fs.readdir() function reads the contents of a directory. It takes two arguments:

• directory path
• callback function

fs.readdir(__dirname, (err, files) => {

  if (err) {

    console.log("Error reading directory:", err);

  } else {

    console.log("Current directory contents:");

    files.forEach(file => console.log(file));

  }

});

• __dirname: Refers to the directory containing the script.
• err: Captures any errors encountered during the operation.
• files: Contains an array of file and folder names.

Step 4: Running the Script

To execute the script, use the following command in the terminal:

node readDirectory.js

This will provide a list of the directory contents.

Handling Errors in fs.readdir() method

Issues such as inaccessible files, insufficient permissions, or incorrect directory paths can result in errors in the fs.readdir() method.

The below examples explore these situations:

Example 1: Handling Incorrect Directory Paths

Code:

const fs = require('fs');



// Attempt to read the contents of a non-existent directory

fs.readdir('/invalid/path', (err, files) => {

  if (err) {

    // Log the error message if the directory does not exist

    console.error("Error reading directory:", err.message);

  } else {

    // Log the directory contents if no error occurs

    console.log("Files:", files);

  }

});

Output:

Error reading directory: ENOENT: no such file or directory, scandir ‘/invalid/path’

Example 2: Handling Permission Issues

This example demonstrates handling errors due to insufficient permissions to access a directory.

Code:

const fs = require('fs');



// Attempt to read a restricted directory

fs.readdir('/restricted', (err, files) => {

  if (err) {

    // Log a permission error message if access is denied

    console.error("Permission error:", err.message);

  } else {

    // Log the directory contents if no error occurs

    console.log("Files:", files);

  }

});

Output:

Permission error: EACCES: permission denied, scandir ‘/restricted’

Example 3: Graceful Fallback on Errors

This example provides a fallback message to handle errors gracefully.

Code:

const fs = require('fs');



// Attempt to read the contents of a specified directory

fs.readdir('./data', (err, files) => {

  if (err) {

    // Provide a user-friendly message if the directory cannot be read

    console.error("Could not read the directory. Please check the path.");

  } else {

    // Log the directory contents if no error occurs

    console.log("Directory contents:", files);

  }

});

Output:

The output of the third example depends on whether the directory ./data exists and is accessible.

If the directory exists and is accessible it will display the directory contents such as:

If the directory does not exist, the output will be

The output will be the same if the directory exists, but permissions are restricted.

Best Practices of using fs.readdir in Node.js

When using fs.readdir() in Node.js, some best practices are :

1. Implement robust error handling by always including error checks in the callback function. This ensures your application can gracefully manage scenarios like non-existent directories or permission issues.
2. Utilize asynchronous methods and avoid blocking the event loop, which means using fs.readdir() instead of its synchronous counterpart fs.readdirSync() to maintain application responsiveness and performance.
3. Leverage the withFileTypes option to efficiently retrieve additional file information, reducing the need for multiple system calls and providing more detailed insights about directory contents in a single operation.
4. Consider implementing pagination or stream-based approaches for large directories to prevent memory overload, especially when dealing with directories containing thousands of files or complex nested structures.

Test Your Node.js Applications on Real Devices with BrowserStack

Testing on real devices is essential to ensure Node.js applications work flawlessly across various devices.

BrowserStack’s Real Device Cloud offers access to thousands of real iOS and Android devices, enabling developers to test their applications under real-world conditions. This cloud-based solution eliminates the need for in-house device labs, saving time and costs while providing accurate results across different OS versions and screen sizes.

Some benefits of testing your Node.js applications on real device cloud with BrowserStack:

• Real-world Testing: Simulates actual user conditions across various devices, ensuring the app performs as expected.
• Comprehensive Coverage: Access thousands of real iOS and Android devices across different models, OS versions, and screen sizes.
• Cost and Time Savings: Eliminates the need for in-house device labs, reducing overhead and maintenance costs.
• Accurate Results: Test on real devices ensures more reliable and precise feedback than emulators or simulators.
• Cross-Platform Compatibility: Verify app performance and responsiveness across multiple operating systems and device configurations.

Talk to an Expert

Conclusion

Modern versions of Node.js’ fs.readdir() offer developers a flexible and effective method for examining the contents of directories, including recursive searching and file type detection.

Developers can generate efficient, robust file system operations that seamlessly manage directory exploration across various Node.js environments.