Gulp Starter Kit
A starter template for Handlebar, Gulp, ECMAScript(latest), webpack3, sass and postcss.
Table of Contents
- Features
- Installation
- Getting Started
- List of Gulp tasks
- Configuration
- Directory Structure
- Dockerization
Features
This starter also features a number of great software (in the words of their creators):
- Lanyon - a content-first, sliding sidebar theme (originally) for Jekyll (by mdo).
- Gulp - a task automation tool.
- Browsersync - time-saving synchronised browser testing, keep multiple browsers & devices in sync when editing files.
- EditorConfig - a config file for maintaining consistent coding styles.
Assets
- svgo - a Node.js module for optimizing SVG vector graphics files.
- svg-sprite - a Node.js module for takes a bunch of SVG files, optimizes them and bakes them into SVG sprites.
- Favicons - a Node.js module for generating favicons and their associated files.
- imagemin - a Node.js module for minify images seamlessly.
- assets-manager - a Node.js module for transfer the required files from your registry distributions to the target.
JavaScript
- Babel - a JavaScript compiler for es5 to es6/7.
- rollup - a module bundler for JavaScript.
- Webpack - a bundler for JavaScript.
- ESLint - the pluggable linting utility for JavaScript and JSX (with preconfigured ruleset by Google.
- UglifyJS – A JavaScript parser, minifier, compressor or beautifier toolkit.
StyleSheet
- Sass - CSS with superpowers.
- PostCSS - a tool for transforming styles with JS plugins.
- Autoprefixer - adding vendor prefixes by the rules of Can I Use.
- csso - a CSS minifier with structural optimizations.
- Stylelint - a mighty, modern CSS linter (with preconfigured ruleset by Hugo Giraudel).
Html
- handlebars - a javascript template engine.
- handlebars-wax - Effortless registration of data, partials, helpers, and decorators using file-system globs, modules, and plain-old JavaScript objects.
- handlebars-layouts - a handlebars helpers which implement layout blocks.
- handlebars-helpers - More than 180 Handlebars helpers in ~20 categories.
- HTMLHint - a Static Code Analysis Tool for HTML.
- html-minifier - a javascript-based HTML compressor/minifier.
Rollup plugins
- rollup-plugin-node-resolve - Use the Node.js resolution algorithm with Rollup.
- rollup-plugin-commonjs - Convert CommonJS modules to ES2015.
- rollup-plugin-uglify - Rollup plugin to minify generated bundle.
Webpack plugins
- DefinePlugin
- ProvidePlugin
- CommonsChunkPlugin
- NoEmitOnErrorsPlugin
- LoaderOptionsPlugin
- UglifyJsPlugin
- expose-loader
- BannerPlugin
Tests
- Gemini - a utility for regression testing the visual appearance of web pages.
Git Hooks manager
Installation
Node version manager
Install NVM. And use the latest version of NodeJS.
nvm install node
nvm use node
Install Sass
Go to sass-lang.com/install for installation in command line.
gem install sass
Before install sass, you should install Ruby and install Gem.
Install Yarn
npm install --global yarn
Install Babel
npm install --global babel-cli
Install Gulp
npm install --global gulp-cli
Install Gemini
npm install -g gemini
npm install -g selenium-standalone
selenium-standalone install
Getting started
- Clone this Boilerplate
$ git clone https://github.com/amazingsurge/gulp-starter-kit.git <PROJECT_NAME>
$ cd <PROJECT_NAME>
- Install Dependencies
$ yarn install
- Build the project
$ gulp
- Stay up-to-date
$ git remote add upstream https://github.com/amazingsurge/gulp-starter-kit.git
$ git pull upstream master
List of Gulp tasks
To run separate task type in command line gulp [task_name]
.
Almost all tasks also have watch mode - gulp watch:[task_name]
, but you don't need to use it directly.
Main tasks
Task name | Description |
---|---|
default |
will start all tasks required by project in dev mode: initial build, watch files, run server with livereload |
build |
builds all content and assets from src to dist . |
dev |
builds your project without optimization. |
Core tasks
Task name | Description |
---|---|
styles |
compile all scss from src/styles to dist/assets/styles folder. |
scripts |
compile all js from src/scripts to dist/assets/scripts folder. |
html |
compile all hbs files to html files. |
usemin |
replaces references to non-optimized scripts or stylesheets into a set of HTML files |
Assets related tasks
Task name | Description |
---|---|
copy |
copy files from src/assets path to dist/assets path. |
vendor |
copy vendor files from registry distributions to dist/assets/vendor path. |
svgs |
optimize svg files. |
sprite |
generate svg sprite. |
fonts |
copy files from src/fonts path to dist/fonts path. |
favicons |
generate favicons to dist/assets/favicons path. |
images |
optimize and copies images in src/images to dist/assets/images . |
srcset |
Generate responsive images to dist/assets/images . |
Dev tasks
Task name | Description |
---|---|
clean |
remove dist folder. |
beautify |
beautify your source files in src/styles and src/scripts . |
server |
start a BrowserSync instance. |
watch |
watchs for changes in src/ path and rebuilds parts of the site as necessary. |
Version tasks
Task name | Description |
---|---|
version:major |
MAJOR version when you make incompatible API changes |
version:minor |
MINOR version when you add functionality in a backwards-compatible manner |
version:patch |
PATCH version when you make backwards-compatible bug fixes. |
version |
alias to version:path . |
All available tasks are placed in a folder tasks
.
Flags
gulp [task_name] --prod
orgulp [task_name] --production
to run task in production mode.
Workflow
Everything's ready to get started right away:
npm start
- Compiles assets & html, launches development server:
- compiles styles & scripts are being compiled & concatenated
- compresses images & svgs
- builds the site & opens it in your default browser
- watches for changes and injects them right away
npm run build
- Same as above, but in production mode:
- compiles & builds everything
- minifies & compresses everything
Configuration
Global variables and site metadata can be found inside config.js
. Your can make some modification in the file.
Directory Structure
The source
directory contains your entire application code, including CSS, JavaScript, HTML.
The rest of the folders and files only exist to make your life easier, and should not need to be touched.
Below you can find full details about significant files and folders.
├── README.md # Readme file
├── package.json # Dependencies for node.js
├── LICENSE # License
├── .babelrc # Babel config file
├── .gitignore # Git ignore rules
├── .htmlhintrc # Settings for HTMLHint
├── postcss.config.js # PostCSS config
├── gulpfile.babel.js # The Gulp task manager configuration
├── /webpack/ # Webpack config
├── /tasks/ # Gulp tasks definitions
├── /archives/ # Folder with zip archives
├── /dist/ # Minified, optimized and compiled files
│ ├── /assets/ # Assets folder
│ │ ├── /styles/ # CSS files
│ │ ├── /scripts/ # JS files
│ │ ├── /fonts/ # Fonts folder
│ │ ├── /images/ # Images folder
│ │ ├── /svgs/ # Svg files
│ │ └── /favicons/ # Favicons files
│ └── *.html # Rendered and compiled HTMLs from hbs
└── /src/ # The source code of the application
├── /assets/ # Static assets files copy to dist
├── /data/ # Metadata associated with the site.
├── /styles/ # Stylesheets source
├── /scripts/ # Javascript source
├── /fonts/ # Font files
├── /images/ # Non compressed image files
├── /svgs/ # Non compressed svg files
├── /favicons/ # Favicon image
├── /helpers/ # Handlebars helpers
├── /layouts/ # Handlebars layouts that are based on
├── /partials/ # Handlebars partials that are included / extended
└── /html/ # Handlebars pages, one per page on the site
Running tests
Start selenium-standalone
in a separate tab before running the tests:
selenium-standalone start
Run gemini tests with flat reporter:
gemini test --reporter flat
Dockerization
- Build and run the Container
$ docker-compose up
- Run a command in a running container
$ docker-compose exec app <COMMAND>
- Remove the old container before creating the new one
$ docker-compose rm -fs
License
The code is available under the MIT license.