Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/morris/vinyl-ftp

Blazing fast vinyl adapter for FTP
https://github.com/morris/vinyl-ftp

deployment ftp gulp vinyl

Last synced: 5 days ago
JSON representation

Blazing fast vinyl adapter for FTP

Awesome Lists containing this project

README

        

# vinyl-ftp

[![version](https://img.shields.io/npm/v/vinyl-ftp.svg)](https://www.npmjs.com/package/vinyl-ftp)
[![downloads](https://img.shields.io/npm/dm/vinyl-ftp.svg)](https://www.npmjs.com/package/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:

```javascript
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:

```javascript
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](https://www.npmjs.com/package/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:

```javascript
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 `/` and removes them if not.

## Development

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