node package manager



NPM version Downloads Build Status Coverage Status Tip

Promise-based file-system adapter and transmogrifier.


$ npm install --save spiff


The simplest usage of spiff copies files from one location to another.

import { read, write } from 'spiff';

That's all well and good, but it's not very interesting. Let's change the files.

import { read, write } from 'spiff';
    // Replace all whitespace with a single space.
    .map(cssFile => {
        cssFile.contents = cssFile.contents.replace(/\s+/, ' ');
        return cssFile;

That did the trick. But look at all that code just to change one property. We can do better.

import { read, write } from 'spiff';
    // Replace all whitespace with a single space.
    .mapProp('contents', x => x.replace(/\s+/, ' '))

Now we're talking! But we're spitting out each file individually. Let's bundle them.

import { file, read, write } from 'spiff';
    // Replace all whitespace with a single space.
    .mapProp('contents', x => x.replace(/\s+/, ' '))
    // Concatenate multiple files into one.
        // Add each css file to the bundle.
        (bundle, cssFile) => {
            bundle.contents += cssFile.contents;
            return bundle;
        // Start with a new empty file.


The find and read functions return special type of Promise object called a ListPromise. These lists provide a means of iterating through items with maximum concurrency, but are ultimately just Promises. Therefore, you can await the results.

async function bundleAssets() {
    await read('src/scripts/**/*.js')
    await read('src/styles/**/*.css')

See the ListPromise documentation for more information on the available iteration methods.


file([options, [contents]]) : VinylRW

  • options Object
    • cwd String (default: process.cwd()) Current working directory.
    • base String (default: cwd) Base path from which to derive relative paths.
    • path String File path.
  • contents {String|Buffer|Stream} - (default: null) File contents.

Creates a new VinylRW file.

file('', '# TODO');

find(glob, [options]) : ListPromise<VinylRW>

  • glob String|Array<String>
  • options Object Options for globby.

Finds files matching a glob pattern and provides them as a Promise-aware list of VinylRW objects. Does not read file contents into memory.

    .map(x => x.path)

read(glob, [options]) : ListPromise<VinylRW>

  • glob String|Array<String>
  • options Null|String|Object If null or a string, value is used as the encoding when reading. If an object, options for globby and fs.readFile.
    • encoding {String} (default: 'utf8') File encoding. Set to null to use Buffers instead of Strings.

Finds files matching a glob pattern and provides them as a Promise-aware list of VinylRW objects that can be mapped, filtered, reduced, and sorted. Reads file contents into memory.

// text files
// special encoding
read('src/data/**/*.csv', 'ucs2')
// binary files
read('src/images/**/*.png', null)

remove(glob) : Promise

  • glob String|Array<String>

Permanently deletes files and directories.


write([dir, [options]]) : Function

  • dir String (default: file.base) Optional alternate directory in which to write a file. By default, files will be saved to their current .path value.
  • options Object Options for fs.writeFile.

Returns a callback that accepts a VinylRW file and writes it to the file system, optionally in a different location.

callback(fileObj) : VinylRW

  • fileObj VinylRW The VinylRW file to be written.

Writes a file to the file system based on the file's path property. Returns the file so that you may continue iterating after writing.



Standards for this project, including tests, code coverage, and semantics are enforced with a build tool. Pull requests must include passing tests with 100% code coverage and no linting errors.


$ npm test

© Shannon Moeller (

Licensed under MIT