Justfile Skill

Build system configuration using just, a modern command runner.

Related skills:

• mise - Tool version management (includes just+mise integration patterns)
• go-pro, rust-pro, typescript-pro - Language-specific templates

Installation

# Via mise (recommended - version pinned per-project)
mise use just

# macOS
brew install just

# Linux/Windows (via cargo)
cargo install just

# Or prebuilt binaries: https://github.com/casey/just/releases

When to Use Just

Project Patterns

Simple Repo (Single Package)

For single-language projects, create one

justfile

# Project Build System
# Usage: just --list

default:
    @just --list

# === Quality Gates ===
check: fmt lint test
    @echo "All checks passed"

fmt:
    go fmt ./...

lint:
    go tool golangci-lint run

test:
    go test -race ./...

build:
    go build -o bin/app ./cmd/app

See

references/simple-repo.just

Monorepo (Multiple Packages)

For monorepos, use hierarchical justfiles with the

mod

repo/
├── justfile              # Router - imports package modules
└── packages/
    ├── api-go/
    │   └── justfile      # Go package recipes
    ├── web/
    │   └── justfile      # TypeScript package recipes (optional)
    └── ops/
        └── justfile      # DevOps recipes

Root justfile (router):

# Monorepo Build System
# Usage: just --list
# Usage: just go <recipe>

mod go "packages/api-go"
mod web "packages/web"
mod ops "ops"

default:
    @just --list

# Umbrella recipes call into modules
check: (go::check) (web::check)
    @echo "All checks passed"

setup: (go::setup) (web::setup)
    @echo "All toolchains ready"

Commands become:

just go check

just go lint

just web build

just ops deploy

See

references/monorepo-root.just

references/package-go.just

Recipe Patterns

Quality Gates

Always provide a single

check

# Full quality gates - run before commits
check: fmt lint test coverage-check
    @echo "All checks passed"

Quick Check (Dev Iteration)

Fast feedback loop for development - essential checks only:

# Quick feedback loop - essential checks only
check-quick: lint test
    @echo "Quick checks passed"

Clean Recipe

Standard cleanup for build artifacts and caches:

# Remove build artifacts and caches
clean:
    rm -rf build/ coverage.out node_modules/.cache

Parallel Check Execution (CI)

Run package checks in parallel for faster CI:

# Run all package checks in parallel (CI optimization)
check-parallel:
    @just api check & just web check & wait

Coverage Enforcement

Use shebang for multi-line shell logic:

# Check coverage meets 70% minimum
coverage-check:
    #!/usr/bin/env bash
    set -euo pipefail
    go test -race -coverprofile=coverage.out ./...
    COVERAGE=$(go tool cover -func=coverage.out | grep total | awk '{print $3}' | sed 's/%//')
    COVERAGE_INT=${COVERAGE%.*}
    [ "$COVERAGE_INT" -ge 70 ] || (echo "FAIL: Coverage ${COVERAGE}% < 70%" && exit 1)
    echo "PASS: Coverage ${COVERAGE}%"

The

#!/usr/bin/env bash

Umbrella Recipes with Module Dependencies

# Root justfile calling into modules
check: (go::check) (web::check)
    @echo "All checks passed"

Optional Modules

For packages that may not exist in all environments:

mod? optional-package "packages/optional"

Documentation Comments

Every recipe should have a doc comment (shown in

just --list

# Run unit tests with race detection
test:
    go test -race ./...

Module doc comments - Comments above

mod

just --list

# Go API (GraphQL + Watermill)
mod api "packages/api"

# Next.js frontend
mod web "packages/web"

# PostgreSQL database
mod db "packages/db"

Output of

just --list

api ...      # Go API (GraphQL + Watermill)
db ...       # PostgreSQL database
web ...      # Next.js frontend

Always add doc comments to module imports for discoverability.

Module System Details

Syntax

mod <name> "<path>"              # Required module
mod? <name> "<path>"             # Optional module (no error if missing)
mod <name>                       # Module at ./<name>/justfile

Working Directory

Recipes in modules run with their working directory set to the module's directory, not the root. This is the desired behavior for package-local commands.

Listing Module Recipes

just --list           # Root recipes + module names
just --list go        # Recipes in 'go' module
just --list-submodules # All recipes including submodules

Important: Use

just --list <module>

just <module> --list

Calling Module Recipes

just go check         # From command line
(go::check)          # As dependency in justfile

Integration with Language Toolchains

Go Projects

# Uses go.mod tool directive for pinned versions
lint:
    go tool golangci-lint run

# Auto-fix linting issues (chains goimports to fix imports after modernize changes)
fix:
    go tool golangci-lint run --fix
    go tool goimports -w .

Why chain goimports? The

modernize

fmt.Errorf()

errors.New()

goimports

--fix

TypeScript/Node Projects

Two approaches:

Option A: Thin wrapper (recommended for consistency)

# packages/web/justfile
check:
    npm run check

lint:
    npm run lint

test:
    npm test

Option B: Direct delegation from root (simpler)

# Root justfile - no web module
ts-web-check:
    cd packages/web && npm run check

Rust Projects

check: fmt lint test
    @echo "All checks passed"

fmt:
    cargo fmt --all

lint:
    cargo clippy -- -D warnings

test:
    cargo test

Mise Integration

When a project uses mise for tool version management, just recipes should use

mise exec

See the

mise

.mise.toml

Shell Override (Recommended)

# All recipes automatically use mise-pinned tools
set shell := ["mise", "exec", "--", "bash", "-c"]

build:
    npm run build

test:
    go test ./...

Graceful Degradation

For repos where mise is optional:

set shell := ["bash", "-c"]

# Use mise if available, otherwise fall back to PATH
_exec cmd:
    #!/usr/bin/env bash
    if command -v mise &>/dev/null; then
        mise exec -- {{cmd}}
    else
        {{cmd}}
    fi

build: (_exec "npm run build")
test: (_exec "go test ./...")
lint: (_exec "golangci-lint run")

Note: No

.mise.toml

Why This Matters

Recommendation: Use the shell override for team repos. Use graceful degradation for open source where mise adoption varies.

Caveats

Failure mode: Shell override + mise not installed = cryptic "could not find shell" error. Use graceful degradation for open source.

First clone: Contributors must run

mise trust

setup:
    mise trust
    mise install
    @echo "Toolchain ready"

Security Auditing

All language templates include consistent audit recipes:

audit

audit-fix

audit-ci

Language tools:

npm audit

govulncheck

go get -tool golang.org/x/vuln/cmd/govulncheck@latest

cargo audit

cargo install cargo-audit

Reference Templates

Load the appropriate template based on project structure:

references/simple-repo.just

references/monorepo-root.just

references/package-go.just

references/package-ts.just

references/package-rust.just

Note: Reference files use

.just

justfile

.justfile