Repository files navigation

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

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

nps is short fornpm-package-scripts

What happened to p-s?

Even though npm scripts have a ton of advantages (learn more), it can grow into anunmaintainable mess in yourpackage.json file. Part of the problem is we're configuring scripts injsonwhich has fundamental issues (like no comments).

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

constnpsUtils=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/jestdefault:"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-utilsvalidate:npsUtils.concurrent.nps("lint","test","build")}};

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

scripts:default:node index.jslint:eslint .test:# learn more about Jest here: https://kcd.im/egghead-jestdefault:jestwatch:script:jest --watchdescription:run in the amazingly intelligent Jest watch modebuild:default:webpackprod:webpack -pvalidate:concurrent "nps lint" "nps test" "nps build"

To usenps, 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 howhere).

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 scriptOptions:  --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` scriptAvailable scripts (camel or kebab case accepted)lint - eslint .test - jesttest.watch - run in the amazingly intelligent Jest watch mode - jest --watchbuild - webpackbuild.prod - webpack -pvalidate - 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 scripttest.watch:

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

Now, to run a script, you can run:

nps lintnps test.watch#etc.

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

nps b # will run the build scriptnps 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 onthe roadmap.

Also check out theexamples. You'll find some good stuff in there (including how to deal with windowsand 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 torequire that your co-workers or project contributors to do so), then you can add a single script to yourpackage.json.We recommend that you use thestart script because it requires less typing:

package.json

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

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

This module is distributed vianpm which is bundled withnode and shouldbe installed as one of your project'sdevDependencies:

npm install --save-dev nps

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

npm install --global nps

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

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

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

./node_modules/.bin/nps init

or

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

This will use yourpackage.jsonscripts to generate apackage-scripts.js (respectively apackage-scripts.yml)file and update yourscripts to utilize thenps binary.

If you have ahelp script, then yourhelp script will be run. Otherwise, this will output the help.

Note: you can do this withnps --help, but if you're using thestart script in yourpackage.json this allows youto runnpm start help rather thannpm 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 alsonormally use thenps alias rather thannps because it's easier to type.

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

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

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

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.

Use a different config

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

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

Specify the log level to use

You can specify a module which will be loaded before the config file is loaded. This allows you to preload for examplebabel-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

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:

nps help "--help-style all"

scripts will give you only the help information built from your package-scripts.js file

nps help "--help-style scripts"

basic will give you only the name and description of the scripts from your package-scripts.js file

nps help "--help-style basic"

Some of the options accepted by CLI can also be provided in a.npsrc or.npsrc.json JSON configuration file.It will search upwards starting in the directory thenps command was invoked from.

The accepted options are:

• require
• config

The other options can be provided in the specified configuration file (or the defaultpackage-scripts.js) once it is loaded, but theseoptions need to be provided in order to find and parse the configuration file.

This is can be useful when you have a reqular set of options you need to pass tonps, especially when usingseries.nps() orconcurrent.nps() fromnps-utils.

{"require":"ts-node/register/transpile-only","config":"package-scripts.ts"}

That's all for the CLI.

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

nps expects to yourpackage-scripts.js file tomodule.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 canlook 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 stringsimple:'echo "this is easy"',// nps simple// you can specify whether some scripts should be excluded from the help listhidden:{script:"debugging script",hiddenFromHelp:true},test:{default:{script:"jest",// nps testdescription:"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-stuffscript:'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 configurenps with the following options:

Setting this totrue will preventnps from outputting anything for your script (normally you'll get simple outputindicating the command that's being executed). This effectively sets thelogLevel todisable.

This sets the logLevel ofnps.

By settingLOG_LEVEL environment variable you can control the log level fornps

Log levels available:

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

Congratulations your repo is nps-friendly. Time to flaunt it! Add the nps-friendly badge to your README using the following markdown:

[![nps friendly](https://img.shields.io/badge/nps-friendly-blue.svg?style=flat-square)](https://github.com/sezna/nps)

Your badge will look like this:

It may also make sense to change your README.md or CONTRIBUTING.md to include or link to the nps project so that your new contributors may learn more about installing and using nps.

Have you looked at the examples inother/EXAMPLES.md?

Just to be clear: You donot have to use thestart script. You can use whatever you like. But I recommend usingthestart.npm scripts are generally run withnpm run <script-name>. There are some exceptions tothis. For example:

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

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

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

• Pull out npm scripts into another file with nps byElijah Manor (5:53)

This was inspired bya tweet by@sindresorhus.

Big thank you to@tmpvar for giving up the namenps! The originalnps is nowcallednpmsearch-cli.

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

• scripty has a solution for this problem as well. The reason I didn't go with that though is you still needa line for every script (one of the pains I'm trying to solve) and a each script requires its own file (one of thebenefits 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

This projectis p-s! It was just renamed during a major version bump. There were a fewbreaking changes for this to happen and those are documented on thereleasespage.

Thanks goes to these people (emoji key):

Kent C. Dodds 💻📖🚇💡📹👀	David Wells 💻	Abhishek Shende 💻⚠️	Rowan Oulton 💻📖⚠️	Gilad Goldberg 💻	Tim McGee 💻📖	Nik Butenko 💡💻
Tommy 🐛💻⚠️👀	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 👀	bumbleblym 💻📖	Islam Attrash 💻	JasonSooter 📖	Nate Cavanaugh 💻	Wissam Abirached 💻⚠️
Paweł Mikołajczyk 💻⚠️	Kyle Welch 💻⚠️	Lufty Wiranda 💻	Bhargav Ponnapalli 💻	falieson 📖🔧	Suhas Karanth 🐛💻	Eric Skram 📖
Kether Saturnius 💻📖	Sviatoslav 🐛💻	Wei Wang 💻	Sami Jaber 🐛💻	Florian Löchle 💻	Kevin J 💻	Ben Teichman 💻📖
Alex Hansen 💻🚇👀	Casey Primozic 🚇👀	Vivek Fitkariwala 💻	Danny Coates 💻

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

MIT