npm package: @superskrypt/npm-tasks
Description: Set of npm tasks for development
Author: Superskrypt
Latest version: 0.3.7

# NPM TASKS

`npm-tasks` - build system for superskrypt projects. 

## Instalation
---
**1. Run `npm` installation in your project folder:**
```console
yarn add -D @superskrypt/npm-tasks
```
```console
npm install --save-dev @superskrypt/npm-tasks
```
ATTENTION! For some reasons in node > 15 `npm install` does't install all dependencies for `npm-tasks`  
 
## Configuration
---

**1. Install `nps` package globaly:**

```console
npm i g nps
```

**2. Put `package-scripts.js` in the project root folder and add content:**

```js
module.exports = require('@superskrypt/npm-tasks');  // put this in package-scripts.js file
```  

**3. Create `config.json` file with defined configuration for deployment, scss compiler and webpack options.**

Example:  
`config.json`:

```json
{
    "webpack_includes": [],
    "custom_js_libs_folder": ["vendors"],
    "webpack_provide_plugin": {"Buffer": ["buffer", "Buffer"] },
    "envs": {
        "tst": {
            "protocol": "ssh",
            "host": "domain",
            "user": "user_name",
            "path": "path/to/remote/folder/",
            "backup_limit": 3
        },
        "prod": {
            "protocol": "ftp",
            "host": "ip_server_address",
            "user": "user_name",
            "path": "path/to/remote/folder/",
            "backup_limit": 0
        }
    },
    "versioned": [
        "path/to/file/in/build/folder"
    ],
    "watchers": {
        "custom": {
            "customWatcherName": ["path/to/files", "command task", true]
        }
    },
    "scss_files_disabled_for_backend_base_imports": ["admin"]
}
```   
### _`config.json`_ fields:  
_`webpack_includes`_ - **Array (optional)**, paths to all libraries you want to include to the build.  
  
Example:  
```json
"webpack_includes": ["./node_modules/@superskrypt/sutils","./node_modules/scrollmagic-plugin-gsap"]
```
_`webpack_provide_plugin`_ - **Object (optional)** , add libraries to load them automatically. See more: https://webpack.js.org/plugins/provide-plugin/  
```json
   "webpack_provide_plugin": {"Buffer": ["buffer", "Buffer"] }
```
  
Example:  
_`process_images`_ - **Boolean (optional)** - If set to `true` then images from folder `project_root/src/images` will be compressed.  
_`target_browsers`_ - **Array (optional)** - overrides default target browsers in babel configuration. Format  must be compatible with [browserslist](https://github.com/browserslist/browserslist).  

_`custom_js_libs_folder`_ - **Array|String (optional)** - specify folder name or list of folder names for custom js libraries. If you set this property then whole folder/s and it's content will be copy to destination js folder. This property may be useful with legacy superskrypt projects where external libraries were included by script tag and hosted on subfolder e.g. `js/vendors/gsap.min.js`  

_`copy_paths`_ - **Array (optional)** - specify additional folders/file paths which needs to be copy to build folder. Paths **MUST BE RELATIVE** and needs to be located in `src` folder.  
**!NOTE**: By default all `json` files from the first level of `src` folder are copied to the build folder.  
Example:  
```json
 "copy_paths": ["sounds", "documents/excel", "custom_file.txt"]
```

_`envs`_ -  **Object (required)** with contains configuration for deployment. Must contain two properties  
* _`tst`_ - for development eviroment  
* _`prod`_ - for production enviroment  

Both `tst` and `prod` properties have the same schema:  
* _`protocol`_ - (optional) either ftp or ssh(default)  
* _`host`_ - ip or domain of remote serwer  
* _`user`_ - user  
* _`path`_ - path to folder on remote server where you want to deploy your project  
* _`backup_limit`_ - maximum number of backup copies on server `TODO: implement it`  

_`versioned`_ - **Array (optional)** - list of files to be processed to replace `$VERSION$` placeholder with current version (see [setver][build-setver] for more details).

_`watchers`_ - **Object (optional)** - list of watchers used by browser-sync based task, `watch`. You can overwrite default or create own custom watchers (see [watch][watch-task] for more details).  
_`scss_files_disabled_for_backend_base_imports` – list of files, which needs to be skipped when default scss imports from wp-backend-base are being applied. By default this mechanism, when BACKEND_BASE_SCSS_MODULES_PATH option is set, in .env file (see below), will be pasting scss imports of default styles from wp-backend-base to every scss file (from the first level). If a file name is present in scss_files_disabled_for_backend_base_imports option, this means that this mechanism will be skipped for that file.

**4. create `.env` file and put it in the root of project. `This is your local file and should be added to .gitignore`**
```txt
DEV_PROXY=local_domain.dv
BUILD_PATH=/path/to/build/folder/on/the/local/machine
BACKEND_BASE_JS_PATH=/path/to/backend-base/js/folder
BACKEND_BASE_SCSS_MODULES_PATH=/path/to/backend-base/scss/file-with-imports-to-include
SCSS_CUSTOM_LOAD_PATHS=/path/to/folder/with/additional/scss/files
PORT=3000
BROWSER='google chrome'
ROUTING=client
GIT_PASSWORD=*****
DEV_PASSWORD=*****
PROD_PASSWORD=*****
```


| Option                 | Description                              |
|------------------------|------------------------------------------------------------------|
| `DEV_PROXY`            | domain assigned to current project for testing on local machine                                                                                                      |
| `BUILD_PATH`           | absolute path on local machine to place build into                                                                                                                   |
| `BACKEND_PATH`           | absolute path on local machine to plugin witch holds wp-backed-base installation (in vendor folder)                                                                                                                   |
| `SCSS_CUSTOM_LOAD_PATHS` | Path to custom scss imports folder eg. parent theme. Useful when working with child theme and you want to use some of variables, mixinis, or functions from parent theme.
| `BACKEND_BASE_JS_PATH` | **(Legacy, available up to v0.2.4. – see options migration guide bellow)** Absolute path on local machine pointing folder with javascript files in backend base. Allow to use backend base js in project. |
| `BACKEND_BASE_SCSS_MODULES_PATH` | **(Legacy, available up to v0.2.4. – see options migration guide bellow)** Absolute path on local machine pointing folder with file scss file witch imports to include in base scss file (from theme or plugin). These imports (eg.: `@import "_partials/4_blocks/card.scss"`) are inserting at the beginning of base scss file. |
| `PORT` | add port number for development (default is 3000)  |
| `BROWSER` | add browser name for browser-sync (`watch` task default browser is `'google chrome'`)  |
| `ROUTING` | set `ROUTING` to `'client'` when using client-routers (see `browsersync options: single`)   |
| `GIT_PASSWORD` | password for git commands. If not provided here, you will be prompted each time it is required  |
| `DEV_PASSWORD` | password for deployment on developement server. If not provided here, you will be prompted each time it is required  |
| `PROD_PASSWORD` | password for deployment on production server. If not provided here, you will be prompted each time it is required |

### OPTIONS MIGRATION GUIDE: 
 
#### Version v.0.2.5

 - in .env file add `BACKEND_PATH` option and paste absolute path to backend plugin, where you have installed wp-backend-base package. Note that you need at least `wp-backend-base` with commit hash `#c7e5eac`.   
 - delete options `BACKEND_BASE_JS_PATH` and `BACKEND_BASE_SCSS_MODULES_PATH`  

If you are using legacy version <= 0.2.4, in order to successfully build project (js, scss files)


## Run  

Basic command:
```console
nps <task-name>
```
Or if you want to pass arguments **(`task-name` and `arguments` must be in quotes)**:
```console
nps "<task-name> --env=dev"
```
## Available command line arguments:

* **_--env=[dev|prod]_** - when flag `--env=prod` is set then all tasks works in production mode e.g source-maps are off, js code is minify etc.
* **_--debug=[true|false]_** - when `true` is set, then `babel` and `webpack` will be display more information about compilation.
  
  Examples
  ```console
  nps "build --debug=true"
  nps "build env=prod --debug=true"
  ```


## Available tasks:
* **build tasks**:
    * [build][build-task]
    * [build:prod][build-prod]  
    * [build:clean][build-clean]  
    * [build:fonts][build-fonts]  
    * [build:icons][build-icons]   
    * [build:html][build-html] 
    * [build:images][build-images]   
    * [build:css][build-css]  
    * [build:scripts][build-scripts]  
    * [build:theme][build-theme]  
    * [build:setver][build-setver]  
* **release tasks**:
    * [release][release-task]
    * [release:prompt][release-prompt]
    * [release:prompt-version][release-prompt] - `alias for release:prompt`
    * [release:bump-version][release-prompt] - `alias for release:prompt`
    * [release:clean][release-clean]
    * [release:create][release-create]
    * [release:to-git][release-to-git]
* **deploy tasks**:
    * [deployDev][deploydev]
    * [deployTst][deploydev] - `alias for deployDev`
    * [deployProd][deployprod]
    * [gitDev][gitdev]
    * [gitTst][gitdev] - `alias for gitDev`
    * [gitProd][gitprod]
    * [revertDev][revertdev]
    * [revertTst][revertdev] - `alias for revertDev`
    * [revertProd][revertprod]
    * [deploy:setDev][deploy-setdev]
    * [deploy:transferDev][deploy-transferdev]
    * [deploy:transferTst][deploy-transferdev] - `alias for deploy:transferDev`
    * [deploy:transferProd][deploy-transferprod]
* **watch tasks**:
    * [watch][watch-task]


[build-task]: docs/build.md 
[build-prod]: docs/build.md
[build-clean]: docs/clean.md
[build-fonts]: docs/fonts.md
[build-icons]: docs/icons.md
[build-html]: docs/html.md
[build-images]: docs/images.md
[build-css]: docs/styles.md
[build-scripts]: docs/scripts.md
[build-theme]: docs/theme.md
[build-setver]: docs/setver.md
[release-task]: docs/release.md
[release-prompt]: docs/release_prompt.md
[release-clean]: docs/release_clean.md
[release-create]: docs/release_create.md
[release-to-git]: docs/release_to_git.md
[deploydev]: docs/deploydev.md
[deployprod]: docs/deployprod.md
[gitdev]: docs/gitdev.md
[gitprod]: docs/gitprod.md
[revertdev]: docs/revertdev.md
[revertprod]: docs/revertprod.md
[deploy-setdev]: docs/deploy_setdev_.md
[deploy-transferdev]: docs/transfer.md
[deploy-transferprod]: docs/transfer.md
[watch-task]: docs/watch.md

## Wp Backed Base integration

Since `v.0.2.5` npm-tasks have better integration with `superskrypt/wp-backend-base`. Main functionalities are:

 - access to wp-backend-base configuration file, witch holds for example enabled modules. This configuration file, `backend-base-config.json` lays in plugin or theme witch holds wp-backend-base installation (in vendor folder)
 - ability to gather and compile project scss files with **default core wp-backend-base styles files** and **enabled modules style files** eg. *Newsletter* . 
 - scss imports are ordered in the way, that local project styles wins
 - ability to compile javascript code imported from wp-backend-base core modules or modules.

 ### Import wp-backend-base javascript files to local project

 If you want to use some of wp-backend-base js files, for example `SpaController` , `accessibility functions` or `lazy loading functionality`, you need import them like this:
 ```javascript
import { ImageLazyLoadingController } from 'bb-modules/lazy-loading';
 ```
 ```javascript
import { AutoCardsFiltersController } from 'bb-modules/frontend-filters';
 ```  

 If you want use some of wp-backend-base modules javascript files, for example `Newsletter`, you need import them like that:
 ```javascript
import * as Newsletter from "Newsletter/js/NewsletterController.js"
 ```