README
WTF Scripts 
What the F -
Summary:
A utility for allowing package owners to provide short documentation strings for each script in the "package.json" file.
A better alternative to the popular package "npm-scripts-info". This has more options and supports mustache templates in your help messages by default.
Usage
Via the CLI
# Put this in your "info" script, or something else. If you've setup some common scripts (check out the defaults) and just need it for that, you don't need to do anything else, but if you really want to, read on!
wtf-scripts
CLI Options
-V, --version output the version number
--reporter [name] -r Runs wtf-scripts with the selected reporter
--key [name] -k The key that contains the help items. This defaults to "scripts-help".
--prefix [regex] A regex that runs against each key in the scripts object, matching any items that are help items. Thisdefaults to /^[,@~?]/i.
--json [file] The JSON file containing each help message. This defaults to the help key in package.json.
--no-defaults Disallows assigning default help messages to common scripts.
-h, --help output usage information
If there is a scripts-help.json
file in the current working directory, that will be used instead of the help key in your package.json
.
If you supply the --json
flag, that is used instead of scripts-help.json
or your package.json
.
Programmatic API
const wtf = require('wtf-scripts');
// Check out the typings (index.d.ts) file for the API.
const help = wtf({
name: 'silly-package',
scripts: {
// This script will get the default description.
test: '',
// This has an inline help item.
inline: '',
// You can use either ",", "@", "~", or "?" by default, or you can pass a regex.
// Here is a template:
'@inline': 'inline help item for package {{name}}',
// This has an external help item.
external: ''
},
'scripts-help': {
external: 'external help'
}
});
help;
/* ->
{
test: 'Runs the tests for this package.',
inline: 'inline help item for package silly-package',
external: 'external help item'
}
*/
Reporters
Good news: You can add your own reporter! Or you can use the ones that come with wtf-scripts
, here's a fancy list.
Name | Details |
---|---|
plain |
The standard boring reporter, and the default one. |
color |
Prints your help in color! Script names are blue, and messages are green. |
rainbow |
Like the color reporter, but prints out rainbow colors instead. |
json |
Prints out a JSON array of { key, value } objects, where key is the script name, and value is the help message. |
html |
Prints out a HTML list (<ul> ), where which item looks like this: <li><span class="name">script name</span><span class="value">help message</span></li> |
Templates
More good news :tada: You can use Mustache templates in your help messages!
{
"name": "silly package",
"description": "a package",
"scripts": {
"test": "tape test.js"
},
"scripts-help": {
"test": "Tests {{name}}, which is {{description}}"
}
}
This outputs:
{
"test": "Tests silly package, which is a package"
}
Please note: minstache
is a bit silly, and doesn't support {{ spaces }}
in your Mustaches.
Default Help
If wtf finds a commonly-used script name without a help item, it will provide a default one. Here's a list of the defaults.
X being the name of your project. Yes, the defaults are clever.
Name | Default Value |
---|---|
test |
Runs the test for X. |
coverage |
Outputs coverage information. |
watch |
Watches the files, and rebuilds them on change. |
info |
Display information about the scripts present. |
start |
Starts X. |
stop |
Stops X. |
coveralls |
Sends the current test results to the coveralls service. |
restart |
Restarts X. |
build |
Builds X. |
serve |
Starts a local development server. |
lint |
Lints the codebase, printing out any formatting errors. |
eslint |
Runs eslint on the codebase. |
tslint |
Runs tslint on the codebase. |
docs |
Generates documentation for X |
start:production |
Starts X in production mode. |
start:development |
Starts X in development mode. |
lint:fix |
Fixes any issues picked up by the linter. |
Templates
By default, the minstache
engine is used to compile templates in help items.
If you want to know more about this implementation, check it out on NPM.
Errors
wtf might throw, and it probably will if you give it garbage. Here are times when it may throw an error.
- When the input is not an object.
- When the input does not have a "scripts-help" property (or whatever you've chosen in the configuration).
- When there is a help item for a script, but the script cannot be found.
- When there is both an inline and external help item for a script.
As long as you give it proper input, you should be fine. If this isn't the case, please submit an issue / pull request and I'll be right on the case.
Happy hacking!
License
This project is licensed under the MIT license. A copy of this license can be found in the license file.
MIT @ Will Hoskings (resynth1943)