Getting Started

Check for Node and NPM

Make sure that you've installed Node and NPM before attempting to install gulp (supports gulp 4.x.x).
For gulp 3.x.x use ~1.4.0 version.

node -v
npm -v

Install Gulp globally

npm i -g gulp

Project integration

Composer

1. Add the repository's path to the composer.json

"repositories": [
    {
      "type": "github",
      "url": "https://github.com/magepro-dev/magento-2-gulp"
    }
]

2. Run

composer require --dev magepro-dev/magento-2-gulp

3. Rename the following files in your project root directory:
   package.json.example to package.json
4. Install modules listed as dependencies in the package.json:

npm i

or

yarn

Manually

1. Copy source files to your project dir.
2. Rename the following files in your project dir:
   package.json.example to package.json
3. Install modules listed as dependencies in the package.json:

npm i

or

yarn

Configuration

Copy the content of themes.js into the local-themes.js and add your theme configuration in the dev/tools/grunt/configs/ directory.

module.exports = {
    ...
    <Theme>: {
        area: 'frontend|adminhtml',
        name: '<Vendor>/<Theme>',
        locale: locale,
        files: [
            'css/styles-m',
            'css/styles-l',
        ],
        dsl: 'less'
    }
    ...
}

Example:

module.exports = {
    ...
    themeName: {
        area: 'frontend',
        name: 'Package/themeName',
        locale: 'en_US',
        files: [
            'css/styles-m',
            'css/styles-l'
        ],
        dsl: 'less'
    }
    ...
}

How to use

In a project root dir run gulp [command] --[themeName] --[argument]

Available commands:

Command	Arguments	Description
help		Display this help message
clean	--themeName	Remove cached files (pub/static/**, var/**)
exec	--themeName	Republishes symlinks to the source files
less	--themeName	Compile LESS to CSS
watch	--themeName	Watch for *.less files
	--themeName --docker	Watch for *.less files in a docker container

See commands:

gulp help

Compile styles:

gulp clean --themeName && gulp exec --themeName && gulp less --themeName

Run watcher:

gulp watch --themeName
gulp watch --themeName --docker

The argument --docker enables the option usePolling: true for the gulp watcher. Read more here.

Scripts

See short scripts in the package.json.example.

Example:

"gulp": "gulp clean --themeName && gulp exec --themeName && gulp less --themeName && gulp watch --themeName"
"gulp:docker": "gulp clean --themeName && gulp exec --themeName && gulp less --themeName && gulp watch --themeName --docker"

Run the script:

npm run [scriptName]

or

yarn [scriptName]

Example:

npm run gulp
npm run gulp:docker

Note:

themeName is a key of exported object in the file:

dev/tools/grunt/configs/local-themes.js

Replace it everywhere for npm scripts.