TypeScript icon, indicating that this package has built-in type declarations

1.0.11 • Public • Published

NPM version Build Status


Scan-dir-recursive is a small library that allows you to list all files in a directory recursively with the possibility of ignoring some.


npm install scan-dir-recursive

Getting started

const scan = require("scan-dir-recursive");
scan(__dirname, function(files){
    console.log("Files:\n", files.join("\n"));

Api documentation

Async or sync

By default, a scan is done asynchronously but it is possible to do them synchronously too.

// Async
const scanAsync = require("scan-dir-recursive");
// or
const scanAsync = require("scan-dir-recursive/async");
// Sync
const scanSync = require("scan-dir-recursive/sync");

scanDirRecursive(directory, done, [ignore])

  • directory:String - Absolute path to the directory to scan
  • done:Function - Function to call when the scan is complete. Receive an Array of filenames as an argument
  • [ignore:Array] - Array of files to ignore


It is possible to use the async version with a javascript Promise.

const scan = require("scan-dir-recursive/promise");
scan(__dirname, IGNORED)
        console.log("Files:\n", files.join("\n"));

Notice that the done parameter is omitted since it is replaced by the Promise.

scanDirRecursive(directory, [ignore])

  • directory:String - Absolute path to the directory to scan
  • [ignore:Array] - Array of files to ignore

Returns a Promise that receive an Array of filenames when it resolve

Absolute path or relative path

By default, the files are listed with their absolute path. It is possible to get a path relative to the specified directory by using the relative version of the script.

const DIR = "/home/myUser/myProject/src";
// Absolute path
const absolute = require("scan-dir-recursive");
absolute(DIR, function(files){
    // "/home/myUser/myProject/src/file.js"
    // "/home/myUser/myProject/src/someDir/other.js"
// Relative path
const relative = require("scan-dir-recursive/relative");
relative(DIR, function(files){
    // "file.js"
    // "someDir/other.js"

Ignoring files

You can specify an Array of filenames or glob pattern to ignore in the results.

Assuming we have the following directory structure in /home/myUser/myProject/src

   |- a.js 
   |- b
   |  |-- b1/
   |  |     |-- b1.js
   |  |-- b2/
   |        |-- b2.js

When we run the following, the b/b1 branch and all its content will be ignored.

const path = require("path");
const scan = require("scan-dir-recursive");
const DIR = "/home/myUser/myProject/src";
const IGNORED = [
    path.resolve(DIR, "b/b1"),  // Ignored with absolute path
    "b/b1"  // Ignored with relative path
    "**/b/b1/**"                // Ignored with glob pattern
function onComplete(files){
scan(DIR, onComplete, IGNORED);
// [
//  "a.js",
//  "b/b.js",
//  "b/b2/b2.js"
// ]
// Ignored: "b/b1/b1.js",

Glob patterns are tested with the minimatch module. See their documentation for more information on how to use glob patterns.


Test can be run by using the test command:

npm run test

Coverage data can also be generated by running the coverage command:

npm run coverage

To view the coverage report, open coverage/lcov-report/index.html in the browser of your choice.



Package Sidebar


npm i scan-dir-recursive

Weekly Downloads






Unpacked Size

21.2 kB

Total Files


Last publish


  • polopelletier