npm-tasks
- build system for superskrypt projects.
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
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"]
}
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 serverTODO: 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
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 |
- 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 leastwp-backend-base
with commit hash#c7e5eac
. - delete options
BACKEND_BASE_JS_PATH
andBACKEND_BASE_SCSS_MODULES_PATH
If you are using legacy version <= 0.2.4, in order to successfully build project (js, scss files)
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"
-
--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, thenbabel
andwebpack
will be display more information about compilation.Examples
nps "build --debug=true" nps "build env=prod --debug=true"
- build tasks:
-
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:
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.
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"