@ecedi/gulp-stack v12.0.2-beta

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

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
• .eslintrc.json : JS linter (ESLint) parameters for JS files in this directory
• .gitlab-ci.yml: Gitlab integration for development on the repo, see below

Development

Redmine tickets : https://redmine.ecedi.fr/projects/ecedi-front-end-gulp/issues

Local development and testing

• Install the repo with the usual git clone, in a sibling folder of the project you want to use to test it.
• In this new gulp-stack folder, change whatever you need to change
• In the project, install gulp-stack "as if it was a package" :
  • Delete node_modules/@ecedi to make sure you'll do a "fresh" install
  • npm install ../gulp-stack --install-links --save-dev

You'll see in package.json that instead of "@ecedi/gulp-stack": "X.X.X" you'll have "@ecedi/gulp-stack": "file:../gulp-stack", which means it uses your local gulp-stack folder as a package. All dependencies should be installed in node_modules.

⚠ If you test other things in the project with npm install, you'll need to launch this command again, with --install-links, always at last (else the package will be remplaced by a symlink : its dependencies won't be installed in node_modules/ and the scripts won't work correctly).

Do this process as many times as you need to test new modifications !

Publish as a package

When it's ready to test/use as a "real" package :

• In the gulp-stack folder :
  • Update version number in package.json (you can test first with an alpha or beta version, ex "10.1.6-alpha")
  • Delete package-lock.json then regenerate it with npm install : to update the version number
  • Publish the package (you'll need an NPM account in ecedi team) : npm publish --access public
• In the project folder, install the new package :
  • Delete package-lock.json and node_modules to make sure you'll do a "fresh" install
  • npm install @ecedi/gulp-stack --save-dev

Once you've tested everything is OK, you'll need to do the same process to publish the package with the final version number.

Gitlab CI

There are 2 stages in the CI :

Audit

On each merge request, run NPM Audit and Depcheck, to check NPM vulnerabilities and dependencies. This suggests making all updates necessary to keep the dependencies up-to-date.

More info on :

• https://docs.npmjs.com/auditing-package-dependencies-for-security-vulnerabilities
• https://www.npmjs.com/package/depcheck

Tag

On each merge on master, offers manual jobs to release a tag according to the semver conventions (fix/minor/major). The associated release note should be automatically generated, based on the list of commit messages (to be verified).

More info on :

• https://semver.org/
• https://github.com/ecedi/git-tag-auto
• https://github.com/jk1z/GitLab-Release-Note-Generator