Justfile Development

Workflows for authoring, reviewing, planning, and updating justfiles with the

just

When to Use

• Creating a new justfile for a project
• Adding or modifying recipes
• Reviewing a justfile for quality issues
• Planning which recipes a project needs
• Upgrading a justfile as a project matures
• Converting a Makefile to a justfile
• Setting up monorepo module structure

Workflows

Author

When creating a new justfile or adding recipes.

New Justfile Scaffold:

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

default:
    @just --list

# =============================================================================
# Development
# =============================================================================

# Build the project
[group('dev')]
build:
    <build-command>

# =============================================================================
# Testing
# =============================================================================

# Run test suite
[group('test')]
test:
    <test-command>

# =============================================================================
# Code Quality
# =============================================================================

# Format code
[group('lint')]
fmt:
    <fmt-command>

# Run linter
[group('lint')]
lint:
    <lint-command>

# =============================================================================
# Utilities
# =============================================================================

# Remove build artifacts
[group('util')]
[confirm('Remove all build artifacts?')]
clean:
    <clean-command>

Recipe Writing Rules:

[group('name')]

[group('dev')]

# Build the project

_

_ensure-tool name:

[confirm]

[confirm('Delete all?')]

recipe name='default':

&&

cd

[working-directory]

Adding Recipes to Existing Justfiles:

1. Identify the correct group (see Standard Groups below)
2. Place recipe near related recipes in the same section
3. Add doc comment
4. Add

   [group]

   attribute
5. If destructive, add

   [confirm]

Review

Use this checklist when reviewing justfiles.

## Justfile Review

- [ ] `set shell` declared at top
- [ ] All recipes grouped with `[group('name')]`
- [ ] Every recipe has a doc comment
- [ ] No ungrouped recipes (except `default`)
- [ ] Private helpers prefixed with `_`
- [ ] Destructive recipes use `[confirm]`
- [ ] No `cd` usage (use `[working-directory]`)
- [ ] No `&&` chaining (use dependencies or separate lines)
- [ ] No secrets in justfile (env vars or `op://`)
- [ ] `default` recipe shows `just --list`
- [ ] Section separators between groups
- [ ] Recipe names are kebab-case
- [ ] No monolithic recipes (compose from focused ones)
- [ ] Parameters preferred over env vars for inputs

Common Issues:

set shell

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

[group('name')]

# Description

cd

[working-directory('path')]

&&

env('VAR')

op://

Plan

Use when deciding what recipes a project needs.

3-Question Assessment:

Recipe Sets by Project Type:

Decision: Single File vs Modules:

justfile

Convert

When migrating from a Makefile to a justfile.

Steps:

1. Map targets to recipes (all recipes are phony — no

   .PHONY

   needed)
2. Add

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

   at top
3. Add

   default

   recipe with

   @just --list

4. Group recipes with

   [group('name')]

   and add section separators
5. Add doc comments above each recipe
6. Fix anti-patterns (see translations below)
7. Add

   [confirm]

   to destructive recipes
8. Validate:

   just --list

   shows grouped, documented recipes

Makefile → just Translations:

.PHONY: target

target: dep1 dep2

recipe: dep1 dep2

cd dir && cmd

[working-directory('dir')]

cmd1 && cmd2

$(VAR)

{{VAR}}

@echo "msg"

@echo "msg"

export VAR=val

export VAR := "val"

include file.mk

import "file.just"

Update

When upgrading an existing justfile.

Maturity Progression:

YAGNI: Only add levels you currently need. Reassess when project scope changes.

Module Migration:

When a justfile exceeds ~20 recipes, consider splitting:

1. Create

   just/

   directory
2. Move related recipes to

   just/<group>.just

3. Add

   import? "just/<group>.just"

   to root justfile
4. Or use CDN:

   mod name "https://just.arusty.dev/modules/<name>.just"

Quick Reference

Standard Groups

dev

test

lint

docs

docker

release

util

Essential Syntax

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

[group('dev')]

[confirm('message')]

[working-directory('path')]

_recipe-name:

recipe name:

recipe name='value':

recipe *args:

recipe: dep1 dep2

recipe: (dep1 "arg")

if os() == "macos" { ... }

#!/usr/bin/env python3

[script('python3')]

import? "just/mod.just"

mod name "https://url"

Common Functions

os()

"linux"

"macos"

"windows"

arch()

"x86_64"

"aarch64"

env('VAR')

env('VAR', 'default')

justfile_directory()

invocation_directory()

just

aRustyDev Conventions

• Shell: always

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

• CDN modules from

  just.arusty.dev

• Local modules in

  just/

  with

  import?

• Gist templates via

  just apply-gist

  (see

  gist-templates

  rule)
• KuzuDB recipes follow

  graph-data-pattern

  rule

Language Patterns

Quick lookup — see

references/recipe-patterns.md

fmt

cargo fmt

gofmt -w .

prettier --write .

ruff format .

lint

cargo clippy

golangci-lint run

eslint .

ruff check .

test

cargo test

go test ./...

vitest

pytest

build

cargo build

go build ./...

tsc

python -m build

coverage

cargo tarpaulin

go test -cover

vitest --coverage

pytest --cov

See Also

• references/syntax-quick-ref.md

  — full syntax reference

• references/recipe-patterns.md

  — recipe patterns by category and language

• references/module-system.md

  — module system deep dive

• references/maturity-model.md

  — maturity assessment details

• examples/rust-project.just

  — complete Rust CLI/lib justfile

• examples/monorepo-root.just

  — monorepo router pattern

• examples/arustydev.just

  — aRustyDev conventions with gist templates

• tables/standard-groups.md

  — group definitions and ordering

• tables/language-recipes.md

  — Rust/Go/TS/Python recipe matrix