Gulp Webpack Boilerplate
๐ Overview
A modern JavaScript starter toolkit for web-development using Gulp task runner and Webpack bundler.
Ideal for fast building static HTML sites or templates. It speeds up the proccess of delevelopment, testing and deploy in a front-end project. Also it can be extended in a simple way when project require some extra functionality provided by thirdparty packages.
All the tasks are done via Gulp. Webpack is just used for Javascript (especially for ES6 Import/Export as Gulp can't do it in a proper way) and not for rest because it's a little bit overhed to translate all static assets and styles through js using Webpack.
๐ Table of Contents
๐ Demo of projects using this boilerplate
๐ง Features
| Feature | Description |
|---|---|
| Javascript | Full support of javascript latest features using Babel loader and Webpack. Also, there is a lot of code optimization while building in production mode. |
| HTML | Pug templates provide an opportunity to make a better structure and code readability and then compiling it to HTML. |
| Styles | Stylus support with compiling to css and doing minification with concatenation. |
| Autoprefixier | Parse CSS and add vendor prefixes(-wbkit, -moz, -o, -ms) to rules in production build. |
| Sourcemaps | Css and js source maps in development mode. |
| Bootstrap | You can specify what part of Bootstrap do you need and then compile it to get the low size files. |
| Live Reload | Automatic reloading of the browser on code modification and cross-platform syncing of all actions between connected devices. This depends on Gulp-watch, Webpack-watch, BrowserSync. |
| Google Fonts | Auto-downloads Google fonts specified in fonts list then generates css with them and finally moves them to the build dir. |
| Images | Compressing images to desired quality and size through Mozjpeg or Guetzli. |
| Hashed names | File names contain smart hashes in production mode. Hash will change on file modifications. This helps to avoid browser long term caching. |
| Code linting | Eslint checks js code according to AirBnb rules and notify if something wrong. |
| Code formatting | Prettier auto-formats js code that doesn't satisfy Eslint styles rules. |
| Cached files | Gulp tasks configured to process only new files in development mode. |
| Error notifier | You get a desktop notification when errors occur. |
๐ฌ Project Structure
โโโ dist/ # Static version of the website
โ โโโ css/ # Folder for concatenated css file
โ โโโ fonts/ # All fonts files
โ โโโ img/ # Images
โ โโโ js/ # Folder for bundle js file
โ โโโ index.html # Can be any page and more than one
โโโ src/ # Source files
โ โโโ fonts/ # Fonts
โ โ โโโ fonts.list # Google Fonts config
โ โโโ img/ # Site images
โ โโโ js/ # Javascript files
โ โ โโโ bootstrap.js # Uncomment module that you need
โ โ โโโ entry.js # Webpack entry point
โ โ โโโ main.js # All user scripts
โ โโโ styles/ # Styles
โ โ โโโ bootstrap/ # Bootstrap sass config
โ โ โ โโโ bootstrap.scss # Uncomment module that you need
โ โ โ โโโ _variables.scss # Change what you want
โ โ โโโ main.styl # Main stylesheet file
โ โโโ templates/ # Site templates (Pug)
โ โ โโโ pages/ # Pug only looks for this dir
โ โ โ โโโ index.pug # You can create any amount of pages in this dir
โ โ โโโ navigation.pug # Site navigation
โ โ โโโ header.pug # Site header
โ โ โโโ footer.pug # Site footer
โ โ โโโ layout.pug # Main layout
โ โโโ vendor/ # Appears if CUSTOM_SOURCE options specified or fonts enabled.
โ โโโ bootstrap/ # Change source files to whatever you want
โ โโโ googleFonts/ # Storage for downloaded fonts
โโโ temp/ # Temporary folder
โ โโโ manifest/ # Manifests for the production build
โ โโโ rev-images.json # Hashed images names
โโโ .babelrc # Babel presets for latest js features
โโโ .eslintrc.js # ESLint config
โโโ .gitignore # List of files ignored by git
โโโ .prettierrc # Prettier formatter config
โโโ gulpfile.babel.js # Gulpfile config and tasks
โโโ license # Project license
โโโ package.json # Node.js dependencies and scripts
โโโ readme.md # Description of the project
๐ง Prerequisites
You must have :
- Node.js
- Yarn or Npm
- Gulp
or install :
- Install Node Version Manager with these commands:
sudo apt updatesudo apt install build-essential ; sudo apt install libssl-devcurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.34.0/install.sh | bashsource ~/.bashrc
- Install latest Node.js :
nvm install nodenvm use node
- Install Yarn or Npm :
sudo apt install yarnornvm install --latest-npm
- Optionally, also install Gulp globally if you want to launch tasks without
yarn runornpm start:yarn add globalornpm install --global gulp
๐จ Installation
- Go to the directory where you want
cd somedirectory - Clone this repo to your computer
git clone https://github.com/noth8/gulp-webpack-boilerplate.git - Go to cloned repo
cd gulp-webpack-boilerplate - Install all packages with
yarn installornpm install
๐ด Launch
Yarn Commands
| name | Description |
|---|---|
yarn run dev |
Build in development mode |
yarn dev |
Same as yarn run dev |
yarn run prod |
Build in production mode |
yarn prod |
Same as yarn run prod |
Npm Commands
| name | Description |
|---|---|
npm run dev |
Build in development mode |
npm run prod |
Build in production mode |
Look at 'Packages list' section for more information about used plugins in dev or prod mode.
๐ Config options in gulpfile.babel.js
| name | default | true | false |
|---|---|---|---|
| GOOGLE_FONTS_ENABLED | true | Gulp downloads fonts listed in fonts.list and copies them to dist dir. |
- |
| BOOTSTRAP_ENABLED | true | Specify what you need in : bootstrap.js, bootstrap.scss, _variables.scss and webpack will take it from bootstrap source and add it to bundle. |
You can also use default bootstrap by specifying import 'bootstrap' in entry.js |
| BOOTSTRAP_CUSTOM_SOURCE | true | Give you a copy of bootstrap source if you want to make some changes directly. | Using bootstrap from node_modules/ |
| AUTOPREFIXER_BROWSER_LIST | last 2 versions | browsers versions that automatically gets properties specific to them (-ms, -moz, -webkit) |
- |
| IMAGE_ENCODER_GUETZLI | false | Uses Guetzli encoder for build in production mode. | Uses MozJPEG encoder for build in production mode. |
| IMAGE_COMPRESSION_RATE | 84 | Compression quality, in range 0 (worst) to 100 (perfect). | - |
๐ Packages list
General :
-
gulp - The streaming build system.
Purpose : automated development process by running tasks. -
webpack - is a bundler for javascript. Packs many modules into one or a few bundled assets.
Purpose : proper js bundling what gulp doesn't do. -
bootstrap - is an open source framework for developing with HTML, CSS, and JS.
Purpose : responsive grid on web and mobile. -
jquery - is a JavaScript library designed to simplify HTML DOM tree traversal and manipulation.
Purpose : for custom code and also for bootstrap dependency. -
popper.js - A popper is an element on the screen which "pops out" from the natural flow of your application.
Purpose : bootstrap dependency. -
gulp-google-webfonts - a plugin to download Google webfonts and generate a stylesheet for them.
Purpose : automate the process of using google webfonts just specifying them in one file(fonts.list). -
gulp-load-plugins - loads gulp plugins from package dependencies and attaches them to the specified object.
Purpose : imports google-webfonts when they are needed (alternative to "require" with lazy loading). -
gulp-if - a ternary plugin: conditionally control the flow of vinyl objects.
Purpose : helps to run plugins according to development or production mode specified. -
gulp-plumber - prevents pipe breaking caused by errors from gulp plugins.
Purpose : catch errors and send them to the node-notifier. -
gulplog - logger for gulp and gulp plugins
Purpose : pass to webpack errorHandler and print info if errors occur. -
node-notifier - a Node.js module for sending notifications on native Mac, Windows, and Linux.
Purpose : displays errors with platform-native notifications. -
gulp-pug - is a plugin for compiling Pug templates.
Purpose : translate pug files into html. -
through2 - is a tiny wrapper around Node.js streams. Allows writing gulp plugin.
Purpose : pass file name from stream to pug for navigation based on location. -
gulp-sass - is a wrapper around node-sass.
Purpose : compiles .scss files into css. -
node-sass - is a library that provides a binding for Node.js to LibSass.
Purpose : it's needed for gulp-sass. -
gulp-stylus - is a wrapper around stylus.
Purpose : compiles .styl files into css. -
stylus - providing an efficient and dynamic way to generate CSS
Purpose : it's needed for gulp-stylus. -
merge2 - Merge multiple streams into one stream in sequence or parallel.
Purpose : for skipping Bootstrap and Google fonts from merging when they are disabled. -
gulp-inject - ั javascript, stylesheet, and web component injection plugin.
Purpose : injects css and js files into html files by replacing special tags specified in pug files. -
gulp-concat - Streaming concatenation middleware for gulp
Purpose : merge css files into one. -
stream-combiner2 - Turn a pipeline into a single stream.
Purpose : less code for better readability. -
@babel/core - the core functionality of Babel.
Purpose : babel-loader dependency. -
@babel/register - is a require hook, that will bind nodeโs require method and automatically transpile the file on the fly.
Purpose : gulp.babel.js for es6 features. -
@babel/preset-env - is a smart preset that allows you to use the latest JavaScript without needing to micromanage which syntax transforms (and optionally, browser polyfills) are needed by your target environment(s). This Needs for webpack babel-loader.
Purpose : babel-loader configuration. -
babel-loader - Babel loader for webpack
Purpose : transforms Javascript code from new standards to previous for old browser support. -
babel-eslint - a wrapper for Babel's parser used for ESLint
Purpose : custom parser specified in eslintrc.js -
eslint - ESLint is an open source JavaScript linting utility.
Purpose : static javascript code analysis using specified rules. -
eslint-config-airbnb-base - base(without react) AirBnb list of rules.
Purpose : just because of the most popular and nice javascript style guide -
eslint-plugin-import - ESLint plugin with rules that helps validate proper imports.
Purpose : checks es6 imports.
Production :
-
del - delete files and folders using globs
Purpose : deletes build dir before other tasks run. -
gulp-autoprefixer - PostCSS plugin to parse CSS and add vendor prefixes to CSS rules using values from Can I Use.
Purpose : automatically adds browser's specific prefixes like '-moz', '-webkit-', '-ms'. -
gulp-clean-css - clean-css is a fast and efficient CSS optimizer.
Purpose : minify css files. -
gulp-imagemin - is an image compressor which is built around plugins like mozjpeg and others.
Purpose : minifies jpeg images with mozjpeg vs guetzli. -
imagemin-guetzli - imagemin plugin for guetzli.
Purpose : Guetzli-generated images are typically 20-30% smaller than others. -
imagemin-mozjpeg - Imagemin plugin for mozjpeg
Purpose : Mozjpeg-generated images are larger than Guetzli-generated but Mozjpeg is much faster. -
gulp-rev - appending content hash to filenames.
Purpose : helps to get rid of browser long term caching. -
gulp-rev-replace - rewrite occurrences of filenames which have been renamed by gulp-rev.
Purpose : replaces names in links to the images specified in html and css files from original to hashed using manifest file generated by gulp-rev.
Development :
-
browser-sync - keep multiple browsers & devices in sync.
Purpose : automatically reloads content on each saves on all connected devices and also catches all actions occurred in one of them and relays to others. -
gulp-sourcemaps - provides sourcemap support for other plugins.
Purpose : may show original css code locations before merging into one css. -
gulp-cached - this keeps an in-memory cache of files (and their contents) that have passed through it.
Purpose : caches styles between incremental builds. -
gulp-remember - is a plugin that remembers and recalls files passed through it.
Purpose : passes files to gulp-concat that were thrown back by gulp-cashed. -
gulp-newer - a plugin for passing through only those source files that are newer than corresponding destination files.
Purpose : processes the same fonts and images only once between incremental builds.
๐ Some notes about Guetzli
Guetzli is a JPEG encoder that aims for excellent compression density at the high visual quality. Guetzli-generated images are typically 20-30% smaller than images of equivalent quality generated by libjpeg. Guetzli generates only sequential (non-progressive) JPEGs due to faster decompression speeds they offer.
Requirements :
-
it uses a large amount of memory. You should provide 300MB of memory per 1MPix of the input image.
-
Guetzli uses a significant amount of CPU time. You should count on using about 1 minute of CPU per 1MPix of an input image.
-
Guetzli assumes that input is in sRGB profile with a gamma of 2.2. Guetzli will ignore any color-profile metadata in the image.
-
Guetzli is designed to work on high-quality images (e.g. that haven't been already compressed with other JPEG encoders). While it will work on other images too, results will be poorer. You can try compressing an enclosed sample high-quality image.
-
Guetzli converts PNG/JPG to JPG. When using this plugin or guetzli-bin CLI, the original filename+ext is used as the output, although the image format has changed. You have to rename the file with the correct file extension (JPG) yourself afterward.