This project is deprecated (and broken! (you've been warned!)) until new version is scripted. Also if anyone is interested in taking this project over let me know. Thanks.
Allows the management of a website or web application via bundle configuration files from the command line (uses gulp in the background) and makes feature based development easier.
So the idea is as follows:
We have a bundles
directory (could be named anything via the gulpw-config.*
file).
That directory should contain "bundle-configuration" files which are used by "task adapters" to run a
task via the command line; E.g., $ gulpw build:global deploy:global deploy:other-bundle
.
The bundle files will then hold the user's configurations in the *.yaml, *.json, or *.js format.
- Install gulpw globally
npm install gulpw -g
then - Install gulpw locally
npm install gulpw
.
- Create your project's bundle configs folder; E.g., './gulpw-bundle-configs' etc.
- Create empty
gulpw-config.*
config file or rungulpw config
in your projects root to generate one. - Tell your
gulpw-config.*
file where your bundle configs folder is (setbundlesPath
to your bundles config path inside config file). - Configure your global tasks within your
gulpw-config.*
file. - (Optional) Execute
gulpw deploy-config
to configure servers to deploy your work to. - Reap the benefits of using gulpw.
A bundle config:
- is made of either a *.yaml, *.json, or *.js file with one or more properties listed in it.
- can have many config sections used by tasks.
- can be created by calling
gulpw bundle-config
. Note this task will not overwrite existing bundles but will let you know when they already exists and will prompt you to enter a new name/alias.
# some-other-bundle.yaml
alias: some-other-bundle
# some-bunde.yaml
alias: some-bundle
files:
js:
- some/file/path.js
- some/other/file/path.js
css:
- some/other/file/path1.css
- some/other/file/path2.css
requirejs:
options:
# requirejs options here ...
...
See the listed tasks below for ideas on what other sections you can use in your bundle files.
Also when running gulpw config
you will be asked about the tasks you want to include which will
then be included in your bundle file consequently depending on your answers.
gulpw {task-name}:{bundle-name} [flags]
to run task for one bundle.gulpw {task-name} [flags]
to run tasks for all bundles.
where {task-alias}
is the task you want to run ('build', 'minify' etc.)
and {bundle-alias}
is the bundle you want to run the task for (for './bundle-configs/hello-world.yaml'
the bundle alias would be hello-world
.
[flags]
are any flags you would like to pass in with the task that you're calling; E.g.,
gulpw deploy:global --file-types js
Also, e.g., gulpw build:global build:some-other-bundle deploy:global deploy:some-other-bundle --dev
The above example builds (see build task for more info) some bundles (in development mode
(unminified due to --dev
flag)) and deploys them to
the users selected server (see deploy task section for more info).
- browserify
- build
- bundle
- clean
- compass
- config
- copy
- copytoclipboard
- csslint
- deploy
- deploy-config
- eslint
- findandreplace
- help
- jasmine
- jshint
- minify
- mocha
- requirejs
- vulcan
- watch
The 'build' task calls every sub task listed in a {bundle-name}.yaml config file except (by default can be altered in local wrangler config file): - clean (we could have this run via a flag in the future but is ignored for now to speed up performance) - deploy - jshint (called by the minify task so is ignored as standalone task) - csslint (called by the minify task so is ignored as a standalone task)
Note: The minify task runs 'jshint' and 'csslint' (along with other tasks) so that is why they are being ignored as standalone tests.
'build' also adds the 'minify' task to it's list of tasks 'to' run for a particular bundle or bundles
depending on if an html
, css
or js
section is found with the files
section.
- ignoredTasks {Array}: List of standalone tasks to ignore when calling build (*note some tasks are included as conglomerate tasks).
--skip-linting
, --skip-csslint
, --skip-jshint
, --dev
,
--skip-testing
, --skip-mocha-test
, --skip-jasmine-tests
tasks:
# Build Task (Looks through {bundle-alias}.yaml file and runs
# all tasks that are not in the `ignoreTasks`
build:
ignoredTasks:
- clean
- deploy
- jshint
- csslint
None.
Creates a bundle config file in the designated 'bundlesPath' property described in your gulpw-config.* file.
static-tasks:
bundle:
allowedTasks:
- browserify
- compass
- copy
- csslint
- deploy
- jasmine
- jshint
- mocha
- requirejs
- watch
- allowedTasks: List of tasks that the user is allowed to choose from when generating a new bundle config.
None.
- bundle: Sets the default bundle name to use for the new bundle config file for the current bundle generation session. Default 'bundle'. Optional (will ask the user for the name of the bundle to generate but will have the passed in --bundle value as the default).
The 'clean' task cleans out any artifact files outputted by a bundle; E.g., if a bundle has a files
key or
requirejs
key then the artifacts outputted by these sections are cleaned up (deleted) when clean is called.
'clean' also cleans/deletes any files listed in a clean
section; E.g.,
clean:
- some/file/path.js
- some/file/path.css
- etc.
*The files
section can have many different sections that output artifact files for
example a js
, css
, or html
section(s).
*See the 'minify' section for more info on the possible sections supported by the files
section.
- allowedFileTypes: {Array}: A list of file types to allow for cleaning.
tasks:
clean:
allowedFileTypes:
- js
- css
- html
clean:
- some/file/path.js
- some/file/path.css
- etc.
The 'compass' task calls 'compass compile' at compass project root location (config.rb home).
tasks:
compass:
# Compass project root dir
configrb: null # config.rb home
compass:
# Compass project root dir
configrb: null # config.rb home
None.
None.
The config task backs up an existing gulpw-config.* (file could be empty) and creates a new gulpw-config file in the chosen format. The task also allows you to choose which sections (with defaults) to include in the file.
None.
None.
None.
None.
The 'copy' task copies any files listed in a copy
section's files
hash within in a {bundle-name}.* config file.
E.g.,
copy:
files:
./fe-dev/bower_components/requirejs/require.js: ./public/js/vendors/require.js
'copy' copies the 'key' to the 'value' location for every entry in the files
hash.
None.
None.
copy:
files:
./this/path/gets/copied/to: ./this/path
None.
Copies files to clipboard.
tasks:
copytoclipboard:
alternateAlias: clipboard
constructorLocation: ./src/bundle-tasks-adapters/CopyToClipboardTaskAdapter.js
priority: -100
copytoclipboard:
# The following two attributes are optional but at least one must declared inorder to use this task:
#file: {String} - Optional.
#files: {String|Array} - Optional.
None.
The 'csslint' task runs csslint on a bundle or all bundles using the listed '.csslintrc' file or runs with
default options if no '.csslintrc' file is listed (default options are listed in gulpw-config.*
file
and also wrangler.config.yaml
also has a default definition set up for it).
tasks:
csslint:
csslintrc: null
- csslintrc: Location of '.csslintrc' file.
None.
None.
The deploy
task deploys files using the deploy section in a user's local 'gulpw-config.*' and also uses a user level deploy configuration generated by
the 'deploy-config' task. See notes in config section below.
tasks:
# Deploy Task
deploy:
# Use unix style paths for deployment
deployUsingUnixStylePaths: true
# Options written by `deploy-config` to `.gulpw/deploy.yaml`
developingDomain: null
hostnamePrefix: null
hostname: null
port: 22
username: null
password: null
publickeyPassphrase: null
privatekeyLocation: null
# File types that are allowed for deployment
allowedFileTypes: # This will change to `ingoredFileTypes`
- js
- css
- html
- json
- yaml
- jpg
- png
- gif
- md
- mkd
# Domains to develop
domainsToDevelop:
# Hostname to develop for
somedomain.com:
# Servers where user can deploy to `domainToDevelopFor`
# (in this case `domainToDevelopFor` is `somedomain.com`)
hostnames: # slots/hosts
- -devslot1.somedomain.com
- -devslot2.somedomain.com
- -devslot3.somedomain.com
# All website instance prefixes represent the same website just different
# instances of the website.
# An array of hostname prefixes (if any)
hostnamePrefixes:
- web1
- web2
- web3
# If set a `hostnamePrefixFolder` value becomes available
# to any templates within this `domainToDevelopConfig[x]` config.
hostnamePrefixFolders: null
#web1: website1
#web2: website2
#web3: website3
# Root folder on the server to use for deployments (prefix
# path for file paths being deployed that don't have
# `deployRootFoldersByFileType` defined for their typ)))
# example: /home/some-user/sites/<%= hostnamePrefix %><%= hostname %>
# (recieves the `deploy` has from this config)
deployRootFolder: null
# Deploy roots by file type. If defined, file types that are keys in
# it's hash will have the deploy root for said key
# prepend as a deploy root to the file being deployed instead of the
# `deployRootFolder` root path.
deployRootFoldersByFileType:
md: /home/some-user/docroot/md-files.<%= hostnamePrefix %><%= hostname %>/
# A map used to replace parts or all of paths found that match the pattern on the left with the value on the right
# Used for complex setups where the paths in your development environment don't have a one-to-one counterpart on the
# Server; E.g., One of my setups has ./jsp/some/file.jsp locally but on the server it is ./some-other-folder/some/file.jsp
# So this isn't something that can be acheived with a root folder prefix because the local path ./jsp/... is in the root development directory
# and when deploying we deploy ./jsp/... => /{some-deploy-root}/jsp/...
localPathsToServerPathsRegexMap:
'^(?:\.\/)?jsp\/': 'some-necessarily-differently-named-dir-on-the-server/'
Launches an interactive questionnaire for generating a local 'deploy.yaml' file with deployment details
for current development environment.
Note This task must be run before the deploy
task in order for it to function.
Note File is put in the directory specified by localConfigPath
of the
'gulpw-config.*' file or the default is used ('./.gulpw').
None.
The eslint
task expects gulp-eslint
options (link to gulp-eslint: https://github.com/adametry/gulp-eslint)
along with a couple of custom optional attributes:
tasks:
eslint:
options:
useEslintrc: true // Whether to use .eslintrc file
failAfterError: false
failOnError: false
eslintrc: ./.eslintrc // deprecated. Use options hash map instead
- options:
gulp-eslint
options (https://github.com/adametry/gulp-eslint)- useEslintrc: {Boolean} - Whether to use .eslintrc files found in the directories checked. Default 'true'.
- failAfterError: {Boolean} - Whether to fail the task after an error or not. Default 'false'.
- failOnError: {Boolean} - Whether to fail the task on an error or not. Default 'false'.
None.
- skip-lint{ing}
- skip-jshint{ing}
- skip-jslint{int}
Finds and replaces strings in files.
tasks:
findandreplace:
constructorLocation: ./src/bundle-tasks-adapters/FindAndReplaceAdapter.js
priority: -98
# 'gulp-replace' module options
# @see for available options: https://www.npmjs.com/package/gulp-replace
#options:
findandreplace:
# Files to find and replace on.
#files: {Array}
# Key value hash of things to search for (regex|string) and values (string) to replace them with.
# ** Note ** This feature is not supported yet.
#findandreplace: {Object}
gulpw help
gulpw help --section {section-name-here}
- E.g.,
gulpw help --section build
Jasmine tests task runs the jasmine module on your test 'files' array or string using options
if any.
Jasmine options (see jasmine module for available options).
- Skip Testing:
--skip-tests
,--skip-testing
,--skip-jasmine-tests
,--skip-jasmine-testing
tasks:
jasmine:
files:
- some/tests/folder/with/tests/**/*.js
- some/tests/file.js
options: null # - {Object} - Jasmine options if any. Default `null`
jasmine:
files:
- some/tests/folder/with/tests/**/*.js
- some/tests/file.js
JsHint task. If jshintrc
is specified those options are used instead (maybe we'll merge these options
in the future?).
See jshint module for options.
--skip-jshint
, skip-jslint
, skip-linting
tasks:
jshint:
jshintrc: ./configs/.jshintrc
ignoreFiles: null
options:
predef:
- $
- _
- amplify
- Backbone
- browserify
- define
- jQuery
- Modernizr
- Mustache
- Marionette
- require
- sjl
jshint:
jshintrc: ./.jshintrc
options:
... # see jshint module for options
The 'minify' task is a big composite task due to the many subtasks it handles. The minify task launches the following tasks per file in it's sources array (task only launch for corresponding file types):
- gulp-csslint
- gulp-minify-css
- gulp-jshint
- gulp-uglify
- gulp-minify-html
The template
hash in the options for this task takes care of importing templates using a lodash template
into your javascript file (appended to the bottom of the javascript file)(read notes in config description).
--skip-linting
, --skip-csslint
, --skip-jshint
, --skip-jslint
, --dev
tasks:
minify:
# Header for top of file (lodash template)
header: |
/*! Company Name http://www.company-website.com <%= bundle.options.alias %>.js <%= bundle.options.version %> */
cssBuildPath: some/css/build/path
htmlBuildPath: some/html/build/path
jsBuildPath: some/js/build/path
allowedFileTypes: # allowed files types to process for the main tasks (css, js, and html)
- js
- css
- html
htmlTaskOptions:
spare: true
comments: false
jsTaskOptions: {}
useMinPreSuffix: false
useVersionNumInFileName: false
template:
templatePartial: null # lodash template
compressWhitespace: true
templateTypeKeys: # template keys to look for in `files` hash of a bundle
- mustache
- handlebars
- ejs
files:
js: # {Array} of file paths
...
css: # {Array} of file paths
...
html: # {Array} of file paths
...
mustache: # {Array} of file paths
...
handlbars: # {Array} of file paths
...
ejs: # {Array} of file paths
...
Mocha tests task runs the mocha module on your test 'files' array or string using options
if any.
- Skip Testing:
--skip-tests
,--skip-testing
,--skip-mocha-tests
,--skip-mocha-testing
Mocha options. See Mocha module for options.
tasks:
mocha:
# {String|Array} of files. Default `null`
files: # or ./some/tests/**/*.js
- some/tests/folder/with/tests/**/*.js
- some/tests/file.js
options: null # - {Object} - Options if any. Default `null`
mocha:
files:
- some/tests/folder/with/tests/**/*.js
- some/tests/file.js
RequireJs task.
#####In 'gulpw-config.yaml':
tasks:
requirejs: null # requirejs options here
#options:
...
requirejs:
options:
...
Vulcan + crisper task
#####In 'gulpw-config.yaml':
tasks:
# Runs vulcanize and crisper on a file and alternately the file hash as a prefix or suffix
# to the file's basename.
vulcan:
constructorLocation: ./src/bundle-tasks-adapters/VulcanTaskAdapter
priority: 92
# Files to vulcanize
# files: // Populated from bundle.{json,js,yaml} file
# Destination directory for resulting files
# destDir: // Populated from bundle ""
# Crisper options
# @see for available options see: https://www.npmjs.com/package/crisper
#crisperOptions:
#jsFileName: # populated from bundle. Optional. Default `bundle.alias`
#scriptInHead: false. Puts script in head with 'defer' attribute.
#onlySplit: false. If false, omits script include of outputted javascript file
# Vulcanize options (options for `gulp-vulcanize`)
# @see for available options: https://github.com/Polymer/vulcanize#using-vulcanize-programmatically
vulcanizeOptions:
inlineScripts: true
inlineCss: true
# Remove generated 'html>head+body' elements and just keep the body's contents
# @see for more options: https://www.npmjs.com/package/gulp-dom
#noDomWrapper: false # Best used from bundle config level
"Same as in 'gulp-config.yaml' file except `constructorLocation` and `priority` options."
--show-file-sizes
The 'watch' task watches any files listed in the requirejs
, files.*
, and watch.otherFiles
keys (this will be dynamic in upcoming version so that you can say what keys should be watched by
default.
- ignoredTasks {Array}: Tasks to ignore by default.
- tasks {Array}: Tasks to run sequentially when a watched file change is detected.
- Not implemented yet
otherFiles {Array}: Other files to watch globally. Defaultnull
.
- Not yet implement
--file-type
(--ext
,-t
) - A list of comma separated file types to watch explicitly (ignores all other file types).
tasks:
watch:
ignoredTasks:
- clean
- deploy
tasks:
- build
- deploy
otherFiles: null
watch:
# Boolean for also watching files in `deploy.otherFiles` hash
watchDeployOtherFilesToo: false
otherFiles:
- path/to/some/file.js
- path/to/some/file.file
- ...
Note All long forms of these flags use the --{flag-name}
format. Short forms use -{flag-one-letter-alias}
.
All flag default values are null
/false
.
- bundle: Reserved but not yet used.
- file-types: Used to pass a comma separated list of file extensions to the defined tasks.
- Affected tasks:
deploy
- Uses--file-types
string to only deploy files of the types you passed in via--file-types
or one of it's aliases.
- Aliases:
--filetypes
--filetype
--ext
-t
-x
- Affected tasks:
- force: Used to force the task runner to continue despite any errors.
- Aliases: -f
- debug: Used for developing gulpw and allows you to keep your more pertinent debug logging declarations.
- Aliases: None.
- dev: Used to ignore minification (at this time).
- Affected tasks:
minify
Minification is skipped when used with this flag.
- Affected tasks:
- verbose: Used to print verbose mode logs.
- Aliases:
-v
- Aliases:
- async: Runs all tasks asynchronously. Note This may cause race condition errors between certain tasks; E.g.,
gulpw build deploy
// If you have many bundles deploy may fire before all build sub-tasks are done cause a failure (deploy task will timeout while waiting for files to become available for deploy if they are being used).- Aliases:
-a
- Aliases:
- out: Used for sending a path to a task to use to output file(s). Used by 'csslint' task to output all reporting (optionally).
- Alias:
-o
- Alias:
- section: Used by static help task to show help for a given readme.md section.
- skip-artifacts: Causes artifacts to be skipped on deploy task.
- skip-css-linting: Causes any css linting/hinting to be skipped from the
minify
task. - skip-jasmine-testing: Causes Jasmine tests to be skipped.
- skip-js-linting: Causes js linting tasks to be skipped (jshint/eslint).
- skip-linting: Causes css and js linting/hinting to be skipped via 'minify' task.
- Aliases: --skip-jshint --skip-jslint --skip-linting
- skip-mocha-testing: Causes mocha tests to be skipped.
- skip-tests: Causes
mocha
andjasmine
tests to not run.- Aliases:
--no-tests
--skip-testing
- Aliases:
- skip-related-bundles: Used within build task (skips building of related bundles).
- show-file-sizes: Shows file sizes for 'vulcan' task.
Be able to pass in multiple flags from the command line (some with values some without values). Running multiple tasks and passing in multiple flags and flags with values are allowed (flags and values need to be passed in last for this to work (cli doesn't differentiate between task names and param/flag values)); E.g.,gulp task1 --flag1 flag-value --flag2 --flag3 task2 --flag4
will only runtask1
and will parse task2 as a value of --flag2 unless you explicitely pass a value to --flag3- Build files cannot be shared amongst bundles when wanting to use the 'watch' task cause they cause a
cyclic dependency when running global
watch tasks; I.e.,
gulpw watch
- Inorder to run tests you must have run
gulpw deploy-config
since the deploy task will expect local deploy options to be setup for the gulpw-sample-app.
- Initial Idea UML Diagram (http://www.gliffy.com/go/publish/6312461)
- gulp site (http://gulpjs.com/)
- gulp docs (https://github.com/gulpjs/gulp/blob/master/docs/getting-started.md)
- gulp plugins (http://gulpjs.com/plugins/)
- gulpw sample app (https://github.com/elycruz/gulpw-sample-app) (used by gulpw when running it's tests)