Causal debugging tool that explains build failures by analyzing dependency and environment drift.
npm install why-brokeIt worked yesterday. Why not today?


---
npm start. It crashes.Standard tools show Where it crashed (Stack Trace).why-broke shows Why it crashed (What changed).
We instantly spot the invisible things that Git misses:
* š¦ Silent Updates: A dependency upgraded and broke you.
* š Missing Info: You forgot a new .env key.
* ā” Wrong Tools: You are running Node 18, but the team switched to 20.
---
Option A: Global (Good for local dev)
``bash`
npm install -g why-broke
Option B: Dev Dependency (Best for Teams/CI)
`bash`
npm install --save-dev why-broke
---
#### 1. The Recommended Way (Set & Forget)
Run this once in your project root:
`bash`
npx why-broke initnpm install
Now, every time you run , we automatically save the "Good State" in the background.
#### 2. The One-Off Way (Auto-Pilot)
Wrap your build command. We watch it for you.
`bash`
npx why-broke "npm run build"
* Success? We save the "Good State" silently.
* Failure? We wake up and tell you what changed.
#### 3. Manual Control
`bash`
npx why-broke record # "This works!"
npx why-broke check # "Whoops, it's broken."
---
When your build fails, why-broke gives you a clear root cause analysis:
`text
ā Command failed. Diagnosing cause...
HIGH [Runtime Drift]
Node version changed from v18.16.0 to v20.2.0
āā Fix: Switch back to v18.16.0 using nvm.
HIGH [Dependency Integrity]
Lockfile has changed. Underlying dependencies have drifted.
āā Fix: Run "npm ci" to restore exact versions.
MED [Dependency Definition]
axios changed in package.json: ^1.4.0 -> ^1.5.0
āā Fix: Revert axios to ^1.4.0 or check changelogs.
`
---
Use why-broke in GitHub Actions to debug "It works strictly on my machine" issues.
example-workflow.yml
`yaml`
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
# Run your build with Auto-Pilot
- name: Build & Analyze
run: npx why-broke "npm run build"
If the build passes, we record the baseline. If it fails later, we tell you why.
---
Q: Where is the snapshot stored?
A: In a file called .why-broke.json in your project root.
Q: Should I commit .why-broke.json?
A: No. Add it to your .gitignore. This file represents your local machine's working state.
Q: Does it read my source code?
A: No. We only hash package-lock.json and check process.env keys. We never read or store your actual code or secrets.
---
We don't just dump a diff. We run a probabilistic analysis using 5 specialized detectors:
| Detector | Checks | Confidence |
| :--- | :--- | :--- |
| RuntimeDetector | Node Version, OS, CPU Architecture. | HIGH |HIGH
| DependencyDetector | Lockfile hash, Manifest versions, Integrity. | |tsconfig
| ConfigDetector | Critical configs (, webpack, Docker). | HIGH |npm_
| EnvDetector | Missing keys (ignores volatile vars). | HIGH |LOW` |
| GitDetector | Commit history, Dirty state, Branch drift. |