4.7 KiB
run-commands
Run any custom commands with Nx
Builder properties can be configured in angular.json when defining the builder, or when invoking it.
Examples
workspace.json:
//...
"frontend": {
"architect": {
//...
"ls-project-root": {
"builder": "@nrwl/workspace:run-commands",
"options": {
"commands": [
{
"command": "ls apps/frontend/src"
}
]
}
}
}
}
nx run frontend:ls-project-root
Chaining commands, interpolating args and setting the cwd
Let's say each of our workspace projects has some custom bash scripts in a scripts folder.
We want a simple way to create empty bash script files for a given project, that have the execute permissions already set.
Given that Nx knows our workspace structure, we should be able to give it a project and the name of our script, and it should take care of the rest.
The commands option accepts as many commands as you want. By default, they all run in parallel.
You can run them sequentially by setting parallel: false:
"create-script": {
"builder": "@nrwl/workspace:run-commands",
"options": {
"commands": [
{
"command": "mkdir -p scripts"
},
{
"command": "touch scripts/{args.name}.sh"
},
{
"command": "chmod +x scripts/{args.name}.sh"
}
],
"cwd": "apps/frontend",
"parallel": false
}
}
By setting the cwd option, each command will run in the apps/frontend folder.
We run the above with:
nx run frontend:create-script --args="--name=example"
Notice the --args="--name=example" syntax: we can send custom arguments that will be interpolated into our commands via {args.name}
Custom done conditions
Normally, run-commands considers the commands done when all of them have finished running. If you don't need to wait until they're all done, you can set a special string, that considers the command finished the moment the string appears in stdout or stderr:
"finish-when-ready": {
"builder": "@nrwl/workspace:run-commands",
"options": {
"commands": [
{ "command": "echo 'READY' && sleep 5 && echo 'FINISHED'" }
],
"readyWhen": "READY"
}
}
nx run frontend:finish-when-ready
The above command will finish immediately, instead of waiting for 5 seconds.
Nx Affected
The true power of run-commands comes from the fact that it runs through nx, which knows about your dependency graph. So you can run custom commands only for the projects that have been affected by a change.
We can create some configurations to generate docs, and if run using nx affected, it will only generate documentation for the projects that have been changed:
nx affected --target=generate-docs
//...
"frontend": {
"architect": {
//...
"generate-docs": {
"builder": "@nrwl/workspace:run-commands",
"options": {
"commands": [
{
"command": "npx compodoc -p apps/frontend/tsconfig.app.json"
}
]
}
}
}
},
"api": {
"architect": {
//...
"generate-docs": {
"builder": "@nrwl/workspace:run-commands",
"options": {
"commands": [
{
"command": "npx compodoc -p apps/api/tsconfig.app.json"
}
]
}
}
}
}
Properties
args
Type: string
Extra arguments. You can pass them as follows: nx run project:target --args='--wait=100'. You can then use {args.wait} syntax to interpolate them in the workspace config file. See example above
color
Default: false
Type: boolean
Use colors when showing output of command
commands
Type: array of object
command
Type: string
Command to run in child process
cwd
Type: string
Current working directory of the commands.
envFile
Type: string
You may specify a custom .env file path
outputPath
Type: string | array
Tells Nx where the files will be created
parallel
Default: true
Type: boolean
Run commands in parallel
readyWhen
Type: string
String to appear in stdout or stderr that indicates that the task is done. This option can only be used when parallel is set to true. If not specified, the task is done when all the child processes complete.