Adfab Gulp Boilerplate

2.4.0 verified Fri May 01 auth: no javascript

A Gulp-based boilerplate for kick-starting front-end projects quickly, version 2.4.0. It integrates Browsersync for live reloading, supports SASS/LESS compilation, Babel transpilation, image minification, fonticon and SVG sprite generation, and includes linting for JS/SASS/LESS. Designed for teams needing a consistent, configurable build pipeline with JSON-based task configuration. Released under ISC license, with maintenance via GitHub issues and a SemVer release cycle. Alternatives include custom Gulp setups or modern build tools like Webpack/Vite.

Common errors

error Error: 'default' is not exported by ... ↓

cause Using ES6 import syntax (import) with a CommonJS-only package.

fix

Use require() instead of import: const gulp = require('gulp');

error Error: Task 'sass' is not defined in your gulpfile. ↓

cause The 'sass' task is not registered because gulp-sass is not installed or configured properly.

fix

Install gulp-sass: npm install gulp-sass --save-dev, and ensure gulpfile.js includes the boilerplate tasks by requiring 'adfab-gulp-boilerplate'.

error ReferenceError: gulp is not defined ↓

cause gulp is not installed or not required in the gulpfile.

fix

Install Gulp v4 and require it in the global gulpfile: npm install gulp@4 --save-dev

error Module not found: Can't resolve 'browser-sync' ↓

cause browser-sync is missing; it's a required peer dependency.

fix

Install browser-sync: npm install browser-sync --save-dev

Warnings

breaking gulp v4 is required – gulp v3 is not supported and will cause errors. ↓

fix Ensure Gulp v4 is installed: npm install gulp@4 --save-dev

deprecated The 'source' and 'destination' fields in gulp-config.json must not end with a trailing slash, otherwise paths break. ↓

fix Remove trailing slashes from source and destination paths in gulp-config.json

deprecated The 'task' property is required for each task in gulp-config.json; if omitted, the task name is used but may conflict with internal Gulp tasks. ↓

fix Always specify the 'task' property, e.g., "task": "copy".

gotcha When using the 'copy' task, ensure the destination folder is different from source to avoid infinite loops. ↓

fix Set destination to a separate directory (e.g., dist/fonts) rather than the source folder.

breaking Node.js <= 8 is no longer supported; newer versions may fail due to dependency updates. ↓

fix Upgrade Node.js to version >=10.

Install

npm install adfab-gulp-boilerplate

yarn add adfab-gulp-boilerplate

pnpm add adfab-gulp-boilerplate

Imports

default
wrong
```
import gulp from 'gulp';
```
correct
```
const gulp = require('gulp');
```
Uses CommonJS; no ES module wrapper, so require() is required.
gulpfile.js
wrong
```
Manually creating gulpfile.js from scratch
```
correct
```
No import required; the boilerplate auto-generates a gulpfile.js on install.
```
The package generates gulpfile.js and gulp-config.json automatically. Do not create them manually.
gulp-config.json
wrong
```
Editing node_modules files
```
correct
```
Edit gulp-config.json after installation to configure tasks.
```
Configuration is read from the project root's gulp-config.json, not from installed package.

Quickstart

Installs the boilerplate, auto-generates gulpfile.js and gulp-config.json, configures tasks for SASS and JS, and runs serve with Browsersync.

npm install adfab-gulp-boilerplate --save
# After installation, gulpfile.js and gulp-config.json are created in project root.
# Edit gulp-config.json to set vhost (local URL), sourceRoot, destinationRoot, and tasks.
# Example:
# {
#   "vhost": "http://mysite.local",
#   "sourceRoot": "./src",
#   "destinationRoot": "./dist",
#   "tasks": {
#     "styles": {
#       "task": "sass",
#       "source": "scss/main.scss",
#       "destination": "css"
#     },
#     "scripts": {
#       "task": "js",
#       "source": "js/**/*.js",
#       "destination": "js"
#     }
#   }
# }
# Then run:
gulp serve
# This starts Browsersync with live reloading.