{"id":12366,"library":"vinyl-contents","title":"vinyl-contents","description":"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.","status":"active","version":"2.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/gulpjs/vinyl-contents","tags":["javascript"],"install":[{"cmd":"npm install vinyl-contents","lang":"bash","label":"npm"},{"cmd":"yarn add vinyl-contents","lang":"bash","label":"yarn"},{"cmd":"pnpm add vinyl-contents","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for the file object structure it operates on.","package":"vinyl","optional":false},{"reason":"Internal dependency for buffering stream contents. Upgrade to 'bl' was a breaking change in v2.","package":"bl","optional":false}],"imports":[{"note":"The package exports a single function as its default export. Use a default import for ESM.","wrong":"import { vinylContents } from 'vinyl-contents';","symbol":"vinylContents","correct":"import vinylContents from 'vinyl-contents';"},{"note":"CommonJS require is supported and demonstrated in the official usage examples.","symbol":"vinylContents","correct":"const vinylContents = require('vinyl-contents');"},{"note":"TypeScript types can be imported for the callback signature.","symbol":"type VinylContentsCallback","correct":"import vinylContents, { type VinylContentsCallback } from 'vinyl-contents';"}],"quickstart":{"code":"const { Transform } = require('streamx');\nconst pug = require('pug');\nconst vinylContents = require('vinyl-contents');\nconst Vinyl = require('vinyl');\nconst stream = require('stream');\n\n// A naive Gulp-like plugin to demonstrate vinyl-contents usage\nfunction gulpPug(options) {\n  return new Transform({\n    transform: function (file, cb) {\n      // Pass through null files or non-Vinyl objects\n      if (!Vinyl.isVinyl(file) || file.isNull()) {\n        return cb(null, file);\n      }\n\n      vinylContents(file, function (err, contents) {\n        if (err) {\n          return cb(err);\n        }\n\n        if (contents === undefined) {\n          // File was empty after processing\n          return cb(null, file);\n        }\n\n        try {\n          // Compile the contents (which is now a Buffer) to a string\n          const compiledHtml = pug.compile(contents.toString(), options)();\n          file.contents = Buffer.from(compiledHtml);\n          cb(null, file);\n        } catch (compileErr) {\n          cb(compileErr);\n        }\n      });\n    },\n  });\n}\n\n// Example usage:\nconst pugPlugin = gulpPug();\n\n// Create a dummy vinyl file with streaming content\nconst sourceStream = new stream.Readable({\n  read() {\n    this.push('h1 Hello from Stream, #{name}');\n    this.push(null);\n  }\n});\nconst fileWithStream = new Vinyl({\n  path: 'template-stream.pug',\n  contents: sourceStream, // This will be buffered by vinyl-contents\n  data: { name: 'World' }\n});\n\n// Create a dummy vinyl file with buffer content\nconst fileWithBuffer = new Vinyl({\n    path: 'template-buffer.pug',\n    contents: Buffer.from('p Hello from Buffer, #{name}'),\n    data: { name: 'Universe' }\n});\n\n// Create a dummy vinyl file with null content\nconst fileWithNull = new Vinyl({\n    path: 'template-null.pug',\n    contents: null\n});\n\nconsole.log('--- Processing files ---');\npugPlugin.on('data', (file) => {\n  console.log(`\\nProcessed file: ${file.path}`);\n  console.log(`Contents type: ${file.contents ? 'Buffer' : 'null/undefined'}`);\n  console.log(`Output: ${file.contents ? file.contents.toString() : 'N/A'}`);\n});\n\npugPlugin.on('error', (err) => {\n  console.error('Plugin error:', err);\n});\n\npugPlugin.write(fileWithStream);\npugPlugin.write(fileWithBuffer);\npugPlugin.write(fileWithNull);\npugPlugin.end();","lang":"javascript","description":"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."},"warnings":[{"fix":"Upgrade your Node.js environment to version 10.13.0 or newer. Alternatively, if unable to upgrade Node.js, remain on `vinyl-contents` v1.x.","message":"Version 2.0.0 drops support for Node.js versions older than 10.13.0. Running on unsupported versions will likely lead to errors.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Review existing code for any implicit dependencies on `readable-stream`'s specifics when interacting with `vinyl-contents`. Ensure that only the `contents` provided to the callback are used, and do not make assumptions about the original `file.contents` stream after `vinyl-contents` has begun processing it.","message":"The internal streaming implementation was changed from `readable-stream` to `bl` (BufferList) in v2.0.0. While this is an internal change, it could potentially affect users who relied on specific behaviors or stream types from the previous implementation, or lead to unexpected interactions with highly customized stream pipelines.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Avoid using `vinyl-contents` for files known to be excessively large. Instead, if possible, design your pipeline to work directly with streaming `file.contents` using `file.pipe()` or other stream processing techniques, rather than buffering the entire file into memory.","message":"When `vinyl-contents` processes a Vinyl file with streaming contents, it buffers the entire stream into memory before returning it as a Buffer. This can lead to significant memory consumption and performance issues if processing very large files, potentially causing your application to crash or become unresponsive.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure that the first argument passed to `vinylContents` is always an instance of `Vinyl` from the `vinyl` package.","cause":"The `vinylContents` function was called with an argument that is not a valid `Vinyl` file instance (e.g., `null`, `undefined`, or a plain object).","error":"TypeError: The first argument must be a Vinyl file."},{"fix":"Use the ES Module import syntax: `import vinylContents from 'vinyl-contents';`","cause":"You are attempting to use CommonJS `require()` syntax within a JavaScript file that is being treated as an ES Module (e.g., `\"type\": \"module\"` in `package.json` or `.mjs` extension).","error":"ERR_REQUIRE_ESM or 'require() of ES Module ...' when attempting to use 'require('vinyl-contents')' in an ES Module context."},{"fix":"Refactor your pipeline to avoid buffering very large files into memory. If `vinyl-contents` must be used, increase Node.js's memory limit (e.g., `node --max-old-space-size=4096 script.js`) or process files in smaller chunks (if the downstream consumer supports it) or switch to a stream-based approach for large files.","cause":"Processing extremely large streaming Vinyl files with `vinyl-contents` causes the entire file to be buffered into memory, exceeding available heap space.","error":"Maximum call stack size exceeded / JavaScript heap out of memory"}],"ecosystem":"npm"}