html5 gulp boilerplate

getting started

First create a repo for your project on github, then clone the html5-gulp-boilerplate project, into 'project-name'

git clone https://github.com/Paul-Browne/html5-gulp-boilerplate.git project-name
        

Now you'll want to change the origin of remote (where you push to, and pull from) to the github url of the 'project-name' repo

git remote set-url origin https://github.com/user-name/project-name.git
        

change user-name and project-name to whatever your github user name is, and whatever you named your new project.
Run the command git remote -v to check that you entered the name correctly.

You'll probably want to change a few fields in the package.json, such as name, repository url, author etc.

Now all thats left for you to do is commit the changes to the package.json, and push to master

git add .
git commit -m 'updated package.json'
git push
        

Prerequisite

This boilerplate includes image resizing and optimization, which requires the imagemagick and graphicsmagick libraries to be installed on your system. For Mac you can install these via brew

brew install imagemagick --build-from-source
brew install graphicsmagick --build-from-source
        

Instalation

from within the project directory run

npm install
npm run build
        

This will first download all the dependencies and then build the project. Simple. Open localhost:8888 and you should see 'Hello world'

Other commands are
npm run clean - which will delete all files in /dist and /dev, not including images,
npm run clean-all - which will delete all files in /dist and /dev, including images and
npm pretty - which will prettify the contents of the /src directory.

Project structure

project-name
+ dev           # compiled from src, for development
+ dist          # compiled from src, for production
+ node_modules
- src
  + css
  + icons       # favicon icons + android manifest etc
  + images
  + js
  + scss        # optional, use one, both or neither
  + less        # optional, use one, both or neither
  index.html
.editorconfig
.env            # for ssl localhost
.gitignore
.jsbeautifyrc   # options for prettifying
gulpfile.js
package.json
        

Features

Server

The boilerplate comes with a fully loaded express server for all your developement needs, including https, http2 and gzip compression.

The node run build command will fire up 2 servers listening to localhost:8888 and serving the /dist directory, and another one listening to localhost:8887 and serving the /dev directory

If you have https://localhost then express will look for the certificate and key in the .env file in the root directory of the project, and should look something like this

SSL_CRT_PATH = "/.ssl/localhost.crt"
SSL_KEY_PATH = "/.ssl/localhost.key"
        

Mac users can setup ssl for localhost with these 3 simple commands

If you don't have ssl setup for localhost then express will fallback to http://localhost, without ssl and http2, but still with gzip compression.

The /dist directory will contain all the production ready code, minified & combined html, css and js files.
The /dev directory contains the same code, only prettified and from the source files (before combining) making development easier. Images are the same in both directories.

Image optimization

All images that are placed in the /src/images directory will be optimized before they are copied to the /dist and /dev directories.

Image resizing

All images that are placed in the /src/images directory will also be resized to 400, 800, 1200, 1600 and 2400px wide, and placed in a sub-directory with the name of the size. eg /images/400/sunrise.jpg

Images will not be upscaled, meaning an image of 3000 x 2000px will be resized to all of the above sizes, but an image of 960 x 640px will only be resized to 400 and 800. All resized images are also optimized.

Minifying and uglifying assets

html, css and javascript will be minified, javascript will also be uglified before beign copied to /dist

Prettifying assets

html, css and javascript will be prettified before being copied to /dev

File combining

When marked, css and javascript can be combined into a single file, like so

<!-- build:css css/global.css -->
<link href="css/normalize.css" rel="stylesheet">
<link href="css/main.css" rel="stylesheet">
<!-- endbuild-->
        

This will result in the following markup in /dist
In /dev the original source files will be used.

<link href="css/global.css" rel="stylesheet">
        

Preprocessors

scss and less files will be converted to css, this css will also be minified and can be sourced for file combination if required.

Autoprefixing

css properties and values will be autoprefixed so they work on older browsers, current settings are for browsers with greater than 1% global usage.

for example

.example {
    display: flex;
    flex-direction: column;
}
        

will become

.example {
    display: -webkit-box;
    display: flex;
    -webkit-box-orient: vertical;
    -webkit-box-direction: normal;
    flex-direction: column;
}
        

File caching

The build process will also launch a watch process, to re-build the /dev and /dist directories whenever a file is saved.

This process will only trigger a build for files that have changed. Eg. images wont be reprocessed if a html file is changed.

Favicons, apple, android and windows icons

In the /icons directory there are placeholder icons etc. To build your own from source I would strongly recommend realfavicongenerator.net

Social meta

The index.html includes all the meta for good social media sharing (twitter and facebook). You just need to change the values

Go and checkout html5-gulp-boilerplate project over at github