- Features
- System requirements
- Setup
- Initialization
- Project structure
- Common params
- Working with files
- Deploy
- Creating ZIP archives
- Audit with PageSpeed Insights
- Import data from JSON files and templating HTML (import, iteration, etc).
- Compiling SASS / SCSS files to CSS, adding browser prefixes, grouping media queries.
- Import and export of ECMAScript modules inside JS files.
- Transpiling JS files to ES5 using Babel (optional).
- Building JS files using Rollup (optional).
- Optimization and compression of raster (JPG, PNG, GIF) and vector (SVG) images.
- Convert SVG files to Base64 and then import to CSS (optional).
- Convert images to WebP format (optional).
- Automatic import of Icomoon icons in SASS/SCSS from
selection.jsonfile. - Watching and automatic recompilation of files.
- Generation abstract page with list of project files and used dependencies (optional).
- Linting SASS and JS files with Stylelint and ESLint.
- Sourcemaps generation (optional).
- Creating ZIP archives with source and compiled files (optional).
- Uploading project files to server via FTP (optional).
- PageSpeed Insights reports on the local server (optional).
For image compression you will additionally need to install the following libraries:
brew install libjpeg libpngapt-get install -y libjpeg libpngYou can configure common params using configurator or define them yourself in /config.js file.
Go to project directory and install required dependencies:
npm ciAfter that, start building:
gulpgulp-project # Root directory
├── gulp # Gulp files
│ └── config # Global params
├── src # Source files
│ ├── abstract # Source files for abstract page
│ ├── data # JSON files
│ ├── fonts # Fonts
│ ├── icomoon # Icomoon project files
│ ├── images # Images
│ ├── js # JavaScript files
│ ├── styles # SASS / SCSS files
│ ├── partials # Included HTML files
│ ├── swipers # JSON files with Swiper params
│ ├── templates # Templates (Handlebars, Mustache etc)
│ ├── vectors # SVG files for embedding in CSS
│ └── index.html # Index page
├── .browserslistrc # Supported browsers list
├── .editorconfig # IDE settings
├── .env # Environment settings
├── .eslintrc # ESLint configuration file
├── .gitignore # Git ignored files
├── .stylelintignore # Stylelint inglored files
├── .stylelintrc # Stylelint configuration file
├── CHANGELOG.md # Release notes
├── config.js # User params
├── gulpfile.js # Main file for Gulp
├── package-lock.json # Dependencies tree
├── package.json # Project info
├── README-ru.md # Documentation in Russian
└── README.md # Documentation
Each time the build is run, params are imported from following files:
- Global params
/gulp/config - User params
/config.js
Parameter priority (in ascending order):
- Global params
- User params
- Presets (params from presets fields in configuration files)
- cli params
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| minify | object | false | Minify files |
| sourcemaps | object | false | Generate sourcemaps for CSS and JS files |
| babel | boolean | false | Transpile JS to ES5 with Babel |
| rollup | boolean | false | Building JS with Rollup |
| webp | boolean | false | Convert all images to WebP format |
| abstract | boolean | false | Generate abstract page with project files list |
| debug | boolean | false | Enable debug mode |
| force | array | [] | Tas 8000 k names for force upload |
| preset | string | 'global' | Name of applying preset |
| open | string | 'index' | Startup page (without .html extension) |
| host | string | 'default' | FTP host key from config.ftp file |
| mode | string | 'dev' | Building mode (dev/build), available globally in HTML as @@mode |
All of the above params can be passed to command line through appropriate flags.
Example running with cli params:
gulp --babel --minify js --open catalogThe described command is equivalent to the following entry in configuration file:
{
babel: true,
minify: {
css: false, // inherited from global params
js: true
},
open: 'catalog'
}Presets allow you to start building with predefined params depending on task name or create your own combinations of params.
To create a new preset, add params to presets field in /config.js file.
Params from preset will be applied if:
- Preset name is equivalent to current task name (
build- for build task,deploy- for deploy task, etc); - Preset name passed as cli param
--preset.
Preset example
config.presets = {
deploy: {
babel: true,
compress: true,
mode: 'build'
}
}
This preset is equivalent to launching with following params:
gulp deploy --babel --compress --mode buildCustom preset example
config.presets = {
myPreset: {
debug: true,
minify: {
css: true,
js: true
}
}
}
The above params will be applied when --preset flag is explicitly specified:
gulp --preset myPresetParams from global preset are always applied and can only be overridden from command line.
config.presets = {
global: {
abstract: true,
open: 'home'
}
}HTML files are placed in /src directory.
Included files are placed in /src/partials/ directory.
For convenient work with HTML files, you can use gulp-file-include operators:
@@include@@if@@for@@loop
Documentation and usage examples can be found here.
SASS / SCSS files are placed in /src/styles directory.
JS files are placed in /src/js directory.
By default, all SASS and JS files are combined into one output file. If you need to create a separate file, append
.modulepostfix to file name (e.g.component.module.scss). Thereaftercomponent.cssfile will be created and added to all project pages.
Images are placed in /src/images directory.
Compression settings are set in config.plugins.image param.
To convert all images to WebP format, set config.webp param to true.
To convert SVG files to Base64 and subsequent embedding to CSS, move them to the /src/vectors directory.
To add icons, move Icomoon project files from icomoon.io website to /src/icomoon directory.
The icons will be available in SASS via $icomoon-icons map.
If you are using HTML compilers like Handlebars or Mustache, you can store template files in /src/templates directory.
Before deploying files to server, you must set FTP params in .env file.
After that, run the command:
gulp deployBy default, files are uploaded to default host.
If you need to create another FTP host, add params to .env file:
FTP_CUSTOM_HOST=HOSTNAME
FTP_CUSTOM_USER=USER
FTP_CUSTOM_PASSWORD=PASSWORD
FTP_CUSTOM_DEST=DEST
FTP_CUSTOM_URI=URL
After that, import environment params in config.js file and use host name as object key:
config: {
ftp: {
custom: {
host: process.env.FTP_CUSTOM_HOST,
user: process.env.FTP_CUSTOM_USER,
password: process.env.FTP_CUSTOM_PASSWORD,
dest: process.env.FTP_CUSTOM_DEST,
uri: process.env.FTP_CUSTOM_URI
}
}
}
To upload files to the custom host, run command:
gulp deploy --host customBefore building, you can pass a list of required tasks through the --force flag. Then only selected tasks will be launched, and all others will be ignored.
This can be useful if you want to build and deploy recently modified files only.
gulp deploy --force html,css,jsIn production mode transpiling to ES5 and minification of files are enabled by default, so passing --minify and --babel flags is not required.
If you want to change this behavior, edit config.presets.deploy preset.
To create ZIP files with source and compiled files, run the task:
gulp zipFile names for ZIP files are specified in config.files.zip param.
Google Lighthouse is an open source auditing tool that helps developers improve performance and accessibility of their web projects.
PageSpeed Insights reports are generated on the local server for each project page after running the command:
gulp reportsDepending on number of pages and hardware resources, this task may take a long time to complete.