openclaw - 💡(How to fix) Fix DX: Add Makefile or justfile for common development tasks [1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#59736Fetched 2026-04-08 02:41:13
View on GitHub
Comments
0
Participants
1
Timeline
0
Reactions
0
Author
Participants

Code Example

{
  "scripts": {
    "build": "pnpm canvas:a2ui:bundle && node scripts/tsdown-build.mjs && ...",
    "build:docker": "node scripts/tsdown-build.mjs && ...",
    "build:strict-smoke": "pnpm canvas:a2ui:bundle && node scripts/tsdown-build.mjs && ...",
    "check": "pnpm check:no-conflict-markers && pnpm check:host-env-policy:swift && pnpm tsgo && pnpm lint && ...",
    "check:base-config-schema": "node --import tsx scripts/generate-base-config-schema.ts --check",
    "check:bundled-channel-config-metadata": "...",
    // ... 70+ more
  }
}

---

.PHONY: help build test check dev

help: ## Show this help message
	@grep -E '^[a-zA-Z_-]+:.*?## ' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'

build: ## Build the project (production)
	pnpm build

build-docker: ## Build Docker image
	docker build .

dev: ## Start development gateway with watch mode
	pnpm gateway:watch

test: ## Run all tests
	pnpm test

test-fast: ## Run fast unit tests only
	pnpm test:fast

test-e2e: ## Run end-to-end tests
	pnpm test:e2e

test-channels: ## Run channel-specific tests
	pnpm test:channels

test-extensions: ## Run extension tests
	pnpm test:extensions

check: ## Run all checks (types, lint, format)
	pnpm check

lint: ## Run linter
	pnpm lint

lint-fix: ## Run linter with auto-fix
	pnpm lint:fix

format: ## Format code
	pnpm format

clean: ## Clean build artifacts
	rm -rf dist/

install: ## Install dependencies
	pnpm install

update: ## Update dependencies
	pnpm update

---

# List all recipes
help:
	just --list

# Build the project
build:
	pnpm build

# Run all tests
test:
	pnpm test

# Run fast tests only
test-fast:
	pnpm test:fast

# Start development server
dev:
	pnpm gateway:watch

# Run all checks
check:
	pnpm check
RAW_BUFFERClick to expand / collapse

Problem

OpenClaw has 80+ npm scripts in package.json, making it hard to discover and remember commands:

{
  "scripts": {
    "build": "pnpm canvas:a2ui:bundle && node scripts/tsdown-build.mjs && ...",
    "build:docker": "node scripts/tsdown-build.mjs && ...",
    "build:strict-smoke": "pnpm canvas:a2ui:bundle && node scripts/tsdown-build.mjs && ...",
    "check": "pnpm check:no-conflict-markers && pnpm check:host-env-policy:swift && pnpm tsgo && pnpm lint && ...",
    "check:base-config-schema": "node --import tsx scripts/generate-base-config-schema.ts --check",
    "check:bundled-channel-config-metadata": "...",
    // ... 70+ more
  }
}

Contributors must:

  1. Open package.json to find script names
  2. Understand which script to use for which task
  3. Remember the exact pnpm/npm invocation

Proposed Solution

Add a Makefile with common tasks and self-documenting help:

.PHONY: help build test check dev

help: ## Show this help message
	@grep -E '^[a-zA-Z_-]+:.*?## ' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'

build: ## Build the project (production)
	pnpm build

build-docker: ## Build Docker image
	docker build .

dev: ## Start development gateway with watch mode
	pnpm gateway:watch

test: ## Run all tests
	pnpm test

test-fast: ## Run fast unit tests only
	pnpm test:fast

test-e2e: ## Run end-to-end tests
	pnpm test:e2e

test-channels: ## Run channel-specific tests
	pnpm test:channels

test-extensions: ## Run extension tests
	pnpm test:extensions

check: ## Run all checks (types, lint, format)
	pnpm check

lint: ## Run linter
	pnpm lint

lint-fix: ## Run linter with auto-fix
	pnpm lint:fix

format: ## Format code
	pnpm format

clean: ## Clean build artifacts
	rm -rf dist/

install: ## Install dependencies
	pnpm install

update: ## Update dependencies
	pnpm update

Alternative: Justfile

If the project prefers just over make:

# List all recipes
help:
	just --list

# Build the project
build:
	pnpm build

# Run all tests
test:
	pnpm test

# Run fast tests only
test-fast:
	pnpm test:fast

# Start development server
dev:
	pnpm gateway:watch

# Run all checks
check:
	pnpm check

Migration Plan

  1. Create Makefile with top 15-20 most common tasks
  2. Add to .gitignore if using local overrides (e.g., Makefile.local)
  3. Update CONTRIBUTING.md to mention Make as an option
  4. Consider adding completion scripts for shell users

Acceptance Criteria

  • Makefile created with at least 15 common tasks
  • make help works and shows descriptions
  • make build, make test, make check, make dev work correctly
  • Documented in CONTRIBUTING.md or docs/development/

References

  • Current scripts: package.json scripts section
  • Related: scripts/ directory organization (see related issue)

Priority: Medium Effort: Low (2 hours) Labels: dx, good first issue

extent analysis

TL;DR

Create a Makefile with common tasks and self-documenting help to simplify command discovery and invocation.

Guidance

  • Identify the top 15-20 most common tasks in package.json and migrate them to a Makefile for easier discovery and use.
  • Consider using just as an alternative to make if preferred by the project.
  • Update CONTRIBUTING.md to mention the new Makefile and provide instructions on how to use it.
  • Test the Makefile by running make help and verifying that the common tasks work correctly.

Example

.PHONY: help build test check dev

help: ## Show this help message
	@grep -E '^[a-zA-Z_-]+:.*?## ' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'

build: ## Build the project (production)
	pnpm build

Notes

The Makefile should be created with at least 15 common tasks, and make help should work and show descriptions. The Makefile should be documented in CONTRIBUTING.md or docs/development/.

Recommendation

Apply the proposed solution by creating a Makefile with common tasks and self-documenting help, as it simplifies command discovery and invocation, and is a low-effort task with a medium priority.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING