vinyl-contents

2.0.0 · active · verified Sun Apr 19

vinyl-contents is a specialized utility designed to asynchronously read and normalize the content of a Vinyl file object, a fundamental data structure within the Gulp.js build system. It adeptly handles Vinyl files where the `contents` property can be a Buffer, a Node.js Stream, or `null`. For Buffer contents, it returns them directly. For Stream contents, it buffers the entire stream into a `BufferList` and returns it as a single Buffer, while empty contents (e.g., `file.isNull()`) result in `undefined`. The current stable version is `2.0.0`. As part of the Gulp.js organization, its release cadence prioritizes stability and ecosystem compatibility over rapid feature iteration. A key differentiator is its focused handling of `Vinyl` file types, simplifying content access for downstream processes that expect string or buffer input, though it includes a crucial warning against processing very large streaming files due to its in-memory buffering approach.

Common errors

Warnings

Install

Imports

Quickstart

This example demonstrates how to use `vinyl-contents` within a simplified Gulp-like plugin to process Vinyl files with various content types (stream, buffer, null), converting them to a Buffer after processing.

const { Transform } = require('streamx');
const pug = require('pug');
const vinylContents = require('vinyl-contents');
const Vinyl = require('vinyl');
const stream = require('stream');

// A naive Gulp-like plugin to demonstrate vinyl-contents usage
function gulpPug(options) {
  return new Transform({
    transform: function (file, cb) {
      // Pass through null files or non-Vinyl objects
      if (!Vinyl.isVinyl(file) || file.isNull()) {
        return cb(null, file);
      }

      vinylContents(file, function (err, contents) {
        if (err) {
          return cb(err);
        }

        if (contents === undefined) {
          // File was empty after processing
          return cb(null, file);
        }

        try {
          // Compile the contents (which is now a Buffer) to a string
          const compiledHtml = pug.compile(contents.toString(), options)();
          file.contents = Buffer.from(compiledHtml);
          cb(null, file);
        } catch (compileErr) {
          cb(compileErr);
        }
      });
    },
  });
}

// Example usage:
const pugPlugin = gulpPug();

// Create a dummy vinyl file with streaming content
const sourceStream = new stream.Readable({
  read() {
    this.push('h1 Hello from Stream, #{name}');
    this.push(null);
  }
});
const fileWithStream = new Vinyl({
  path: 'template-stream.pug',
  contents: sourceStream, // This will be buffered by vinyl-contents
  data: { name: 'World' }
});

// Create a dummy vinyl file with buffer content
const fileWithBuffer = new Vinyl({
    path: 'template-buffer.pug',
    contents: Buffer.from('p Hello from Buffer, #{name}'),
    data: { name: 'Universe' }
});

// Create a dummy vinyl file with null content
const fileWithNull = new Vinyl({
    path: 'template-null.pug',
    contents: null
});

console.log('--- Processing files ---');
pugPlugin.on('data', (file) => {
  console.log(`\nProcessed file: ${file.path}`);
  console.log(`Contents type: ${file.contents ? 'Buffer' : 'null/undefined'}`);
  console.log(`Output: ${file.contents ? file.contents.toString() : 'N/A'}`);
});

pugPlugin.on('error', (err) => {
  console.error('Plugin error:', err);
});

pugPlugin.write(fileWithStream);
pugPlugin.write(fileWithBuffer);
pugPlugin.write(fileWithNull);
pugPlugin.end();

view raw JSON →