node package manager
We need your input. Help make JavaScript better: Take the 2017 JavaScript Ecosystem survey »



Wrangler for package scripts

This module is meant as an alternative to gulp watch. Most plugins for gulp already have CLI components, so it doesn't make a lot of sense to install needless dependencies to do what package scripts can already do. However, one drawback of this method is the lack of a clear-cut way to watch files and perform tasks accordingly, which is where wrangler comes in.


Wrangler's primary usage is with two commands, wrangler and run. The watch is a running process to aid in development, while run is just a sugar layer for chaining package tasks.

wrangler [scripts...]

This command watches for file changes similar to gulp watch. Additionally it runs parallel scripts necessary for development in the background. It manages the main process, as defined by the start script, as well. All triggered tasks are added to a queue system to ensure tasks are executed in the same order in which they were triggered.

This command also allows for on-demand script running via stdin. While it is running, typing any package script name will add the task to the queue. There are also several built-in commands:

  • exit - Kills and children and exits
  • pause - Toggles skipping watch events
  • start - Starts the start script, stops a previous instance if one is running
  • stop - Stops the start script, prevents it from starting again until running start, useful for running custom inspectors

run [scripts...]

This command is sugar for a long series of package scripts. It allows a command like npm run clean && npm run build to be shortened to run clean build.


This command allows to quickly build sub-projects and copy them to the local distribution. Very useful for client repos in servers. This will make a directory in <parentProject>/dist/app/<folderName>, run dist on the child project, then copy the child's dist/app to that corresponding directory.


This module is meant to work exclusively with package scripts, accordingly all configuration occurs in the package.json.

  "scripts": {
    "ava": "ava",
    "babel": "babel",
    "build": "run clean babel",
    "clean": "rm -rf dist",
    "http": "http",
    "watch": "wrangler http"
  "watch": {
    "ava": "(dist|test)/",
    "build": "lib/"

Watched Scripts

Watched scripts can be configured using the watch key, the value must be an object. Each key is the name of a package script to run, while the value is either a string or array of the globs to match. When a file within a glob is changed, the task is ran and output is piped to the watch process if there is an issue.

Globs are based on node-glob, with some exceptions. Multiple globs are allowed, and may work together. An example of this would be ["*.js", "!dist.js"], which would match all js files except for dist.js. Additionally, there is a shortcut for directory matching, anything ending with a slash, like dist/ is transformed to dist/**/*.

start is a special case meant for long running processes, such as servers. If there is a start watch defined, the process will start immediately and run in parallel. The process will be restarted if the watch event is triggered.

Parallel Scripts

Parallel tasks are defined as arguments to the wrangler command and are run immediately in parallel with watched tasks. This is good for things like http servers that need to be ran whilst programming. An example of multiple parallel tasks would be wrangler http gulp browserify where each argument is the name of a package script and is separated by spaces.