https://github.com/beyteflow/errlens
A lightweight CLI that explains JavaScript/Node.js errors in plain English and suggests fixes.
https://github.com/beyteflow/errlens
cli javascript nodejs
Last synced: 4 months ago
JSON representation
A lightweight CLI that explains JavaScript/Node.js errors in plain English and suggests fixes.
- Host: GitHub
- URL: https://github.com/beyteflow/errlens
- Owner: BeyteFlow
- License: mit
- Created: 2026-02-25T16:34:57.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-02-26T18:12:03.000Z (5 months ago)
- Last Synced: 2026-02-26T21:46:13.706Z (5 months ago)
- Topics: cli, javascript, nodejs
- Language: JavaScript
- Homepage:
- Size: 1.25 MB
- Stars: 2
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ErrLens 🔍
> **Translate cryptic JavaScript errors into human-readable solutions instantly.**
**ErrLens** is a professional-grade CLI utility designed to eliminate developer frustration. It intercepts Node.js crashes, analyzes stack traces, and delivers plain-English explanations with actionable fixes—directly in your terminal.
---
## 🌟 Key Features
- 🚀 **Instant Diagnostics** – No more context-switching to Google or StackOverflow.
- 🔄 **Live Monitoring** – Catch errors in real-time using the `errlens run` command.
- 🧠 **Fuzzy Logic Engine** – Matches messy stack traces and typos using `Fuse.js`.
- 🎨 **Beautiful UI** – High-visibility terminal output powered by `boxen` and `chalk`.
- 🤖 **CI/CD Ready** – Export raw data via `--json` for automated error reporting.
---
## 📦 Installation
Install globally via npm to use the `errlens` command anywhere in your terminal:
```bash
npm install -g errlens
```
---
## 🛠 Usage
### 1️⃣ Automatic Monitoring (The "Pro" Way)
Run your script through ErrLens. If it crashes, ErrLens intercepts the error and explains the fix before the process exits.
```bash
errlens run your-app.js
```
---
### 2️⃣ Manual Analysis
Found a weird error in your logs? Just paste the message:
```bash
errlens "TypeError: Cannot read properties of undefined"
```
---
### 3️⃣ Pipeline Integration
Get machine-readable results for your own tooling or automated reports:
```bash
errlens "is not a function" --json
```
Run a script and write the JSON report directly to a file in CI:
```bash
errlens run test.js --json > ci-report.json
```
In `--json` mode, ErrLens prints only JSON (no spinner, colors, or terminal boxes).
Example response from `run`:
```json
{
"code": 0,
"count": 0,
"matches": []
}
```
Example response from `analyze ` (match found):
```json
{
"code": 1,
"count": 1,
"matches": [
{
"name": "TypeError: Cannot read properties of undefined",
"match": "Cannot read properties of undefined",
"explanation": "You are trying to access a property on a variable that is currently empty.",
"why": "The variable wasn't initialized, or an API call hasn't finished yet.",
"fixes": [
"Use optional chaining: user?.name",
"Set a default value: data || []"
],
"example": "const name = user?.name || 'Guest';"
}
]
}
```
Exit codes (useful for CI):
- `run ` exits with the child process exit code.
- `analyze ` exits with `1` when matches are found (intentional, so CI can fail when known errors are detected), otherwise `0`.
This follows Unix conventions where `0` means success and non-zero means failure. If you prefer success-on-detection in CI, invert the check in your pipeline logic (for example, treat exit code `1` from `analyze ` as a pass condition).
---
## 🧠 System Architecture
ErrLens operates on a three-stage intelligent pipeline to turn confusion into clarity:
| Phase | Component | Description |
|---------------|----------------|-------------|
| Interception | `auto.js` | Hooks into the `uncaughtException` event via a preload script. |
| Matching | `matcher.js` | Uses fuzzy search against `database.json` to find the root cause. |
| Formatting | `formatter.js` | Wraps the diagnosis in a clean, color-coded terminal interface. |
---
## 📁 Project Structure
```
errlens/
├── bin/index.js # CLI Entry point & Command routing
├── lib/
│ ├── matcher.js # Fuzzy search & Logic engine
│ ├── formatter.js # UI & Terminal styling
│ ├── auto.js # Automation & Error interception
│ └── database.json # The "Knowledge Base" (Dictionary)
├── package.json # Dependencies & Metadata
└── README.md # Documentation
```
---
## 🤝 Contributing
We are building the world's most comprehensive dictionary of JavaScript errors, and we need your help!
1. Fork the repository.
2. Add a new error entry to `lib/database.json`.
3. Submit a Pull Request.
💡 **Tip:** Every error you add helps another developer save valuable time. Join the mission!
---
## 📝 License
Distributed under the MIT License. See `LICENSE` for more information.
---
Built with ❤️ by BeyteFlow
Making the terminal a friendlier place, one error at a time.