Drupal Gulp

A basic, reusable Gulp setup for use with Drupal 8+ projects.

Installation

• cd into the root of your Drupal project/repository.
  • This is the directory containing composer.json.
• Run npm install --save-dev https://github.com/jigarius/drupal-gulp.
  • Observe: The package should be installed at node_modules/drupal-gulp/.
• Copy the following files from node_modules/drupal-gulp/dist/ into the project's root. Modify them if you know what you're doing.
  • gulpfile.js
  • gulp.config.js
  • .eslintrc.yml
  • .sass-lint.yml

You should now be able to use Gulp: npx gulp. For this to work, your custom packages must follow a specific directory structure.

Usage

Package structure

To standardize the solution and to make it reusable, this Gulp setup assumes the following directory structure.

• The gulpfile.js is in the root of the Drupal project.
• Drupal's document root is docroot or web.
• Custom extensions are in one of the following standard paths:

  DRUPAL/modules/custom/*
  DRUPAL/themes/custom/*
  DRUPAL/sites/*/modules/custom/*
  DRUPAL/sites/*/themes/custom/*
  

• Each custom extension has the following directory structure:
  • vendor contains 3rd-party libraries (ignored).
    • Other directories can be ignored with custom configuration.
  • styles/ extension's styles.
    • *.scss contains style sources.
    • *.min.css (generated by Gulp).
    • *.css.map (generated by Gulp).
  • scripts/ extension's scripts.
    • *.js contains script sources.
    • *.min.js (generated by Gulp).
    • *.js.map (generated by Gulp).
  • components/**/COMPONENT/
    • *.scss contains component's styles.
    • *.min.css (generated by Gulp).
    • *.css.map (generated by Gulp).
    • *.js contains component's scripts.
    • *.min.js (generated by Gulp).
    • *.js.map (generated by Gulp).
• Assets must be referenced using relative paths, e.g. url("../../images/foo.jpg").
• Files that are just meant for being imported should be named with an underscore in the beginning. For example, for a _includes.scss file, a processed .min.css will not be generated.

Commands

See a list of all Gulp tasks with gulp -T. Here are some common tasks:

• gulp build - Build all assets.
• gulp watch - Watch for changes and build assets when sources change.
• gulp config - Display the final configuration object received by Gulp tasks. This is useful debugging.

To vary the verbosity of Gulp output, use the -L flag. For example, to view debug-level output, you can run gulp -LLLL build.

Scripts

Optionally, you can add the following scripts to your package.json.

{
  "scripts": {
    "build": "npx gulp build",
    "lint": "npx gulp lint",
    "watch": "npx gulp watch"
  }
}

You can execute these scripts with npm run, e.g. npm run build.

Development

This project uses Docker Compose. You can set up a local dev environment as follows:

• Clone the repository and cd into it.
• For the first time (or after docker-compose.yml is modified), run make build
• make start - Start dev env.
• make ssh - Launch a shell inside the Docker container.
  • /package contains the drupal-gulp package.
  • /app contains a sandbox for testing the Gulpfile.
• make stop - Stop dev env.

To learn more about the development environment, see:

• docker-compose.yaml
• Makefile

Updating

To update the Gulp setup in an existing project,

• Run npm update drupal-gulp.
• Delete the following files from your Drupal project and replace them with the newer versions in node_modules/drupal-gulp/dist/.

At this point, you should be able to run gulp again.

Acknowledgements

This package is brought to you by Jigarius.