WOK

Tasty website cookware

WOK is a loosely opinionated boilerplate for web development built with flexibility and productivity in mind.

Features

HTML5 Boilerplate
Static HTML templating with Nunjucks
Sass 3.5+ with node-sass and CSS post-processing
BEM-like naming convention
Em based media-queries via sass-mq
ES2015+ support with Babel (supports babel-env for IE10+, evergreen browsers and stage2. Polyfill loaded from CDN.js)
Gulp.js build and deploy workflow
Development server and asset live-reload with BrowserSync and Weinre remote debugging
Incremental deploy with rsync or lftp
Remote backup / rollback (UNIX SSH environments only)

Supported browsers (via browserslist)

last 1 major version
>= 1%
Chrome >= 45
Firefox >= 38
Edge >= 12
Explorer >= 10
iOS >= 9
Safari >= 9
Android >= 4.4
Opera >= 30

Requirements

Node.js >= 6.9.0 (we strongly suggest to use something like nvm)
gulp cli (npm install -g gulp)

Installation

Clone this repo:

git clone git://github.com/fevrcoding/wok.git

From project root:

npm install (gulp deps)

Linting

JavaScript linting

Wok comes with pre-configured eslint linting based on the airbnb base preset. You can lint your JavaScript files by running: gulp lint:js.

If you want to use in editor linting, please follow the setup instructions your editor

SCSS linting

Linting via stylelint is available as a gulp task: gulp lint:styles. Available editor extensions for in-editor linting are listed here

Configuration

On a plain HTML project, the default configuration should work just fine. On other setups you might need to tweak some paths/options:

customize paths and options in hosts.js, paths.js and properties.js files within the build/gulp-config folder
if needed, edit/add/remove tasks by editing tasks' configuration in build/gulp-tasks/.

Note: you may override hosts.js, paths.js and properties.js files just for your local codebase by creating a .local.js file. Those local files won't be committed in git

Project Structure

Project sources are located into application folder. Don't edit files in public since they will be overwritten during the build process.

Application Folder Structure

assets
    + fonts #Web Fonts
    + images #Images
    + javascripts #JavaScript files
    + stylesheets #SASS files
    + audio #audio files
    + video #video files
    + vendors #vendors packages not installed via npm
documents #Markdown files or any other txt-like file to be included in HTMLs
fixtures #JSON files
views #HTML files
    +   partials #View partials
    +   templates #Nunjucks templates
    index.nunj.html #Main views
...

JavaScript Development

Wok supports cross browser ES2015 by parsing individual source files with Babel. To support old browsers polyfills are loaded via CDN.

To use ES2015 modules follow the webpack2 recipe.

View Templates

With Nunjucks you can setup extensible page templates. See official docs for further details.

View Partials and Sub-folders

View partials in application/views/partials are rendered to public folder like every other file. To prevent rendering prepend a _ to the filename.

To limit performance issues, just first level sub-folders will be included in the parse process.

Building

From project root:

gulp serve (builds in development mode, runs a static server on port 8000, watches for change and live-reloads assets)

Production build

To generate a production ready build add the --production parameter:

gulp --production

Deploy and rollback:

SSH and rsync

By default WOK implements a simple set of deploy tasks requiring SSH remote access and rsync.

To deploy and rollback with rsync first setup your remote hosts in build/gulp-config/hosts.js, then run:

#deploy to remote staging server. A backup of the deploy target folder (`paths.dist.root`) will be stored in `paths.backup`.
gulp deploy --target=staging

#deploy a production build to remote production server
gulp deploy --production --target=production

#rollback to the previous version in the remote production server
gulp remote --command=rollback --target=production

FTP

If you are on a shared hosting with FTP access, you can switch to the more basic ftp task, which uses lftp mirroring feature for incremental upload.

To switch to ftp mode, set deployStrategy in build/gulp-config/properties.js to 'ftp', then config hosts and run deploy commands as explained above.

Note Rollback and backup tasks won't be available with this configuration.

Customize host related deploy options

Instead of globally setting the deploy strategy, you can setup a deploy strategy for each host in your hosts[.local].js file by setting a deployStrategy key. Custom host configuration will take precedence over global configuration.

Configuration options may vary based on the deploy strategy. Common options are:

host: Remote host IP address,
username: remote username,
password: remote password,
path: path to which files will be saved.
port: port the deploy service is listening to
deployStrategy: the deploy strategy to use

Note: path configuration differs from strategy to strategy. For ftp use a relative path (ie: 'public') without trailing slashes. For rsync/SSH it might be safer to use an absolute path (ie: /var/wwwroot/my-site/public).

Usage with external tools

When paired with Phing or other deployment systems, remember to set buildOnly to true in build/gulp-config/properties.js to delegate deploy tasks.

Other Gulp tasks

dev: one time development build (also runs as default task)
server: runs a local static server in public folder. Use flag --production to enable gzip compression
lint: runs both JavaScript and style linters
bump: bumps semver version of package.json file.

Project Info

WOK was created by Marco Solazzi with contributions from Matteo Guidotto and Umberto Quintarelli.

kino90/wok

WOK