hela

Powerful & flexible task runner framework in 80 lines, based on execa. Supports shareable configs, a la ESLint

You might also be interested in hela-config-tunnckocore or in the other related projects.

Quality Assurance 💯

If you have any how-to kind of questions, please read Code of Conduct and join the chat rooms 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
• CLI
• API
  • .hela
  • .exec
  • .shell
• Shareables Configs
• Related Projects
• Contributing
• Contributors
• Users
• License

(TOC generated by verb using markdown-toc)

Install

This project requires Node.js v8 or above. Install it using yarn v1 or above / npm v5 or above.

$ yarn add 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, in really 80 lines without the documentation comments, but it has very flexible nature by embracing Shareable Configs. Yes, it supports presets of tasks same as found in ESLint and Renovate. Each preset is just an object with extends and/or tasks properties.

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's resolving mechanism looks for this files to load configuration (where the %s is the name of the 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 tries JSON, if fail to parse then fallback to YAML
  'package.json', // 8 - foo, fooConfig or pkg.config.foo fields
]

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

{
  "extends": [
    "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, exec, shell, ...options }) signature. Worth mentioning that it is called in a promise.then() and so the nextTick - be aware of that.

CLI

Install it as dev dependency of your project first, then you can use it just like you use gulp, for example hela <taskName>. With hela-config-tunnckocore preset you can run tasks like the following, but go there for more deep docs.

$ hela style
$ hela lint
$ hela format
$ hela commit
$ hela release

To start using some existing preset in your project add .helarc file in the root and set extends property to the name of the config (hela-config- prefix is assumed), for example:

extends: tunnckocore

You also can override the tasks from the given preset, for example

extends: tunnckocore
tasks:
  lint: echo foobar

And when running hela lint or yarn hela lint it will execute echo foobar instead of eslint --fix. Also note that you have access to the shell's environment variables.

Try to run hela show-cwd somewhere

tasks:
  show-cwd: echo "Your working directory is $PWD"

Notice that you don't need any presets to work correctly.

API

Review carefully the provided examples and the working tests.

.hela

Controls, merges and resolves all tasks from config files and passed through opts.tasks.

All opts are passed to execa-pro and to execa, so you can pass opts.stdio: 'inherit' for example to output the result of each command in the console, useful for things like prompt inputs. Resolving works recursively and support ESLint style presets through the opts.extends. The extends property can be string (the name of the preset, prefixed with hela-config-), a function (that is passed with { extends, tasks } object) or an object containing another extends and/or tasks properties.

Configuration is handled by @tunnckocore/pretty-config which is pretty similar to the cosmiconfig package and so the config files lookup order is:

• .helarc.{json,yaml,yml,js}
• hela.config.js
• .hela.config.js
• .helarc - YAML or JSON syntax
• package.json - one of hela, helaConfig or config.hela fields

Params

• opts {Object}: requires to have at least tasks ot extends properties
• returns {Promise}: so you can use async/await mechanism

.exec

A mirror of execa-pro's .exec method, see its docs. This is also included in the object that is passed to each task if the task is a function.

Params

• cmds {string|Array}: commands to call, if array of strings executes in series
• options {Object}: optional, passed to execa-pro and so to execa
• returns {Promise}: so you can use async/await mechanism

.shell

A mirror of execa-pro's .shell method, see its docs. This is also included in the object that is passed to each task if the task is a function.

Params

• cmds {string|Array}: commands to call, if array of strings executes in series
• options {Object}: optional, passed to execa-pro and so to execa
• returns {Promise}: so you can use async/await mechanism

back to top

Shareables Configs

• hela-config-tunnckocore - a preset for every repository and package in @tunnckoCore organization.
• hela-config-rollup-build - preset of tasks focused on bundling, using rollup. Go create for Webpack?
• hela-config-new-project - preset of tasks for generating whole new project and repository.

Related Projects

Some of these projects are used here or were inspiration for this one, others are just related. So, thanks for your existance!

• execa-pro: Thin layer on top of execa that allows executing multiple commands in… more | homepage
• gitcommit: Simple, small and stable helper & prompter for submitting conventional commits | homepage
• hela-config-tunnckocore: A hela task runner shareable config (preset of tasks) for @tunnckoCore org | homepage
• new-release: A stable alternative to semantic-release. Only handles NPM publishing and nothing more… more | homepage
• parse-commit-message: An extensible parser for commit message that follows Conventional Commits v1 spec | homepage

back to top

Contributing

Please read the Contributing Guide and Code of Conduct documents for advices.
For bugs reports and feature requests, please create an issue or join us at our Flock chat rooms.

Contributors

Thanks to the hard work of these wonderful people this project is alive and it also follows the all-contributors specification.
Pull requests, stars and all kind of contributions are always welcome.

Users

You can see who uses hela in the USERS.md file. Please feel free adding this file if it not exists.
If you or your organization are using this project, consider adding yourself to the list of users. Thank You!

License

Copyright (c) 2017-present, Charlike Mike Reagent <olsten.larck@gmail.com>.
Released under the Apache-2.0 License.

This file was generated by verb-generate-readme, v0.6.0, on November 15, 2017.
Project scaffolded and managed with hela.