shared-scripts

Convenience tool to share scripts across multiple repositories.

Inspired by kcd-scripts and eslint's sharable config.

Integrating setup configurations into the codebase comes at a cost:
The repositories are splattered with configuration files (eslintrc, jest.config, package.json, etc.).

While this allows to tailor the setup to the needs of the software,
it usually leads to copying a bunch of configuration directives.
They might be thought through at first, but often enough they end up being just there because "at some point someone considered it necessary and I don't want to change a running system" - and actually maintaining them seems just cumbersome.

We try to keep our code lean, and so we should strive for the same regarding our configurations.

react-scripts and others try to solve this with a 'one-fits-all' approach moving the necessary configuration into this package so that consuming packages end up just with the dependency for react-scripts or similiar.
By updating this dependency all embedded configurations are automatically updated too.

kcd-scripts provides an interesting solution working with plugged in configurations but "it's really specific to [the authors] needs".

eslint allows to set up a shared configuration and extending it in multiple repositories of similar needs.

Taking eslint's approach of shareable configurations this package provides the command-line utility to extend/overwrite/wrap other scripts and reuse them across multiple repositories.

Installation

$ yarn add --dev shared-scripts

Usage

Set up a scripts.config.js that exports config like:

 module.exports = {
    extends: [
        // reference other configs by require-resolvable names ...
    ],
    scripts: {
        // reference scripts by require-resolvable names ...
        'foo': '@myNamespace/myScriptCollection/foo',
        'echo': __dirname + '/myScript',
        // or define them inline
        'echo': require('./myScript'),
    },
}

Run one of the scripts on the command line:

 $ yarn scripts foo

Options

$ yarn scripts --help prints available scripts
$ yarn scripts --debug-config displays information about the resolved config
$ yarn scripts foo --help prints the options for script foo

Scripts

 // ./myScript.js
module.exports = {
    description: 'Example script that echoes its arguments',
    variadicArgs: {
        description: 'Lines',
    },
    run(params) {
        params.variadicArgs.forEach(l => process.stdout.write(`${l}\n`))
    },
}

Options

     options: {
        foo: {
            description: 'Available as --foo flag',
        },
        bar: {
            description: 'Available as --baz and -b flag',
            long: 'baz',
            short: 'b',
        },
        p: {
            description: 'This one is -p followed by two values',
            values: ['x', 'y'],
        },
    },

The script can access the command line options as e.g. params.options.p.x

Arguments

     requiredArgs: [
        {
            id: 'foo',
            description: 'This one is required.',
        },
    ],
    optionalArgs: [
        {
            id: 'bar',
            description: 'This one can be omitted.',
        }
    ],

The script can access the command line arguments as e.g. params.args.foo.

Variadic arguments

     variadicArgs: {
        id: 'extra',
        description: 'This allows more arguments to be passed',
    },

Variadic Arguments are available as params.variadicArgs.

Exit code

If the run function of a script throws the script will exit with either the value of that throw if it is a number - or 2 otherwise.