Gulp Configuration
Simplify your Gulp configuration to compile, lint, fix, compress and live-reload SCSS and JS files.
Table of contents
Usage
Install the package with your Yarn:
yarn add --dev @studiometa/gulp-config
Or with NPM:
npm install --save-dev @studiometa/gulp-config
Create a file named gulpfile.js
at the root of your project with the following:
const config = require('@studiometa/gulp-config');
module.exports = config.create({
styles: {
src: './tests/src/styles',
dist: './tests/dist/styles',
},
scripts: {
src: './tests/src/scripts',
dist: './tests/dist/scripts',
},
server: true,
});
You will then have the following tasks available:
gulp styles-build
gulp styles-lint
gulp styles-format
gulp scripts-build
gulp scripts-lint
gulp scripts-format
gulp serve
The gulp
default tasks will execute the build and lint tasks before the server one.
The server tasks watch automatically for changes in the styles and scripts files to re-trigger the build and lint tasks.
CLI options
All the defaults Gulp CLI flags can be used when running a task, with the following custom ones:
Flag | Short Flag | Type | Description |
---|---|---|---|
--diff-only | -d | Boolean | Execute the given task only on files listed in your `git diff`. |
--quiet | -q | Boolean | Disable most of the system notifications to improve performance. |
--fail-after-error | Boolean | Specific to the lint tasks, they will end with a non-zero error code if any error level warnings were raised. |
Configuration
The main options object can contain 3 different keys : styles
, scripts
and server
. If one of them is omitted, the corresponding tasks won't be created. Find below the description and default values for each configuration object.
Styles
styles.src
(String)
The path to your SCSS files.
{
src: 'src/styles',
}
styles.glob
(String)
The glob to match your SCSS files.
{
glob: '**/*.scss',
}
styles.dist
(String)
The path where the compiled CSS files are saved.
{
dist: 'dist/styles',
}
styles.postCssPlugins
(Array)
A list of PostCSS plugins to use.
{
postCssPlugins: [
autoprefixer(),
],
}
styles.cleanCssOptions
(Object)
Options for the gulp-clean-css
plugin.
{
cleanCssOptions: {
level: 1,
},
}
styles.gulpSassOptions
(Object)
Options for the gulp-sass
plugin. It uses the node-sass-magic-importer
by default to resolve @import
in your SCSS files.
{
importer: require('node-sass-magic-importer')({
disableImportOnce: true,
}),
}
styles.styleLintOptions
(Object)
Options for the gulp-stylelint
plugin. This configuration is used in both the styles-lint
and styles-format
tasks, with the fix
options automatically set to true
for the styles-format
task.
{
failAfterError: false, // forced to false, except if `--fail-after-error` is specified
reporters: [
{
formatter: 'string',
console: true,
},
],
}
Scripts
scripts.src
(String)
The path to your JS files.
{
src: 'src/scripts',
}
scripts.glob
(String)
The glob to match your JS files.
{
glob: '**/*.js',
}
scripts.dist
(String)
The path where the uglified and/or compiled JS files are saved.
{
dist: 'dist/scripts',
}
scripts.uglify
(Boolean)
Whether to run or not gulp-uglify
on the Javascript files.
{
uglify: true,
}
scripts.uglifyOptions
(Object)
Options for the gulp-uglify
plugin.
{
uglifyOptions: {
compress: {
drop_console: true,
},
},
}
scripts.es6
(Boolean)
Enable/Disable es6 scripts compilation.
{
es6: false,
}
scripts.babelOptions
(Object)
Options for the gulp-babel
plugin.
{
babelOptions: {
presets: [ '@babel/preset-env' ],
},
}
scripts.esModules
(Boolean)
Enable/Disable es6 modules resolution with Webpack.
{
esModules: false,
}
scripts.webpackOptions
(Object)
Options for the webpack-stream
plugin.
{
webpackOptions: {
mode: 'production',
devtool: false,
module: {
rules: [
{
test: /\.js$/,
exclude: /(node_modules|bower_components)/,
use: {
loader: 'babel-loader',
},
},
],
},
},
}
scripts.ESLintOptions
(Object)
Options for the gulp-eslint
plugin. Check for a .eslintrc
file in your project by default. This configuration object is used in both the scripts-lint
and scripts-format
tasks, with the fix
options automatically set to true
for the scripts-format
task.
{
ESLintOptions: {
useEslintrc: true,
},
}
Server
You can simply enable the server task by setting the server
key to true
in your configuration. But you might want to set some more detailed configuration with extra watchers for example.
server.browserSyncOptions
(Object)
Options for the browser-sync
plugin.
{
browserSyncOptions: {
watchTask: true,
open: false,
proxy: process.env.APP_HOST || false,
},
}
If your project is using a
.env
file, you can load it in yourgulpfile.js
file with thedotenv
package and set a variable namedAPP_HOST
to take advantage of the default browser-sync configuration. The server setup by browser-sync will then be proxied on the port 3000 of the host you defined, you will have live-reload enabled by accessinghttp://APP_HOST:3000
.
Example of configuration to enable browserSync with https://
:
{
browserSyncOptions: {
proxy: 'https://local.fqdn.com',
https: {
key: 'path/to/your/key.pem',
cert: '/path/to/your/cert.pem',
},
},
}
You can easliy create a valid certificate for your local domain
local.fqdn.com
with the help ofmkcert
and the following command:mkcert local.fqdn.com fqdn.com localhost 127.0.0.1
server.watchers
(Array)
A list of files you want to watch when the server is running. It allows you to execute custom tasks and callbacks when the given files or glob changes. By default, the build tasks (styles-build
and scripts-build
) and the lint tasks (styles-lint
and scripts-build
) are triggered when any of the files found in the styles.src
and scripts.src
paths changes.
The following example will watch for changes in your HTML files and trigger a browser-sync reload and execute the styles-build
task:
{
files: [ '**/*.html' ],
options: {
cwd: 'path/to/your/files',
},
callbacks: [
{
event: 'change', // 'add', 'change' or 'unlink'
callback: (browserSync) => browserSync.reload(),
},
],
tasks: [
'styles-build',
],
}
See the Gulp documentation on the watch
method for more detailed information on how a watcher works.
Contributing
This project's branches are managed with Git Flow, every feature branch must be merged into develop via a pull request.