@superskrypt/npm-tasks v0.3.2

NPM TASKS

npm-tasks - build system for superskrypt projects.

Instalation

1. Run npm installation in your project folder:

yarn add -D @superskrypt/npm-tasks

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:

npm i g nps

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

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:

{
    "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:

"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/

   "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.

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:

 "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 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 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

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
PORT=3000
BROWSER='google chrome'
ROUTING=client
GIT_PASSWORD=*****
DEV_PASSWORD=*****
PROD_PASSWORD=*****

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:

nps <task-name>

Or if you want to pass arguments (task-name and arguments must be in quotes):

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

  nps "build --debug=true"
  nps "build env=prod --debug=true"

Available tasks:

• build tasks:
  • build
  • build:prod
  • build:clean
  • build:fonts
  • build:icons
  • build:html
  • build:images
  • build:css
  • build:scripts
  • build:theme
  • build:setver
• release tasks:
  • release
  • release:prompt
  • release:prompt-version - alias for release:prompt
  • release:bump-version - alias for release:prompt
  • release:clean
  • release:create
  • release:to-git
• deploy tasks:
  • deployDev
  • deployTst - alias for deployDev
  • deployProd
  • gitDev
  • gitTst - alias for gitDev
  • gitProd
  • revertDev
  • revertTst - alias for revertDev
  • revertProd
  • deploy:setDev
  • deploy:transferDev
  • deploy:transferTst - alias for deploy:transferDev
  • deploy:transferProd
• watch tasks:
  • watch

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:

  import { ImageLazyLoadingController } from 'bb-modules/lazy-loading';

  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:

  import * as Newsletter from "Newsletter/js/NewsletterController.js"