@studiometa/gulp-config

Gulp Configuration

Simplify your Gulp configuration to compile, lint, fix, compress and live-reload SCSS and JS files.

Table of contents

• Usage
  • CLI options
• Configuration
  • Styles
    • src
    • glob
    • dist
    • postCssPlugins
    • cleanCssOptions
    • styleLintOptions
  • Scripts
    • src
    • glob
    • dist
    • uglify
    • uglifyOptions
    • es6
    • babelOptions
    • esModules
    • webpackOptions
    • ESLintOptions
  • Server
    • browserSyncOptions
    • watchers
• Contributing

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 your gulpfile.js file with the dotenv package and set a variable named APP_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 accessing http://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 of mkcert 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.