Gulp Stack

Requirements

Required :

• NVM, or Node version with NPM : see .nvmrc.

• gulp-cli as a global dependency : npm install gulp-cli -g.

  This dependency is essential to use the Gulp tasks. You have to install it after using the right Node version, because gulp-cli version depends on Node version. You may have to reinstall it if you switched to a "new" Node version.

Installation

NPM

https://www.npmjs.com/package/@ecedi/gulp-stack

Then npm install @ecedi/gulp-stack --save-dev.

Project configuration

• Copy config.example.json to your project root folder (where there is your package.json), and rename it in config.json
• Adjust the paths or parameters if necessary for your project :
  • gulp.twig.watch or gulp.sass.watch : list of file(s) to watch
  • gulp.twig.tasks or gulp.sass.tasks : list of compilation tasks, each one is an object with parameters :
    • src : source file(s)
    • dest : destination folder
    • base (only for Twig) : base path, will be used for {% extends ... %}
  • gulp.sass.options : list of Sass options you want to use for compilation
  • gulp.sass.lint : list of files to lint
  • browsersync : BrowserSync parameters
  • front_paths : list of root-relative paths, to use in Twig files
  • namespaces : list of @... namespaces to use in Twig files
  • static_path_debug_txt : text for path debug comments
• Copy .browserslistrc.example to the parent folder, and rename it in .browserslistrc. Update the options if needed.

Start

To use the commands, add scripts in your package.json :

"scripts": {
  "start": "gulp --gulpfile node_modules/@ecedi/gulp-stack/gulpfile.js",
  "dev": "gulp dev --gulpfile node_modules/@ecedi/gulp-stack/gulpfile.js",
  "prod": "gulp prod --gulpfile node_modules/@ecedi/gulp-stack/gulpfile.js",
  "lint": "gulp lint --gulpfile node_modules/@ecedi/gulp-stack/gulpfile.js"
},

See below for the detail of what each of the gulp tasks does.

Then you can initialize the styles & static files by running one of the command lines :

• npm start
• or npm run dev

Gulp tasks

Summary

| Tasks | watch for changes | compile Twig | compile SCSS | minify SCSS | lint SCSS | |---------------------------| ------------------ |--------------------|--------------------|--------------------|--------------------| | default | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | | | dev | | :heavy_check_mark: | :heavy_check_mark: | | | | prod | | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | | lint | | | | | :heavy_check_mark: | | watchAll (private) | :heavy_check_mark: | | | | | | twigToHtml (private) | | :heavy_check_mark: | | | | | sassToCssDev (private) | | | :heavy_check_mark: | | | | sassToCssProd (private) | | | :heavy_check_mark: | :heavy_check_mark: | | | lintSass (private) | | | | | :heavy_check_mark: |

Public tasks (exported)

• default (command gulp) : twigToHtml + sassToCssDev + watchAll
• dev: compile Twig & SCSS files with sourcemaps : twigToHtml + sassToCssDev
• prod: compile Twig & SCSS files minified : twigToHtml + sassToCssProd
• lint: lint files : lintSass

Those tasks are public because they are exported.

You can use them in the gulp-stack folder (command gulp dev for example) or in your project through the NPM scripts (command npm run dev for example).

Private tasks

• watchAll: allows watching globs and running a task when a change occurs + runs browserSync
• twigToHtml: compile the Twig files in the static folder (when there is a static front)
• sassToCssDev: compile the SCSS files in the CSS folder, with sourcemaps & autoprefixer
• sassToCssProd: compile & minify the SCSS files in the CSS folder
• lintSass: lint SCSS files to display Stylelint errors

Those tasks are also defined in gulpfile.js but you can't call them via the command line because they aren't exported.

Files

• gulpfile.js: Gulp main file where tasks are declared and launched
• package.json: main file where global infos and dependencies are declared
• package-lock.json: main file where dependencies are listed with a fixed/precise version, to avoid differences between instances of the same project
• config.example.json: example of a project config file where path variables are declared
• .browserslistrc.example: example of a browserslist config file.
• .nvmrc: indication of the Node version to use