A cross platform utility interface for working with filesystems in Node.js.


A cross platform interface for working with the file system in Node.js programs. Yes, it works with both posix and win32. So there.

Built by @kixxauth

The most common use of Filepath is to use it as a library. In that case, just include it in your Node.js project by adding a line for "filepath" in your pacakge.json dependencies. For more information about your package.json file, you should check out the npm documentation by running npm help json.

Alternatively, you can quickly install Filepath for use in a project by running

npm install filepath

which will install filepath in your node_modules/ folder.

var FP = require('filepath')
// FilePath.create just takes a string to create a new path object:
var path = FP.create(__filname)
assert(path instanceof FP.FilePath)
// It's important to remember that a FilePath instance is *not* a String.
// The 'path' property of a FilePath instance is the string representation
// of the FilePath instance, which is the same thing as calling .toString().
assert(path.path === path.toString())
// Defaults to current working directory if you don't pass any arguments:
var path = FP.create()
assert(path.toString() === process.cwd())
// Joins multiple arguments into a single path object:
var path = FP.create(__dirname, 'foo')
assert(path.toString() === __dirname + '/foo')
// Handy shortcut class method.
assert(FP.root().toString() === '/')
// Another handy shortcut class method.
assert(FP.home().toString() === '/home/kris')
var path = FP.create(__dirname).append('foo', 'bar').append('baz')
assert(path.toString() === __dirname + '/foo/bar/baz')
var path = FP.create('/home/kris/filepath', 'lib').resolve('../')
assert(path.toString() === '/home/kris/filepath/')
var path = FP.create('/home/kris/filepath/lib')
assert(path.toString() === '../test')
var path = FP.create('/home/kris/filepath').dir();
assert(path.toString() === '/home/kris')
var path = FP.create('/home/kris/filepath/').basename();
// Note that basename() returns a *String*
assert(path === '')
var ext = FP.create('/home/kris/filepath/').extname()
// Note that extname() returns a *String*
assert(ext === '.md')
var parts = FP.create('/home/kris/filepath/').split()
assert(parts[0] === 'home')
assert(parts.pop() === '')
var path = FP.create(__dirname)
var path = FP.create(__filename)
var path = FP.create(__dirname)
var li = FP.create(__dirname).list()
// Listing a directory returns an Array of fully resolved FilePath instances
assert(li[4] instanceof FP.FilePath)
assert(li[4].toString() === '/home/kris/filepath/')
FP.create(__dirname).recurse(function (path) {
  // Each listing is a FilePath object with a fully resolved path string.
  assert(path instanceof FP.FilePath)
  assert(path.toString().indexOf(__dirname) === 0)
// Works kinda like 'mkdir -P'.
var path = FP.create('/tmp/some/new/deep/dir').mkdir()
assert(path instanceof FP.FilePath)
var FS = require('fs')
var stream = FP.create(__filename).newReadStream()
assert(stream instanceof FS.ReadStream)
var FS = require('fs')
var stream = FP.create('/tmp/new_file.txt').newWriteStream()
assert(stream instanceof FS.WriteStream)
var path = FP.create(__filename)
// #read() returns a promise object with #then() and #failure() methods. (contents) {
  // Defaults to 'utf8' so you get a string here instead of a Buffer.
  assert(typeof contents === 'string')
// Or you can read a file *synchronously*:
var readmeContents ={sync: true})
assert(typeof readmeContents === 'string')
var path = FP.create('/tmp/new_file.txt')
// #write() returns a promise object with #then() and #failure() methods.
// Writes the file contents in 'utf8' by default.
path.write('Hello world!\n').then(function (returnedPath) {
  assert(returnedPath === path)
  assert({sync: true}) === 'Hello world!\n')
// Or you can write a file *synchronously*:
var syncPath = FP.create('/tmp/new_file_sync.txt')
syncPath.write('Overwrite with this text', {sync: true})
assert({sync: true}) === 'Hello world!\n')
var path = FP.create(__filename)
var originalContent ={sync: true})
// #copy() returns a promise object with #then() and #failure() methods.
path.copy('/tmp/').then(function (target) {
  // The callback value (`target`) is a new FilePath instance.
  assert(target.toString() === '/tmp/')
  assert({sync: true}) === originalContent)
// Or you can copy a file *synchronously*:
syncPath = FP.create(__dirname, 'package.json')
originalSyncContent ={sync: true})
syncTarget = syncPath.copy('/tmp/package.json')
assert(syncTarget.toString() === '/tmp/package.json')
assert({sync: true}) === originalSyncContent)

To run the tests, just do

npm test

You should see the test results output.

Copyright (c) 2013-2015 by Kris Walker (

Unless otherwise indicated, all source code is licensed under the MIT license. See LICENSE for details.