wtf-scripts v1.3.0

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

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.

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)