150-justfile

Justfile Engineering Ruleset

Goal: Standardized justfile patterns that provide consistent, discoverable commands across all projects regardless of underlying technology.

Why Just over Make?

Feature	Make	Just
Cross-platform	Requires GNU Make	Works consistently everywhere
PHONY declarations	Required for non-file targets	Not needed (all recipes are "phony")
Default recipe	Requires explicit default:	First recipe or default
Help/listing	Manual implementation	Built-in just --list
Variables	Complex syntax $(VAR)	Simple syntax {{var}}
Parameters	Awkward	Native support
String interpolation	Limited	Full support
Error messages	Cryptic	Clear and helpful
Dependencies	File-based	Recipe-based

Installation

# macOS
brew install just

# Cargo (cross-platform)
cargo install just

# Other platforms: https://github.com/casey/just#installation

Core Principles

• Consistency: Common interface across all components regardless of underlying technology
• Simplicity: Hide platform-specific commands behind standard recipes
• Discoverability: just --list shows all available commands with descriptions
• Platform Independence: Works across different languages and toolchains

Standard Structure

Required Elements

Every justfile MUST have:

1. Recipe comments using # for --list output
2. Default recipe (first recipe or explicit default)
3. Standard recipes for common operations

Template

# Show available recipes
default:
    @just --list

# Set up and validate the local development environment
init:
    ./scripts/init.sh

# Install all dependencies
install:
    npm install  # or pip install -r requirements.txt, etc.

# Run in development mode (with live reload)
dev:
    npm run dev  # or python -m flask run, etc.

# Validate code formatting and linting
lint:
    npm run lint  # or ruff check, etc.

# Auto-fix linting issues
lint-fix:
    npm run lint:fix  # or ruff check --fix, etc.

# Run tests
test:
    npm test  # or pytest, etc.

# Run tests with coverage
test-coverage:
    npm test -- --coverage  # or pytest --cov, etc.

# Build the project for distribution
build:
    npm run build  # or go build, etc.

# Remove build artifacts and temporary files
clean:
    rm -rf dist/ node_modules/.cache/

# Run all CI checks
ci: lint test build
    @echo "CI checks passed"