Sponsorship

NPS is being sponsored by the following tool; please help to support us by taking a look and signing up for a free trial.

<a href="https://tracking.gitads.io/?repo=nps"><img src="https://images.gitads.io/nps" alt="GitAds"/></a>

nps

All the benefits of npm scripts without the cost of a bloated package.json and limits of json

nps is short for npm-package-scripts

What happened to p-s?

[![Build Status][build-badge]][build] [![Code Coverage][coverage-badge]][coverage] [![Dependencies][dependencyci-badge]][dependencyci] [![version][version-badge]][package] [![downloads][downloads-badge]][npm-stat] [![MIT License][license-badge]][license]

[![PRs Welcome][prs-badge]][prs] [![Donate][donate-badge]][donate] [![Code of Conduct][coc-badge]][coc] [![Roadmap][roadmap-badge]][roadmap] [![Examples][examples-badge]][examples] ![nps friendly][nps-badge]

The problem

Even though npm scripts have a ton of advantages ([learn more][scripts-advantages]), it can grow into an [unmaintainable mess][mess] in your package.json file. Part of the problem is we're configuring scripts in json which has fundamental issues (like no comments).

This solution

nps is a package that solves this problem by allowing you to move your scripts to a package-scripts.js file. Because this file is a JavaScript file, you can do a lot more with your project scripts. Here's an example of a package-scripts.js file:

const npsUtils = require("nps-utils"); // not required, but handy!

module.exports = {
  scripts: {
    default: "node index.js",
    lint: "eslint .",
    test: {
      // learn more about Jest here: https://facebook.github.io/jest
      default: "jest",
      watch: {
        script: "jest --watch",
        description: "run in the amazingly intelligent Jest watch mode"
      }
    },
    build: {
      // learn more about Webpack here: https://webpack.js.org/
      default: "webpack",
      prod: "webpack -p"
    },
    // learn more about npsUtils here: https://npm.im/nps-utils
    validate: npsUtils.concurrent.nps("lint", "test", "build")
  }
};

Or in case you prefer YAML, here's an example of how that would look in a package-scripts.yml file:

scripts:
  default: node index.js
  lint: eslint .
  test:
    # learn more about Jest here: https://kcd.im/egghead-jest
    default: jest
    watch:
      script: jest --watch
      description: run in the amazingly intelligent Jest watch mode
  build:
    default: webpack
    prod: webpack -p
  validate: concurrent "nps lint" "nps test" "nps build"

To use nps, it's recommended that you either install it globally (npm i -g nps) or add ./node_modules/bin to your $PATH (be careful that you know what you're doing when doing this, find out how here).

Then you can run:

nps help

Which will output:

Usage: nps [options] <script>...

Commands:
  init        automatically migrate from npm scripts to nps
  completion  generate bash completion script

Options:
  --config, -c      Config file to use (defaults to nearest package-scripts.yml
                    or package-scripts.js)
                      [default: "<path-to-your-project>/package-scripts.js"]
  --silent, -s      Silent nps output                  [boolean] [default: false]
  --log-level, -l   The log level to use
                    [choices: "error", "warn", "info", "debug"] [default: "info"]
  --require, -r     Module to preload
  --prefix, -p      Prefix for each <script> name
  -h, --help        Show help                                           [boolean]
  -v, --version     Show version number                                 [boolean]
  --help-style, -y  Style of help to use
                    [choices: "all", "scripts", "basic"] [default: "all"]

Examples:
  nps.js test build                         Runs the `test` script then the
                                            `build` script
  nps.js "test --cover" "build --prod"      Runs the `test` script and forwards
                                            the "--cover" flag then the `build`
                                            script and forwards the "--prod"
                                            flag
  nps.js --prefix=test unit functional      Runs the `test.unit` script then
                                            the `test.functional` script

Available scripts (camel or kebab case accepted)

lint - eslint .
test - jest
test.watch - run in the amazingly intelligent Jest watch mode - jest --watch
build - webpack
build.prod - webpack -p
validate - concurrent "nps lint" "nps test" "nps build"

You can also use the help command with a script name

nps help test.watch

Which will output the details of the script test.watch:

test.watch - run in the amazingly intelligent Jest watch mode - jest --watch

Now, to run a script, you can run:

nps lint
nps test.watch
# etc.

But the fun doesn't end there! You can use a prefix:

nps b # will run the build script
nps help b # will display help for the build script

And these prefixes can go as deep as you like!

nps b.p # will run the production build script

Cool stuff right? And there's more on [the roadmap][roadmap].

Also check out the [examples][examples]. You'll find some good stuff in there (including how to deal with windows and other cross-platform issues).

Note: If you don't like installing things globally and don't want to muck with your $PATH (or don't want to require that your co-workers or project contributors to do so), then you can add a single script to your package.json. We recommend that you use the start script because it requires less typing:

package.json

{
  "scripts": {
    "start": "nps"
  }
}

You don't have to use the start script if you don't want. Note that if you're writing a node application, you're likely using start for starting your server. In that case, you can create a default script which will be run when nps is run without arguments (so effectively it'll work just the same). But if you'd prefer, you can use whatever you wish. For example you could easily create a nps script and do: npm run nps b.

Installation

This module is distributed via [npm][npm] which is bundled with [node][node] and should be installed as one of your project's devDependencies:

npm install --save-dev nps

global installation

You can install this module globally also (this is recommended):

npm install --global nps

From here you can use nps on the command line via one of the installed aliases: nps or nps.

If you do this, you may also be interested in installing the shell autocompletion script. See more about this below.

Getting started

If you're already using npm scripts, you can get up and going really quickly with the init command:

./node_modules/.bin/nps init

or

./node_modules/.bin/nps init --type yml

This will use your package.json scripts to generate a package-scripts.js (respectively a package-scripts.yml) file and update your scripts to utilize the nps binary.

API

CLI

Commands

help

If you have a help script, then your help script will be run. Otherwise, this will output the help.

Note: you can do this with nps --help, but if you're using the start script in your package.json this allows you to run npm start help rather than npm start -- --help

init

As indicated above, this will migrate your npm scripts to package-scripts.

completion

nps completion >> <your-bash-profile-file>

Normally <your-bash-profile-file> will be ~/.bash_profile, ~/.bashrc, or ~/.zshrc.

Note: you should probably only do this if you have the package installed globally. In that case you should probably also normally use the nps alias rather than nps because it's easier to type.

Note: for zsh support, you must enable zsh's bash completion script compatibility mode.

CLI options

-h, --help

Will print out the help you see above (the available scripts are colored 🌈 and come from the config specified/default config).

-s, --silent

By default, nps will log out to the console before running the command. You can add -s to your command to silence this.

--no-scripts

By default, the script's command text will log out to the console before running the command. You can add --no-scripts to prevent this.

-c, --config

Use a different config

nps -c ./other/package-scripts.js lint

Normally, nps will look for a package-scripts.js file and load that to get the scripts. Generally you'll want to have this at the root of your project (next to the package.json). But by specifying -c or --config, nps will use that file instead.

-l, --log-level

Specify the log level to use

-r, --require

You can specify a module which will be loaded before the config file is loaded. This allows you to preload for example babel-register so you can use all babel presets you like.

scripts

To run a script, you simply provide the name of the script like so:

nps cover

And you can run multiple scripts in series by simply adding more space-separated arguments.

nps cover check-coverage

And you can pass arguments to scripts by putting the scripts in quotes:

nps "test --cover" check-coverage

-y, --help-style

By default, nps will dump a very long help documentation to the screen based on your package-scripts.js file. You can modify this output with one of three help-style options:

all gives you the normal default output: