Propeller is a simple and lightweight Gulp plugin that allows you to compile and deploy your projects using easy-to-read configuration files. Compilers are used to build your project, while deployers are used to push files to both local and remote environments.
Install Propeller using npm:
npm install gulp-propeller --save-devCreate a propeller.json file in your project directory:
{
"tasks": [
"sass: scss/**/*.scss > build/css",
"webpack: es6/entry.js > build/js/bundle.js"
],
"environments": {
"local": {
"type": "file",
"src": "build/**",
"dest": "public/assets"
}
}
}Use Propeller in any Gulp task:
const gulp = require('gulp');
const propeller = require('gulp-propeller');
gulp.task('default', function(){
// run propeller tasks, then deploy to 'local' environment
propeller.run().deploy('local');
});Compilers are used to build your project in preparation for deployment. Configure compilers by adding tasks to your propeller.json file:
{
"tasks": [
"sass: scss/app.scss > public/css",
"webpack: es6/entry.js > public/js/bundle.js"
]
}Run all tasks in sequential order using propeller.run:
propeller.run();Some compilers may yield a different output when in production mode. For example, a production build may include minified files for optimized performance. Run gulp tasks with the --production flag to enable production mode in all Propeller compilers.
Propeller includes several core compilers that are available by default.
Concatenate files into a single file at the target location. Use a comma-separated array syntax to specify all source files in order.
{
"tasks": [
"concat: [ js/one.js, js/two.js ] > public/js/all.js"
]
}Copy files from one location to another.
{
"tasks": [
"copy: source/icons.otf > public/fonts"
]
}Compile Sass stylesheets to CSS.
{
"tasks": [
"sass: scss/app.scss > public/css"
]
}By default, compiled CSS stylesheets include Sass sourcemaps and expanded CSS style declarations. In production mode, the Sass compiler uses gulp-autoprefix to automatically add vendor prefixes to your CSS styles. In addition, the CSS output is compressed and minified for optimal performance.
Compile ES6 files into client-ready ES5 using the Babel preset for webpack.
{
"tasks": [
"webpack: es6/entry.js > public/js/bundle.js"
]
}Babili is used in production mode to minify the compiled scripts for better performance.
Deployers are used to move project files to a target environment. Configure deployers by adding environments to your propeller.json file:
{
"environments": {
"local": {
"type": "file",
"src": "build/**",
"dest": "public/html",
"gitignore": false
}
}
}Deploy to a target environment using propeller.deploy:
propeller.deploy('local');Chain deployments to compiler tasks to create a sequential build/deploy sequence:
propeller.run().deploy('local').deploy('staging');Propeller includes several core deployers that are available by default.
Deploy assets using the file system.
{
"environments": {
"web1": {
"type": "file",
"src": "public/**",
"dest": "/volumes/web1/public_html",
"gitignore": false
}
}
}Deploy assets using the file transfer protocol (FTP). This deployer requires a connection object to be included in the environment definition within propeller.json (see below for examples).
The FTP deployer utilizes vinyl-ftp to handle file transfers. See https://www.npmjs.com/package/vinyl-ftp#ftpcreate-config- for additional connection configuration options.
{
"environments": {
"staging": {
"type": "ftp",
"src": "public/**",
"dest": "public_html/staging",
"gitignore": false,
"connection": {
"host": "staging.somedomain.com",
"user": "kyle",
"pass": "mypassword",
"secure": true,
"port": 21
}
}
}
}Deploy assets using the secure file transfer protocol (SFTP). This deployer requires a connection object to be included in the environment definition within propeller.json (see below for examples).
The SFTP deployer utilizes gulp-sftp to handle file transfers. See https://www.npmjs.com/package/gulp-sftp#api for additional connection configuration options.
{
"environments": {
"production": {
"type": "sftp",
"src": "public/**",
"dest": "public_html/www",
"gitignore": false,
"connection": {
"host": "somedomain.com",
"user": "kyle",
"pass": "mypassword",
"port": 22
}
}
}
}Propeller is built to be highly extensible. Create custom compilers and deployers to add new capabilities to your Propeller projects.
Extend propeller.Compiler and pass an instance of your extended class to propeller.extend to register a custom compiler.
const gulp = require('gulp');
const propeller = require('gulp-propeller');
class Coffee extends propeller.Compiler {
/**
* Compile source to destination:
* Override this method to write your own compiler.
* Return a Gulp stream to properly close this method.
*
* @param {string} src
* @param {string} dest
* @return {Object} stream
*/
compile(src, dest){
// do stuff
}
}
// extend propeller
propeller.extend(new Coffee());Custom compilers should include a compile method that returns a Gulp stream object upon closure.
Utilize custom compilers by adding them to your task list. Always use the lower-case class name of your custom compiler when creating tasks. For example, the custom Coffee compiler becomes coffee in our propeller.json task list:
{
"tasks": [
"coffee: source/file.coffee > destination"
]
}Extend propeller.Deployer and pass an instance of your extended class to propeller.extend to register a custom deployer.
const gulp = require('gulp');
const propeller = require('gulp-propeller');
class WebDav extends propeller.Deployer {
/**
* Deploy source to destination:
* Override this method to write your own deployer.
* The connection parameter is optional.
* Return a Gulp stream to properly close this method.
*
* @param {string} src
* @param {string} dest
* @param {Object} connection
* @param {boolean} gitignore
* @return {Object} stream
*/
deploy(src, dest, connection, gitignore){
// do stuff
}
}
// extend propeller
propeller.extend(new WebDav());Custom deployers should include a deploy method that returns a Gulp stream object upon closure. Optionally employ the connection parameter in the deploy method to pass custom JSON configuration data to your deployer.
Utilize custom deployers by referring to them in your environments list. Always use the lower-case class name of your deployer in configuration files. For example, the custom WebDav deployer becomes webdav in our propeller.json environments list:
{
"environments": {
"staging1": {
"type": "webdav",
"src": "public/**",
"dest": "public_html/staging1",
"gitignore": false,
"connection": {
"key1": "value1",
"key2": "value2"
}
}
}
}