js-build-tasks
v1.0.0-rc.18
Published
A library for running build tasks and scripts for nodejs
Downloads
21
Maintainers
Readme
Js build tasks
A library for running build tasks and scripts for nodejs
Contents
Example
# tasks.yml example
extends: ./build/docker.tasks.yml # optional
log: # optional
filePath: ./output.log
logLevel: step
tasks: # required
clean: rimraf ./out ./dist .artifacts
compile: [clean, tsc]
Install
As a global tool
To run tasks directly in the terminal install globally
npm install -g js-build-tasks
run directly in the terminal
task clean compile
As a dev package
To run tasks using package.json scripts install as dev dependency
npm install -save-dev js-build-tasks
Run via package.json scripts
// package.json
{
"scripts": {
"clean": "task",
"compile": "task",
"test": "task"
}
}
Tasks file parameters
# optional: extends tasks and options from other tasks files.
# type: string | string[]
extends: <relative-file-path>
# optional: shell options
shell:
# optional: type of shell output
# type: string
# - tty (default)
# - plain
# [extends]: overrides extended files
mode: <tty|plain>
# optional: output log level
# type: string
# - step: prints step info, command output and errors (default)
# - command: prints command output and errors
# - error: prints errors only
# - silent: no output is printed
# [extends]: overrides extended files
logLevel: <step|command|error|silent>
log:
# optional: log file path
# type: string
# - auto creates it's dir(s) if they don't exist
# - strips ansi escape codes from output
# - enforces shell mode '-sm plain'
# [extends]: overrides extended files
filePath: <relative-file-path>
# optional: file log level
# type: string
# - step: writes step info, command output and errors (default)
# - command: writes command output and errors
# - error: writes errors only
# [extends]: overrides extended files
logLevel: <step|command|error>
# optional: output options
output:
# optional: when true, will print a nested number format e.g. 1.1.1
# type: boolean
# useful for tracing more complex task group steps
# [extends]: overrides extended files
nestedSteps: <true|false>
# optional: disables the task start time in the 'step info' printed in the output
# type: string
# [extends]: overrides extended files
disableTaskTime: <true|false>
# optional: style 'step' and 'error' logging printed to the output
# type: string[] (See valid styles below)
# NOTE doesn't apply to the command output
# [extends]: overrides extended files
style:
step: []
error: [red]
# optional: env(s) available to all tasks
# type: [key: string]: string | boolean | number
# - .node_modules/.bin is automatically added to the $PATH to allow local bin execution
# - expands $ expressions e.g. $PATH: "$PATH:./my/path" will append './my/path' to $PATH
# - shell specific
# - bash|sh: env is placed on to the command line as is. e.g. echo $env
# - cmd.exe: '$MY_ENV' is transformed to '%MY_ENV%' on the command line
# - powershell.exe|pwsh.exe: '$MY_ENV' is transformed to '${env:MY_ENV}' on the command line
# - windows: $PATH env sanitizing e.g. './bin/path1:./bin/path2' becomes '.\bin\path1;.\bin\path2'
# [extends]: mixed in with extended files or overrides if matching the same name
env: { MY_ENV: 1 } # usage echo $MY_ENV or echo ${MY_ENV}
# optional: var(s) available to all tasks (never put into env)
# type: [key: string]: string | boolean | number
# variables are expanded on to the command line e.g. 'echo $MY_VAR' becomes 'echo var value'
# [extends]: mixed in with extended files or overrides if matching the same name
var: { MY_VAR: var value } # usage echo $MY_VAR or echo ${MY_VAR}
# optional: array of 'env' and\or 'var' names to mask in the printed output.
# type: string[]
# e.g. this prevents any command line errors printing sensitive values into the output.
# NOTE: if you trust the command your using then you probably won't need this
# enforces shell mode '-sm plain'
# [extends]: mixed in with extended files
mask: [MY_ENV, MY_VAR, ...]
# required
# type: [key: string]: string | string[]
# [extends]: mixed in with extended files or overrides if matching the same name
tasks:
# direct statements
clean: rimraf ./out ./dist
# group statements (yaml array)
compile: [clean, tsc]
test: [echo $MODE, compile, node ./out/test/runner.js]
# scope `env` or `var`
# NOTE: overrides global entries that have the same <param> name within the task group scope
test:dev:
- env: { MODE: dev }
- env.file: ./some/path/.env # optionally load env from a file into the scope
- test # scoped env is available to all child tasks
- echo exit scope # $MODE=dev won't be set in parent tasks
# scope `repeat`
# repeats commands after the repeat statement
# NOTE: will repeat the `product` of multiple arrays
test:build:
- repeat:
# type: [key: string]: Array<string | boolean | number>
# NOTE: keys are treated as `var` per iteration
CODE_NAME: [bookworm, bullseye, buster]
- echo $CODE_NAME # will be executed x times based on the array product of the repeat
# package scripts
# The following example: package.json must contain { "scripts": { "prepublishOnly": "task" } }
# NOTE: the packageManager field in the package.json is used to execute the task
# default is 'npm'
prepublishOnly: test
Command line options
Cli switches override global settings in the tasks file
Tasks
<tasknames> [-- args]
task(s) that will be run. e.g.
task clean compile
optional args can be appended to the end of the command line. e.g
task clean -- ./out
NOTE args will be applied to the last command that is executed
Version
--version
prints the cli version e.g.
task --version
Help
--help
prints the cli switch usage and options e.g.
task --help
List tasks
--list-tasks|-ls
prints the tasks available
task -ls
can be combined with the -tf switch
Task file
--tasks-file|-tf <path>
relative path to the tasks yaml file based on the cwd. default is ./tasks.yml
Shell mode
--shell-mode|-sm <mode>
tty
(default)plain
Shell log level
--log-level|-l <level>
step
shows step info, command output and errors (default)command
shows command output and errorserror
shows command errors onlysilent
silent output
Log file
--log-file|-lf <path>
relative path to a log file based on the cwd
- auto creates it's dir(s) if they don't exist
- strips ansi escape codes from output
- enforces shell mode '-sm plain'
Log file level
--log-file-level|-lfl <level>
step
writes step info, command output and errors (default)command
writes command output and errorserror
writes command errors only
Env file
--env-file|-ef <path>
relative path to an env file based on the cwd
Env
--env|-e <param=value>
env $ expressions available to all tasks e.g.
-e TEST=true -e OTHER=1
Var
--var|-v <param=value>
var $ expressions available to all tasks e.g.
-v TEST=true -v OTHER=1
Output nested step numbering
--output-nested-steps|-ons
output nested step numbering e.g.
> 1.1
Style disable
--style-disable|-sd
disable styles
Style step
--style-step|-ss <style>
style step info e.g.
-ss yellowBright -ss bold
Style error
--style-error|-se <style>
style errors e.g.
-se yellowBright -se bold
Styles available:
Uses nodejs text styles
'bgBlack', 'bgBlue', 'bgBlueBright', 'bgCyan', 'bgCyanBright', 'bgGray', 'bgGreen', 'bgGreenBright', 'bgMagenta', 'bgMagentaBright', 'bgRed', 'bgRedBright', 'bgWhite', 'bgWhiteBright', 'bgYellow', 'bgYellowBright', 'black', 'blink', 'blue', 'blueBright', 'bold', 'cyan', 'cyanBright', 'dim', 'doubleunderline', 'framed', 'gray', 'green', 'greenBright', 'hidden', 'inverse', 'italic', 'magenta', 'magentaBright', 'overlined', 'red', 'redBright', 'reset', 'strikethrough', 'underline', 'white', 'whiteBright', 'yellow', 'yellowBright'