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.

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!

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