Getting started

PrerequisitesCopy Anchor Link

Hammerkit itself only needs Node.js (see installation for binary and Homebrew options that don't).

Tasks that declare an image run inside a container, so you also need a running container engine — Docker or any Docker-compatible daemon. Containers are the recommended way to run tasks: the build then uses the exact same tools on every machine and in CI, instead of whatever happens to be installed locally. Check the daemon is up with:

docker info

If that prints server information you're ready. If it errors, start Docker (or remove the image: line from the example below to run on your host instead).

Create your first build fileCopy Anchor Link

To get started with hammerkit, you will need to create your first build file. Build files are usually called .hammerkit.yaml and can be created from scratch manually or by using the init command.

hammerkit init

If you created your build file with the init command, the build file will look like the example below.

envs: {}

tasks:
  example:
    image: alpine
    cmds:
      - echo it's Hammer Time!

This build file contains an example command which prints a statement to the console inside an alpine container.

Run your first taskCopy Anchor Link

To run your first command, make sure you're in the same directory as the build file and run:

hammerkit example

The first run pulls the alpine image if it isn't on your machine yet (later runs reuse it), starts a container, executes the echo command it's Hammer Time! and exits with code 0. Run it a second time and it runs again: the task declares no src, so hammerkit can't tell whether anything it reads has changed. Declare the files a task reads under src, and an unchanged task is reported as cached and skipped — that's caching at work.

Discover the tasks in a projectCopy Anchor Link

When you clone a repository that already uses hammerkit, list everything it defines with:

hammerkit ls

This prints every task and service with its image, sources, generated outputs and dependencies. For the full command list and global flags use:

hammerkit --help

Where to go nextCopy Anchor Link

• Why hammerkit — what it does that Make / npm scripts / Taskfile don't.
• Concepts — local vs. container, src/generates/mounts, deps vs. needs.
• Tutorial — build, test and cache a real Node project end to end.
• Task — sources, outputs, dependencies and caching in depth.
• The runnable examples/ folder in the repository.

ConclusionCopy Anchor Link

In this short introduction you created your first build file and executed your first task. The build file and the task in this example were very basic; to see the full functionality of hammerkit, take a look at the rest of the documentation.