hammerkit

Dependencies

A task can depend on other tasks, which run first (unless they are cached).

Every task can have a list of dependencies. They run before the task, and if any of them fails, all pending tasks are aborted. Dependencies can be chained as deep as needed, as long as there is no cycle.

.hammerkit.yaml
tasks:
  install:
    cmds:
      - npm install
      
  build:
    deps: [install]
    cmds:
      - tsc -b
  
  publish:
    deps: [build]
    cmds:
      - npm publish

Dependencies run in parallel

Dependencies that don't depend on each other run concurrently, up to the --concurrency worker count (default 4). In the example above install must finish before build, but if two branches of the graph are independent they execute at the same time. A dependency that fails stops the whole run; see parallelism and exit codes in the CLI reference.

Which ready task runs first

When more tasks are ready than there are free workers (or, with resource requests, than there is room), hammerkit starts the one on the longest remaining chain first. A task's chain is its own expected duration plus that of the longest line of tasks that wait for it, through the services that need it too. The tasks at the start of a long chain, such as the install and build before a slow e2e, go before a short task nothing waits for, such as lint, which still fits in later.

The expected duration of a task is the median of the last 5 times it ran on this machine, kept in durations/ of hammerkit's directory (~/.hammerkit on Linux, ~/Library/Application Support/hammerkit on macOS, HAMMERKIT_DIR when set). On a server, it is the median of its last 9 successful runs in the same repository. A task that never ran counts as the median of the others, and with no history at all every task counts the same, so the chain is counted in tasks. A task that only groups others, and one already taken from the cache, count nothing. Tasks that are equally urgent start in the order they became ready.

Dependencies of cached tasks

A dependency only runs when a task that needs it has to run. If every task depending on it is a cache hit, it is skipped: when e2e is cached, hammerkit run e2e doesn't rebuild the app e2e was tested against. Skipped tasks show up as skipped in the build summary.

Tasks you ask for — by name, or selected with a label filter — always run (or restore from the cache); only tasks pulled in purely as dependencies are skipped. A service's dependency runs once the service starts, so when every task needing the service is a cache hit, neither the service nor its dependencies run. Under up and in watch mode everything runs.

A task that has to run restores its whole dependency chain, not only its direct dependencies. With install ← build ← test, a changed test runs against a cached build, and install is still restored from the cache (shown as cached) because test may need its outputs, for example node_modules, at run time.

A skipped dependency leaves no outputs in the workspace. If you need them — for example an exported dist — request that task too, or pass --no-skip-deps to run the whole dependency graph as in earlier versions.

Aggregate tasks

A task with deps and nothing else to do groups other tasks under one name: no image, no cmds, no src, no generates, no secrets and no needs.

.hammerkit.yaml
tasks:
  build:all:
    deps: [build:api, build:web]

  test:unit:
    image: node:24-alpine
    deps: [build:all]
    src: [test]
    cmds:
      - npm test

An aggregate runs nothing, so it needs no runtime and no image, and writes nothing to its directory:

  • a task that depends on it gets what its dependencies generate (node_modules, dist), as if it depended on them directly;
  • it is up to date when all its dependencies are, so a task that depends on it can be a cache hit, and it has a check key when they do. Asked for by name, it still checks its dependencies and restores their outputs, and is reported cached when all of them were;
  • a server runs it whatever runtimes allows, and --network does not need to limit it.

A task with deps and its own cmds or src but no image is a local task as before.

Referenced and included tasks are addressed with the prefix:task syntax in deps, for example deps: [npm:install]. See references and includes.

Make sure to set up correct caching to speed up your execution and prevent unnecessary work.

On this page