Clinic.js was a Node.js profiling tool that worked great... until it didn't. NearForm built it around 2017 when Node.js was more stable, but they made a fatal mistake: they tied it too closely to Node.js internals that change every fucking release.
The Death of Clinic.js
Reality check: The GitHub repo now says "not being actively maintained" because maintaining this thing became a nightmare. Every time Node.js updated, something broke. V8 would change profiling APIs, performance hooks would get modified, and suddenly your flame graphs looked like abstract art.
I watched this happen in real time. Clinic.js worked fine on Node 16, then Node 18 came out and half the profiling broke. Something around Node 18.2.0 broke the profiling - suddenly all flame graphs looked like abstract art. Completely useless. The maintainers got tired of playing whack-a-mole with Node.js compatibility. Last release was v13.0.0 in June 2023, then they gave up.
The core problem? Node.js internals aren't meant to be stable APIs. They change them whenever V8 updates or when they need to optimize something. Building a profiling tool on top of that is like building a house on quicksand.
What Clinic.js Actually Did (When It Worked)
OK, rant over. Here's what the thing was supposed to do:
When Clinic.js wasn't broken, it had four tools that were actually pretty useful:
Clinic Doctor was the "start here" tool. Run it, load test your app, and it would tell you "hey, your CPU is fucked" or "you're leaking memory like a sieve." Sometimes it worked, sometimes it just said "use Flame" regardless of the actual problem.
Clinic Flame made flame graphs that actually helped you find slow functions. This was the only tool that consistently worked because flame graphs are just stack sampling. Hard to fuck up, even when Node.js internals change.
Clinic Bubbleprof was the weird one. It made bubble charts showing async operations that looked cool but were basically impossible to interpret. Spent way too much time staring at bubbles trying to figure out why database stuff was slow. Turns out it was just missing indexes. Could've figured that out faster with literally any other tool.
Clinic Heap Profiler tracked memory allocations and was decent at finding obvious leaks. But Chrome DevTools does the same thing without the installation headaches.
The Installation Nightmare
Installing Clinic.js was always a shitshow. First, you needed exactly Node.js 16 because newer versions broke everything:
npm install -g clinic
Half the time this would fail with native module compilation errors, especially on Windows. The tool had native dependencies that didn't play nice with different Node versions.
The "workflow" was supposedly simple:
clinic doctor -- node server.js
Then load test it:
autocannon localhost:3000
Reality: Doctor would crash during profiling or produce reports that said "everything looks fine" while your app was clearly dying. The HTML reports took forever and sometimes got corrupted if you killed the process early. Had this thing crash during a demo once. Spent forever trying to get it working again, still said everything was fine when the app was clearly choking on something stupid like database queries.
The worst part? You'd spend half your day setting up Clinic.js, run it on your slow endpoint, and it would tell you to use Chrome DevTools instead. Which you should have done from the beginning.
