node package manager
It’s your turn. Help us improve JavaScript. Take the 2017 JavaScript Ecosystem Survey »


What is "ls"?

ls is a node module for cleanly traversing directories and listing files.

The primary goal is a flexible, expressive syntax.


$ npm i ls


First require:

var ls = require('ls');

Then we can be as sparse as

for (var file of ls('/path/*')) {

Or as elaborate as

  { recurse: true },
  file => console.log `${} is in ${$file.path} and is ${file.stat.size}`


The only required argument is the initial path, the rest can be omitted.

ls([path/s], {config}, /file regex/, iteratorFunction)

Each file produces an object with the following parameters:

  • full: The path and file (/foo/bar/baz.jpg)
  • path: The path to the file (/foo/bar/)
  • file: The file (baz.jpg)
  • name: The file without an extension (baz)
  • stat: A lazy loaded stat object from fs.Stats

You can either grab the whole list

all_files = ls('/path/*')
for (var file of all_files) {
  console.log(, 'is', file.stat.size);

Or use an iterator function, with the context being the file's object

var prettysize = require('prettysize');
ls('/tmp/*', file => console.log(`${} is ${prettysize(file.stat.size)}`));

The {config} object accepts the following parameters:

  • recurse: Should we recurse into directories? (Boolean, default is false)
  • type: What kind of files should we return? ('all', 'dir', 'file', default is 'all')

The /regex/ will only return matching files. All directories will still be recursed.

The iterator function is mostly a style preference, but can be handy if you need to throw an error and stop traversal.


ls is UNLICENSED. Do whatever you want with it.