hereby

hereby

I hereby declare thee built.

hereby is a simple task runner.

$ npm i -D hereby
$ yarn add -D hereby

Herebyfile.mjs

Tasks are defined in Herebyfile.mjs. Exported tasks are available to run at the CLI, with support for export default.

For example:

import { execa } from "execa";
import { task } from "hereby";

export const build = task({
    name: "build",
    run: async () => {
        await execa("tsc", ["-b", "./src"]);
    },
});

export const test = task({
    name: "test",
    dependencies: [build],
    run: async () => {
        await execa("node", ["./out/test.js"]);
    },
});

export const lint = task({
    name: "lint",
    run: async () => {
        await runLinter(...);
    },
});

export const testAndLint = task({
    name: "testAndLint",
    dependencies: [test, lint],
});

export default testAndLint;

export const bundle = task({
    name: "bundle",
    dependencies: [build],
    run: async () => {
        await execa("esbuild", [
            "--bundle",
            "./out/index.js",
            "--outfile=./out/bundled.js",
        ]);
    },
});

Running tasks

Given the above Herebyfile:

$ hereby build        # Run the "build" task
$ hereby test         # Run the "test" task, which depends on "build".
$ hereby              # Run the default exported task.
$ hereby test bundle  # Run the "test" and "bundle" tasks in parallel.

Flags

hereby also supports a handful of flags:

-h, --help          Display this usage guide.
--herebyfile path   A path to a Herebyfile. Optional.
-T, --tasks         Print a listing of the available tasks.

ESM

hereby is implemented in ES modules. But, don't fret! This does not mean that your project must be ESM-only, only that your Herebyfile must be ESM module so that hereby's task function can be imported. It's recommended to use the filename Herebyfile.mjs to ensure that it is treated as ESM. This will work in a CommonJS project; ES modules can import CommonJS modules.

If your package already sets "type": "module", Herebyfile.js will work as well.

TypeScript support

hereby supports Herebyfile.mts and Herebyfile.ts, so long as your runtime supports loading these files. This includes like Node's type stripping, bun, or even a custom loader, and so on.

Caveats

No serial tasks

hereby does not support running tasks in series; specifying multiple tasks at the CLI or as dependencies of another task will run them in parallel. This matches the behavior of tools like make, which like hereby intend to encode a dependency graph of tasks, not act as a script.

In general, if you're trying to emulate a serial task, you will likely be better served by writing out explicit dependencies for your tasks.

Tasks only run once

hereby will only run each task once during its execution. This means that tasks which consist of other tasks run in order like a script cannot be constructed. For example, it's not possible to run "build", then "clean", then "build" again within the same invocation of hereby, since "build" will only be executed once (and the lack of serial tasks prevents such a construction anyway).

To run tasks in a specific order and more than once, run hereby multiple times:

$ hereby build
$ hereby clean
$ hereby build