@gulpetl/vinyl-ftp

Blazing fast vinyl adapter for FTP. Supports parallel transfers, conditional transfers, buffered or streamed files, and more. Often performs better than your favorite desktop FTP client.

Forked from vinyl-ftp to add support for Node-RED as part of the gulpetl project.

Usage

Nice and gulpy deployment task:

var gulp = require( 'gulp' );
var gutil = require( 'gulp-util' );
var ftp = require( 'vinyl-ftp' );

gulp.task( 'deploy', function () {

	var conn = ftp.create( {
		host:     'mywebsite.tld',
		user:     'me',
		password: 'mypass',
		parallel: 10,
		log:      gutil.log
	} );

	var globs = [
		'src/**',
		'css/**',
		'js/**',
		'fonts/**',
		'index.html'
	];

	// using base = '.' will transfer everything to /public_html correctly
	// turn off buffering in gulp.src for best performance

	return gulp.src( globs, { base: '.', buffer: false } )
		.pipe( conn.newer( '/public_html' ) ) // only upload newer files
		.pipe( conn.dest( '/public_html' ) );

} );

Without Gulp:

var fs = require( 'vinyl-fs' );
var ftp = require( 'vinyl-ftp' );

var conn = new ftp( /* ... */ );

fs.src( [ './src/**' ], { buffer: false } )
	.pipe( conn.dest( '/dst' ) );

Remember not to push FTP credentials to public repos!

Node-RED

Node-RED is a low-code, visual programming environment for event-driven applications. vinyl-ftp is available there as part of the gulpetl project; to install it to Node-RED under Manage Palette search for vinyl-ftp.

API

var ftp = require( 'vinyl-ftp' )

ftp.create( config )

Return a new vinyl-ftp instance with the given config. Config options:

• host: FTP host, default is localhost
• user: FTP user, default is anonymous
• pass[word]: FTP password, default is anonymous@
• port: FTP port, default is 21
• log: Log function, default is null
• timeOffset: Offset server time by this number of minutes, default is 0
• parallel: Number of parallel transfers, default is 3
• maxConnections: Maximum number of connections, should be greater or equal to "parallel". Default is 5, or the parallel setting. Don't worry about setting this too high, vinyl-ftp recovers from "Too many connections" errors nicely.
• reload: Clear caches before (each) stream, default is false
• idleTimeout: Time to keep idle FTP connections (milliseconds), default is 100
• debug: A debug callback that gets extensive debug information, default is null
• secure: Set true for secured FTP connections
• secureOptions: Set { rejectUnauthorized: false } for self-signed or expired secure FTP connections

You can override parallel and reload per stream in their options.

---

var conn = ftp.create( config )

conn.src( globs[, options] ) STREAM

Returns a vinyl file stream that emits remote files matched by the given globs. The remote files have a file.ftp property containing remote information. Possible options:

• cwd: Set as file.cwd, default is /.
• base: Set as file.base, default is glob beginning. This is used to determine the file names when saving in .dest().
• since: Only emit files modified after this date.
• buffer: Should the file be buffered (complete download) before emitting? Default is true.
• read: Should the file be read? Default is true. False will emit null files.

Glob-related options are documented at minimatch.

---

conn.dest( remoteFolder[, options] ) STREAM

Returns a transform stream that transfers input files to a remote folder. All directories are created automatically. Passes input files through.

conn.mode( remoteFolder, mode[, options] ) STREAM

Returns a transform stream that sets remote file permissions for each file. mode must be a string between '0000' and '0777'.

conn.newer( remoteFolder[, options] ) STREAM

Returns a transform stream which filters the input for files which are newer than their remote counterpart.

conn.differentSize( remoteFolder[, options] ) STREAM

Returns a transform stream which filters the input for files which have a different file size than their remote counterpart.

conn.newerOrDifferentSize( remoteFolder[, options] ) STREAM

See above.

conn.filter( remoteFolder, filter[, options] ) STREAM

Returns a transform stream that filters the input using a callback. The callback should be of this form:

function ( localFile, remoteFile, callback ) {

	// localFile and remoteFile are vinyl files.
	// Check remoteFile.ftp for remote information.
	// Decide wether localFile should be emitted and call callback with boolean.
	// callback is a function( error, emit )

	callback( null, emit );

}

conn.delete( path, cb ) CALLBACK

Deletes a file.

conn.rmdir( path, cb ) CALLBACK

Removes a directory, recursively.

conn.clean( globs, local[, options] ) STREAM

Globs remote files, tests if they are locally available at <local>/<remote.relative> and removes them if not.

Development

• Run tests with CONFIG=test/config/yourserver.json npm test