Why I Replaced Long npm Scripts with a Makefile for JavaScript Projects

Mar 15, 2026

Swap brittle, long npm scripts for a simple Makefile to simplify builds, speed CI, and improve cross‑project consistency—practical tips for Indian dev teams.

Written by: Rohan Deshpande

I used to have a single package.json with a dozen line-wrapping npm scripts that felt clever until they stopped being maintainable. Every time someone added a new env var, piped one tool into another, or tried to run the same task in CI, things broke. The project grew; the scripts grew wilder. Eventually I swapped them for a simple Makefile—and nothing about my team’s velocity improved magically, but many little frictions disappeared.

If you’ve ever cursed at quoting in package.json or had CI minutes burned because every pipeline reinstalled the world, read on. I’ll explain why a Makefile for JavaScript projects is worth considering, what it actually buys you, and the tradeoffs you should expect.

Why a Makefile? The pragmatic wins

• Single source of orchestration: Make is opinionated about tasks and dependencies. Instead of embedding long shell glue inside package.json, you declare targets like build, test, lint, and their prerequisites. It’s easier to read at a glance.
• Less duplication across repos: When you run similar scripts in many microservices, the Makefile lets you share a compact pattern (or a small include) rather than replicating long npm scripts with tiny variations.
• Better tooling composition: Make integrates smoothly with shell commands, Docker, and caching primitives. Want to run tests only when source changed? Make’s timestamp logic does that for free.
• Clearer CI steps: CI config becomes a thin wrapper (ci: make ci), and the heavy lifting stays in the Makefile. That reduces the duplication between local dev and CI, which saves GitHub Actions minutes and pipeline debugging time—important for teams on budget-sensitive plans in India.
• Avoid npm script quoting hell: Nested quotes and cross-platform differences in package.json are a recurring source of bugs. Makefile recipes are written in plain shell, which most developers already understand.

A tiny example (the idea, not a perfect drop‑in)

.PHONY: install lint test build ci install: npm ci

lint: install npx eslint src

test: install npx jest —coverage

build: install npx tsc

ci: lint test build

(Indentation matters in Makefiles—the recipe lines must start with a tab.)

Real benefits I saw in 3 months

• Fewer “it works on my machine” reports: contributors run make ci locally and see the same steps CI will run. That consistency removed a lot of back-and-forth.
• Faster local iterations: make test could skip the install step with a conditional, so I stopped re-downloading node_modules on every run. For contributors on metered or slow home broadband—common in many Indian cities—that saved real time.
• Smaller, clearer package.json: npm scripts returned to being short wrappers for local dev convenience, not the place to live orchestration logic.

When Makefiles are a pragmatic win — and when they aren’t

Use a Makefile if:

• You have multiple related commands with shared prerequisites (build → test → lint).
• Your CI and local dev should run identical steps.
• You want to avoid complex JSON quoting and keep orchestration out of package.json.

Avoid or delay it if:

• Your project is tiny (one script, e.g., start), and the overhead feels unnecessary.
• Your contributors are Windows-only and unfamiliar with Make and you can’t standardize shells. (Windows now has WSL and Make ports, but it’s an extra friction.)

Tradeoffs and gotchas I ran into

• Cross-platform polish: Make assumes a POSIX shell. On Windows machines without WSL or Git Bash, developers may need extra setup. In our team this was fine because most engineers used Linux/macOS or WSL, but your mileage may vary.
• Non-obvious shell behaviour: Make runs recipes in separate shells by default. That surprised people who tried to set an environment variable in one line and use it the next. You can use line-continuation or .ONESHELL to change behaviour, but that’s another nuance to teach.
• Not a replacement for task runners: For complex JS-only logic (parallelism, file globs handled by Node), an npm script invoking a JS task runner or small Node script can still be cleaner. I recommend complementing Makefiles, not replacing all JavaScript tooling.
• Onboarding: Introduce a README snippet and a few examples. Don’t assume everyone knows make. We added a make cheat-sheet to our contributing guide and reduced confusion fast.

Practical tips for adoption

• Keep package.json scripts as thin shims. For example: “ci”: “make ci” so developers can still use npm run ci if they prefer.
• Start small: migrate one non-trivial script (like build-and-test) first. Measure CI time, install calls, or developer complaints before and after.
• Add a lint target and make ci depend on it—lint failures early in CI save compute minutes.
• Document common patterns in CONTRIBUTING.md and add an alias script for Windows users if needed (PowerShell-friendly wrappers).

Why I’d recommend it for small Indian teams

Many startups here watch cloud and CI costs closely. Makefiles reduce duplication and make it trivial to avoid unnecessary installs and redundant steps—small optimizations that compound across many repositories and CI runs. They also help teams with varied developer setups (laptops on metered connections, remote contributors on slow home networks) by offering a single, readable orchestration file that’s easy to audit.

Conclusion

A Makefile for JavaScript is not a magical silver bullet, but it’s a practical, low-dependency way to untangle brittle npm scripts, align local and CI steps, and shave off repeated friction. Expect a tiny learning curve for cross-platform quirks and be honest about when to keep some logic in Node instead. If your repo has more than a handful of scripts or you’ve suffered quoting/consistency pain, try migrating one task to a Makefile this week—chances are, you’ll appreciate the simplicity.

Warm tip: start with make help—a one-line target that documents the common tasks will save you from writing a separate doc and make the change feel intentional to new contributors.