@splash-plus/scripts

Simple script wrappers for sharing common logic

Table of Contents

• @splash-plus/scripts
  • What Is This?
  • Getting Started
    • Basic Usage
    • Overriding configs
    • Config Options
    • Command Options
  • Versioning
  • Developing
    • Built With
    • Prerequisites
    • Building
    • Deploying / Publishing
    • Testing
    • Style guide
    • Commiting
  • Licensing

What Is This?

This package aims to extend the power of npm scripts in modern javascript projects by providing an abstraction layer to modern project configuration, while providing everything a developer would need to scaffold configs like webpack, babel, jest, and more with sane configuration defaults. In case these defaults just aren't the right fit for your project, this project can also be extended as needed to still provide a starting point for your project configuration

In simpler terms, it's shareable config management as a cli, so you and I can manage all our jest, webpack, eslint, stylelint, and the other 400 or so configs needed for all the bells and whistles in a modern js project in one place so they can be reusable and extended.

Getting Started

Basic Usage

In order to use this module, you first need to create a splash.config.js, or one of the config options cosmic-config supports. A basic one looks a bit like this:

// splash.config.js
module.exports = {
  extends: '@splash-plus/config-jest',
  commands: [
    {
      name: 'echo',
      resolve: 'local',
      description: 'Runs the echo command',
      command: 'echo "Hello World!"'
    }
  ]
}

And from there, you can run the command within an npm script context:

// package.json
{
  "scripts": {
    "echo": "splash-scripts echo"
  },
}

Upon running npm run echo, you should see "Hello World!" printed to the console!

Note: The splash.config.js is not required to be a js file, and can be anything supported by Cosmic Config

Overriding configs

Other configs can be extended using a module name as a single string, or a list of module names as an array of strings:

// splash.config.js
module.exports = {
  extends: '@splash-plus/config-jest',
  commands: []
}

or

// splash.config.js
module.exports = {
  extends: ['@splash-plus/config-jest', '@splash-plus/config-webpack'],
  commands: []
}

When extending configs, take care to watch the name of the commands that get imported. Any commands that share the name with resolve in the order they are extended, with the current splash.config.js overriding any extended commands.

Config Options

Field	Type	Description
extends	String/Array<String>	Configs module to be extended, or array of modules to be extended. Can be either an absolute path, relative path, or name of a node module that must be available in the current projects node_modules folder Note: For local builds using node modules, your package.json can reference a local dir, allowing you to leverage extending a local splash config, but this will fail in ci if your setup fails to find the proper directory
commands	Array<Command>	Array of Command Objects

Command Options

Field	Type	Description
name	String	Required The reference name of the command, and how splash-scripts resolves the command. This is what splash scripts maps to when passed an argument, for example a command with name print with be referenced via splash-scripts print
description	String	A (hopefully) semantic description of what your command does, is used to generate the api on any run of splash-scripts --help
resolve	Enum<'local'/'npx'>	Defaults to 'npx' Uses npx by default to run commands via npx, you'll want to set this to 'local' for any cli package that doesn't exist on the npm registry. For local, you will need the package installed on the os or in the current node context, meaning the package much be installed in your node modules or be globally available on the system
command	String	Required The actual command to run. Can be whatever cli tool you're trying to abstract out. Note: When using a resolve type of npx, npx allows specifing the version after the package name, such as webpack@4, for more control/safety against breaking changes. Do note that I have seen a few packages only grab the latest, so in that case setting it to local and requiring the needed module as a dependency (peerDep for extended modules) might be the best solution

Versioning

Using SemVer for versioning. For the versions available, see the release tags.

Developing

Built With

• Cosmic Config for config management/searching
• Commander for handling cli programs
• ShellJs for executing cli commands from node

Prerequisites

To get started, simply clone the repo and install node deps

npm install

Building

Once dependencies are installed, you can build the project and test local changes by starting dev mode:

npm run dev

This will start up a build in watch mode, which will re-babelify all changes as long as the watch server remains up. In a new terminal, navigate to the root project directory and start testing locally by running

node index.js --help

This will print out all the available commands, edit the splash.config.js to test out any further commands

Deploying / Publishing

Changes are automatically published upon merging to the master branch via semantic release

Testing

Run tests:

npm run test

Run tests in watch mode:

npm run test:watch

Run tests in coverage mode:

npm run test:coverage

Style guide

Simply run npm run verify to run any linting or validation commands

Commiting

Commits utilize cz-conventional-changelog to force commit history to follow conventional commits.

Once files are staged, simply run git commit and husky will automatically run verify before running conventional commits to assist in formatting semantic commits.

Licensing

Licensed under MIT.