or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-vinyl-source-stream

Use conventional text streams at the start of your gulp or vinyl pipelines

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/vinyl-source-stream@1.1.x

To install, run

npx @tessl/cli install tessl/npm-vinyl-source-stream@1.1.0

index.mddocs/

Vinyl Source Stream

Vinyl Source Stream is a utility that enables the use of conventional text streams at the start of gulp or vinyl pipelines. It creates a bridge between standard Node.js streams and vinyl file objects, making it easier to integrate existing stream-based tools with gulp workflows without needing specialized wrapper plugins.

Package Information

  • Package Name: vinyl-source-stream
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install vinyl-source-stream

Core Imports

const source = require('vinyl-source-stream');

ES Modules:

import source from 'vinyl-source-stream';

Basic Usage

const source = require('vinyl-source-stream');
const gulp = require('gulp');
const fs = require('fs');

// Basic usage with a readable stream
fs.createReadStream('input.txt')
  .pipe(source('output.txt'))
  .pipe(gulp.dest('./dist'));

// Common usage with browserify
const browserify = require('browserify');

const bundleStream = browserify('./index.js').bundle();
bundleStream
  .pipe(source('bundle.js'))
  .pipe(gulp.dest('./dist'));

Capabilities

Stream to Vinyl Conversion

Converts conventional text streams into vinyl file objects for use in gulp pipelines.

/**
 * Creates a through stream that converts text input to vinyl file instances
 * @param filename - Optional filename for the output vinyl file
 * @param baseDir - Optional base directory for path resolution
 * @returns Transform stream that emits vinyl file objects
 */
function vinylSourceStream(filename, baseDir)

Parameters:

  • filename (string, optional): A "pretend" filename to use for the vinyl file. This affects how downstream processes handle the file (e.g., for determining output filename, content type detection). If not provided, the vinyl file will have no path property.

  • baseDir (string, optional): Base directory for resolving the file path. When combined with filename, creates the full file path using path.resolve(baseDir || process.cwd(), filename). Also sets the vinyl file's base property when provided. If not provided but filename is given, path resolution defaults to process.cwd() but no base property is set.

Returns:

Transform stream (through2 in object mode) that:

  • Accepts text/buffer chunks as input
  • Emits a single vinyl file object containing the input stream as its contents
  • The vinyl file's contents property is a readable stream containing all input data

Stream Behavior:

  1. The first chunk of input triggers emission of the vinyl file object
  2. All input chunks are forwarded to the vinyl file's internal contents stream
  3. When input ends, both the internal stream and output stream are properly closed
  4. The stream operates in object mode to handle vinyl file objects

Usage Examples:

const source = require('vinyl-source-stream');
const fs = require('fs');
const gulp = require('gulp');

// Basic file conversion
fs.createReadStream('data.txt')
  .pipe(source('processed-data.txt'))
  .pipe(gulp.dest('./output'));

// With custom base directory
someReadableStream
  .pipe(source('result.json', './build'))
  .pipe(gulp.dest('./'));

// Filename only (base defaults to process.cwd())
dataStream
  .pipe(source('output.csv'))
  .pipe(someGulpPlugin())
  .pipe(gulp.dest('./dist'));

// Without filename (downstream plugins determine naming)
apiResponseStream
  .pipe(source())
  .pipe(someTransformPlugin())
  .pipe(gulp.dest('./cache'));

Types

Since this is a JavaScript package, the following TypeScript-style definitions describe the expected types:

interface VinylFile {
  contents: NodeJS.ReadableStream;
  path?: string;
  base?: string;
}

interface TransformStream extends NodeJS.ReadWriteStream {
  // Standard Node.js Transform stream interface
  // Accepts text/buffer chunks via write()
  // Emits vinyl file objects via 'data' events
}

Integration Patterns

With Browserify

const browserify = require('browserify');
const source = require('vinyl-source-stream');
const gulp = require('gulp');

gulp.task('bundle', function() {
  return browserify('./src/app.js')
    .bundle()
    .pipe(source('app.bundle.js'))
    .pipe(gulp.dest('./dist/js'));
});

With Other Stream-Based Tools

const someStreamingTool = require('some-streaming-tool');
const source = require('vinyl-source-stream');

someStreamingTool.createStream()
  .pipe(source('tool-output.txt'))
  .pipe(gulp.dest('./output'));

Error Handling

The stream follows standard Node.js stream error handling patterns. Errors from the input stream will be forwarded to the output stream:

inputStream
  .pipe(source('output.txt'))
  .on('error', function(err) {
    console.error('Stream error:', err);
  })
  .pipe(gulp.dest('./dist'));