Migration Guide

Practical strategies for adopting modern command runners without disrupting your team

Incremental Adoption Strategies

Migrating from GNU Make

Phase 1: Introduce just

Install just alongside make. Create simple recipes.

# justfile
test:
@make test

Phase 2: Delegate to just

Update Makefile to call just for common tasks.

# Makefile
test:
@just test

Phase 3: Complete migration

Keep Makefile for complex builds, just for everything else.

# Team uses just primarily
just build
just test

Migrating from npm scripts

Phase 1: Identify pain points

Look for cross-platform issues, performance problems.

Signs to migrate:
• Using cross-env, rimraf
• Long, complex scripts
• Performance complaints

Phase 2: Create parallel just recipes

Create justfile with equivalent commands.

# package.json delegates
"scripts": {
"test": "just test"
}

Phase 3: Team adoption

Gradually move complex logic to justfile.

Keep npm scripts for:
• CI/CD compatibility
• Tool integrations
• Lifecycle hooks

Selling the Switch to Your Team

Focus on Concrete Benefits

Cross-platform consistency

Eliminate "it works on my machine" problems

Improved discoverability

New team members can explore with just --list

Performance gains

400ms → 5ms startup time improvement

Faster CI builds

Task's caching can significantly speed up builds

Address Common Concerns

Concern: "Another tool to learn"

Response: Syntax is simpler than make, similar learning curve to basic shell scripting.

Concern: "Our current setup works"

Response: Show specific pain points being solved (cross-platform issues, onboarding friction).

Concern: "Installation overhead"

Response: Single binary, can be committed to repo or installed via package managers.

Concern: "CI/CD compatibility"

Response: Incremental adoption allows keeping existing scripts while improving developer experience.

Common Migration Patterns

Pattern 1: Wrapper Approach

Keep existing tooling but provide a better interface through just/Task.

Before (package.json)

"scripts": {
"test": "cross-env NODE_ENV=test jest",
"build": "rimraf dist && webpack"
}

After (justfile)

test:
NODE_ENV=test jest
build:
rm -rf dist
webpack

Pattern 2: Gradual Replacement

Replace scripts one by one, starting with the most problematic.

Migration Order (recommended)

  1. Cross-platform problematic scripts first
  2. Frequently used developer commands
  3. Complex, hard-to-maintain scripts
  4. CI/CD scripts last (for compatibility)

Pattern 3: Hybrid Approach

Use different tools for different purposes in the same project.

npm scripts

Dependency management, lifecycle hooks

just

Developer interface, common commands

Task

Complex builds, asset compilation

Typical Migration Timeline

1

Week 1-2: Assessment & Setup

Identify pain points, install new tools, create parallel configs

2

Week 3-4: Developer Adoption

Team starts using new commands, feedback collection

3

Month 2: Refinement

Address edge cases, improve complex workflows

4

Month 3+: Full Adoption

Legacy tools kept only where necessary, new tool as primary interface