hela

Powerful & flexible task runner framework in 80 lines, based on execa. Supports presets, a la ESLint but for tasks & npm scripts

You might also be interested in hela-preset-tunnckocore.

Quality Assurance 💯

If you have any how-to kind of questions, please read Code of Conduct and join the chat room or open an issue.
You may also read the Contributing Guide. There, beside "How to contribute?", we describe everything stated by the badges.

Table of Contents

• Install
• Background
• Usage
  • When project is using hela as npm scripts
  • When project want to start using it
• Ideas
• API
• Related
• Contributing
• Author
• License

(TOC generated by verb using markdown-toc)

Install

This project requires Node.js v6 and above. Use yarn v1 / npm v5 or above to install it.

$ yarn add hela

Or as development dependency

$ yarn add --dev hela

Background

What is that? It is a package that is useful for automation and keeping things on one place.

It is meant to be used in npm scripts, but if you decide to use it as standalone tool you still can. The core is pretty minimal, really 80 lines without the documentation comments, but it has very flexible nature by embracing Shareable Configs (or also called "presets").

A working preset, you can see in use here (yes, hela uses itself and presets to release itself) and in the first created preset - hela-preset-tunnckocore, which by the way uses itself AND hela too! It is pretty awesome, seriously.

Not only the presets gives us power. Hela uses pretty fantastic configuration loader, which is separated from the core as pretty-config. It is similar to the very much used cosmiconfig, but is a lot more smaller (by implementation, by lines and by deps means) with great defaults and lookup on few places.

The pretty-config looks for this files to load configuration of some tool:

const configFiles = [
  '.%src.json', // 1
  '.%src.yaml', // 2
  '.%src.yml', // 3
  '.%src.js', // 4
  '%s.config.js', // 5
  '.%s.config.js', // 6
  '.%src', // 7 - first try JSON, if fail to parse then fallback to YAML
  'package.json', // 8 - pkg.eslint || pkg.eslintConfig || pkg.config.eslint
]

Not to mention that it has support for adding more if needed.

For example, to load some preset, you can create .helarc.json with this, where if you skip hela-preset- prefix it is assumed automatically.

{
  "presets": [
    "foo",
    "hela-preset-bar",
    "tunnckocore",
    "./some/relative/JS-or-JSON-file.js"]
}

And so, above will resolve hela-preset-foo, hela-preset-bar, hela-preset-tunnckocore and the tasks/presets from some given relative file. And everything is recursive.

Basically, hela just loops over an object of key/value pairs, where key is the name of a task and the value is a string (directly passed to execa), an array of strings (run in series passed to execa) or a function.

If task is a function, then it is passed with ({ parse, argv, taskName, hela, helaExec, helaShell, ...options }) signature. Worth mentioning that it is called in a promise.then() and so the nextTick - be aware of that.

Usage

Most easy to try it, is to install both hela and hela-preset-tunnckocore and run hela style on some project - it will format with Prettier and check with ESLint the files in my-project/src/**/*.js.

When project is using hela as npm scripts

Another way is to just clone this repository and run with yarn or npm

$ yarn build:cli
$ yarn start style
$ yarn start build

or if you just decide to contribute to some of the @tunnckoCore projects then you can just run

$ yarn commit

It will do what is needed and lead you to interactive prompt, which will ask you what you just implemented feat, fix or chore then a message and etc. We follow Convetional Commits v1 specification.

When project want to start using it

Before doing that you should choose some preset and you can just use hela directly without adding it to scripts, because it expose a CLI command called hela too.

For example, in hela-preset-tunnckocore we (will) have update task. Thee job of that task is to just dangerously replace existing bits. By "replace" we mean that it will just read the package.json of the current working directory (CWD) and:

1) set four npm scripts to

{
  "scripts": {
    "start": "hela",
    "test": "yarn start test",
    "precommit": "yarn start precommit",
    "commit": "yarn start commit"
  }
}

2) set files field to

{
  "files": [
    "dist/"
  ]
}

3) create .helarc.json file in CWD

{
  "presets": "tunnckocore"
}

4) set devDependencies field to (the only needed when using tunnckocore preset)

{
  "devDependencies": {
    "eslint-config-standard-tunnckocore": "^1.0.7",
    "hela-preset-tunnckocore": "^0.4.3",
    "husky": "^0.14.3",
    "mukla": "^0.4.9",
    "semantic-release": "^7.0.2"
  }
}

5) and optionally engines field to

{
  "engines": {
    "node": ">=6",
    "npm": ">=5",
    "yarn": ">=1"
  }
}

Nothing strange, right? It is some preset that is used by someone. The cool thing is that we can implement another very simple preset, for example called hela-preset-init which is more unopinionated and will be suitable for every project.

Ideas

• hela-preset-init - unopinionated preset with one task: hela init
• hela-preset-new-project - project scaffolder

API

Review carefully the provided examples and the working tests.

TODO...

Related

• dush: Microscopic & functional event emitter in ~350 bytes, extensible through plugins | homepage
• execa: A better child_process | homepage
• hela-preset-tunnckocore: A hela preset of tasks for @tunncoCore GitHub organization | homepage
• mri: Quickly scan for CLI flags and arguments | homepage
• p-map-series: Map over promises serially | homepage

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
Please read the Contributing Guide and Code of Conduct documents for advices.

Author

• github/tunnckoCore
• twitter/tunnckoCore
• codementor/tunnckoCore

License

Copyright © 2017, Charlike Mike Reagent. Released under the MIT License.

This file was generated by verb-generate-readme, v0.6.0, on October 09, 2017.
Project scaffolded using charlike-cli.