node package manager



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 Code Coverage Dependencies version downloads MIT License

All Contributors PRs Welcome Donate Code of Conduct Roadmap Examples

Quick Video Intro ūüďļ

Video Screenshot

Pull out npm scripts into another file with nps by Elijah Manor (5:53)

The problem

Even though npm scripts have a ton of advantages (learn more), it can grow into an unmaintainable 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: 
      default: 'jest',
      watch: {
        script: 'jest --watch',
        description: 'run in the amazingly intelligent Jest watch mode'
    build: {
      // learn more about Webpack here: 
      default: 'webpack',
      prod: 'webpack -p',
    // learn more about npsUtils here: 
    validate: npsUtils.concurrently.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:

    default: node index.js
    lint: eslint .
        # learn more about Jest here:
        default: jest
            script: jest --watch
            description: run in the amazingly intelligent Jest watch mode
        default: webpack
        prod: webpack -p
    validate: concurrently "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>...
  init        automatically migrate from npm scripts to nps
  completion  generate bash completion script
  --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
  -h, --help       Show help                                           [boolean]
  -v, --version    Show version number                                 [boolean]
  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"
Available scripts (camel or kebab case accepted)
lint - eslint .
test - jest - run in the amazingly intelligent Jest watch mode - jest --watch
build - webpack - webpack -p
validate - concurrently "nps lint" "nps test" "nps build"

Now, to run a script, you can run:

nps lint
# etc.

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

nps b # will run 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.

Also check out the 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:


  "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.


This module is distributed via npm which is bundled with 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


./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.





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


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

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.

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.

-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.


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

That's all for the CLI.


Remember, this file is JavaScript, so you can write functions to make things more simple! See other/ for examples of cool things you can do with this.

nps expects to your package-scripts.js file to module.exports an object with the following properties:


This can be an object or a function that returns an object. See the annotated example below for what this object can look like (and different ways to run them):

module.exports = {
  scripts: {
    default: 'echo "This runs on `nps`"', // nps 
    // you can assign a script property to a string 
    simple: 'echo "this is easy"', // nps simple 
    // you can specify whether some scripts should be excluded from the help list 
    hidden: {
      script: 'debugging script',
      hiddenFromHelp: true,
    test: {
      default: {
        script: 'jest', // nps test 
        description: 'Run tests with jest',
        // your scripts will be run with node_modules/.bin in the PATH, so you can use locally installed packages. 
        // this is done in a cross-platform way, so your scripts will work on Mac and Windows :) 
        // NOTE: if you need to set environment variables, I recommend you check out the cross-env package, which works 
        // great with nps 
      otherStuff: {
        // this one can be executed two different ways: 
        // 1. nps test.otherStuff 
        // 2. nps test.other-stuff 
        script: 'echo "testing other things"',
        description: 'this is a handy description',
    // this one can be executed a few different ways: 
    // 1. nps k 
    // 2. nps kebab-case 
    // 3. nps kebabCase 
    'kebab-case': 'echo "kebab-case"',
    series: 'nps simple,test,kebabCase', // runs these other scripts in series 
nps k # runs nps kebab-case


This object is used to configure nps with the following options:


Setting this to true will prevent nps from outputting anything for your script (normally you'll get simple output indicating the command that's being executed). This effectively sets the logLevel to disable.


This sets the logLevel of nps.

ENV variables


By setting LOG_LEVEL environment variable you can control the log level for nps

Log level

Log levels available:

  • error - errors only
  • warn - errors and warnings only
  • info - info, errors, and warnings (default)


How do I do ___ ?

Have you looked at the examples in other/

Why npm start?

Just to be clear: You do not have to use the start script. You can use whatever you like. But I recommend using the start. npm scripts are generally run with npm run <script-name>. There are some exceptions to this. For example:

  1. npm run test === npm test === npm t
  2. npm run start === npm start

So, while you could use a script called script and run npm run script build, I just think it reads more clearly to just use the start script and run npm start build. It's also nice that it's fewer things to type. You could also use the test script and then type even less: npm t build, but thats just... odd.

Note, often servers are configured to run npm start by default to start the server. To allow for this case, you can provide a default script at the root of your scripts which will be run when npm start is run without any arguments. Effectively this will allow you to have a script run when npm start is executed.


This was inspired by a tweet by @sindresorhus.


Big thank you to @tmpvar for giving up the name nps! The original nps is now called npmsearch-cli.

Related Packages

  • nps-utils - a collection of utilities to make cross-platform scripts and many other patterns (like running concurrent/parallel scripts)

Other Solutions

  • scripty has a solution for this problem as well. The reason I didn't go with that though is you still need a line for every script (one of the pains I'm trying to solve) and a each script requires its own file (one of the benefits of npm scripts I wanted to keep).
  • nabs is a compiler that turns a nicely structured YAML file into script entries in your package.json


What happened to p-s?

This project is p-s! It was just renamed during a major version bump. There were a few breaking changes for this to happen and those are documented on the releases page.


Thanks goes to these people (emoji key):

Kent C. Dodds

ūüíĽ ūüďĖ ūüöá ūüí° ūüďĻ ūüĎÄ

David Wells


Abhishek Shende

ūüíĽ ‚ö†ÔłŹ

Rowan Oulton

ūüíĽ ūüďĖ ‚ö†ÔłŹ

Gilad Goldberg


Tim McGee

ūüíĽ ūüďĖ

Nik Butenko

ūüí° ūüíĽ


ūüźõ ūüíĽ ‚ö†ÔłŹ ūüĎÄ

Jayson Harshbarger

ūüí° ūüĎÄ

JD Isaacks

ūüíĽ ‚ö†ÔłŹ

Christopher Hiller


Robin Malfait


Eric McCormick

ūüĎÄ ūüďĖ

Sam Verschueren


Sorin Muntean

ūüíĽ ‚ö†ÔłŹ ūüďĖ

Keith Gunn

ūüźõ ūüíĽ ‚ö†ÔłŹ

Joe Martella

ūüźõ ūüíĽ ‚ö†ÔłŹ

Martin Segado


Bram Borggreve

ūüźõ ūüíĽ

Elijah Manor


Ragu Ramaswamy

ūüíĽ ‚ö†ÔłŹ ūüźõ

Erik Fox


Aditya Pratap Singh



ūüíĽ ūüďĖ

Islam Attrash




Nate Cavanaugh


This project follows the all-contributors specification. Contributions of any kind welcome!