untool is a JavaScript tool designed to streamline configuration and usage of other JavaScript tools. By default, it comes with a basic development and runtime environment for universal React applications. This environment is highly modular. Every one of its default modules is configurable and extensible - and entirely optional.

untool is not really meant to be used on its own, but extended and built upon. To get everything you need to develop and deploy a production grade web application, please check out hops.

Why?

JavaScript tooling is amazing nowadays. There are tons of bundlers, transpilers, analyzers, optimizers, minifiers, formatters, linters, build-, command- and test-runners, package managers... and then, of course, there are gazillions of frameworks, libraries, modules, components, extensions, plugins, addons, mixins...

Everything is just a yarn add (or npm install) away, available free of charge, all built, maintained and supported by enthusiast, diverse communities of voluteers. Things are truly looking peachy.

The sheer amount of tools has a couple of downsides, though. One of them is the fact that it has become increasingly tedious to wire up all these tools, to get and keep them working together.

Having to do so over and over again, probably for many different projects, can be a bit annoying - and frankly quite expensive. untool is being developed to alleviate this annoyance, to help make even complex tooling setups portable and shareable.

How?

untool aims to be a tool for toolsmiths, enabling us to configure, combine and compose other tools. We try to keep it as minimal, extensible and un-opinionated as possible.

untool consists of a small core and some basic mixins providing build, development and production runtimes.

untool's core is based on mixinable, a highly flexible, declarative microframework providing a rather advanced mixin architecture. In mixinable parlance, untool mixins can define both application strategies and implementations.

This extensible core is built with a very powerful configuration engine with full support for presets and multiple environments. Its config can, of course, trivially be extended to support your own mixins and even your whole application. Your application can, in turn, be used as a preset in other apps.

What?

Out of the box, untool leverages the likes of Yargs, Webpack and Express. Its default app runtime implementation is based on React.

The default mixins expose hooks to completely alter their behaviour and functionality. Tap into them using your own mixins and reconfigure Webpack, register additional Express middlewares and Yargs commands or fetch data to bootstrap your React application.

Of course, you can also use untool to add custom mixins, in turn exposing their own hooks. There are three distinct types of mixins you can add: core, server, and browser. Core mixins are used for building and running your app, while the others are runtime mixins that are being used inside your actual application.

The @untool/react package comes with all three kinds of mixins. Why not use it as a starting point for your own mixins?

What Next?

Installation

As untool is completely modular, there is no single best way to install its different parts. Installing hops, a full-blown development and runtime environment based on untool, is probably the most sensible way to get started, though.

$ yarn create hops-app my-hops-app

After these steps, you are good to go: you can just run your app by executing the command yarn start inside your new my-hops-app folder.

Utilization

To use untool, you certainly do not have to learn about all the parts and concepts it is build upon. A big part of what it aims to do is to allow toolsmiths and app builders to work independently of each other.

If you need to extend its features, you will want to take a peek into the black box, though. To become acquainted with untool's innards, it certainly makes sense to dive into its README files. This is the recommended reading order:

• @untool/core: central base module all other packages rely upon
• @untool/yargs: command line interface engine
• @untool/express: development and production server implementation
• @untool/webpack: webpack setup (including Babel)
• @untool/react: universal React implementation
• @untool/info: logging and preflight checks

At some point, though, you will have to read our source files: if, for example, merely configuring @untool/webpack and using its existing hooks does not suffice for your requirements, you will probably want extend it.

Caveat: please be advised that, given the sheer size of the code base untool is exposing through its hooks, we do not apply naïve semver here: while we treat hook method signature changes as major changes, we consider more subtle changes such as the removal of a Webpack loader option as discussed in this PR as minor.

This means that, if you are building custom mixins based on untool, you might want to pin untool package versions in your package.json or at least use tilde (~) instead of the more commonly used caret (^) to specify version ranges.

Contribution

We are using git, lerna and yarn for building untool. To be able to help us out effectively, you have to have git and yarn globally available on your machine.

If you want to contribute to untool, create a fork of its repository using the GitHub UI and clone your fork into your local workspace:

$ mkdir untool && cd $_
$ git clone git@github.com:<USER>/untool.git .
$ yarn install

When you are finished implementing your contribution, go ahead and create a pull request. If you are planning to add a feature, please open an issue first and discuss your plans.

All code in this repository is expected to be formatted using prettier, and we will only merge valid conventional commits in order to enable automatic versioning.

We will not usually accept pull requests introducing breaking changes unless we are preparing a major release: untool strives to be a solid and robust base for others to build upon.

Releasing untool requires the environment variable GH_TOKEN to be set to a valid GitHub access token with the public_repo scope in order to publish the release notes to the GitHub releases page.