It was 4:45 on a Friday when a teammate Slacked the whole engineering group a link. A charting library, gorgeous demo page, animated transitions, forty stars on GitHub added that afternoon. He wanted it in the next sprint. I said we should look at it properly on Monday. Instead, someone merged it over the weekend because the demo was compelling and the current charts were ugly.
Three years later that decision had its own Jira epic. The bundle had grown past the size of the rest of the app combined. Two of its props were undocumented and had changed meaning in a minor release. The maintainer had moved on to a different language and the issue tracker was a museum of polite unanswered questions. We replaced it in the end, and the replacement took four months. All of that pain was available for inspection on the Friday, in about two hours. Nobody looked.
Here is the checklist I have been using ever since.
The issue tracker tells the truth
The README is the sales page. The issue tracker is the support log, and it cannot fake a relationship with users.
I read the twenty most recent closed bugs. How fast did maintainers respond? What did the first response look like? A pattern of “works as intended, closing” with no reproduction attempt is a person who has stopped being curious about their users. A pattern of questions, patches, and follow-up comments is a healthy project even when the release cadence is slow. I also search for the words I would type on my worst day: memory leak, types, tree shaking, server rendering, accessibility. Whatever I find there is what my future self will find there.
What I actually check
Release hygiene comes next. Last release date, changelog quality, and whether breaking changes ever ride in on minor versions. A project that respects semantic versioning is a project that respects your weekends. Count the humans who ship releases, too. One maintainer is fine for a small utility and a genuine risk for anything load-bearing, and commit counts hide this because half of them are bots.
Dependencies are supply chain surface. I run `npm ls –all | wc -l` before I feel anything, and then I look at what the tree is holding. Every package in there is another account that can be hijacked, another install script, another license to inherit. A library with zero dependencies that does one thing is a different category of object than a library with eighty.
Types matter as an honesty signal. Good type definitions show that the maintainers imagine other people consuming this. Types that live in a separate repository a major version behind are a rolling tax on your team.
Licenses get checked before adoption, never after. MIT and Apache-2.0 are usually fine where I have worked; GPL and AGPL need a conversation; anything with a custom name gets read word by word. The license of your dependencies is your license.
Size claims get measured, never believed. The badge on the README is a marketing artifact. I drop the library into an empty Vite or webpack project, import the one function I need, build for production, and weigh the output. Tree shaking that works in the author’s example can fall apart the moment you import the entry point instead of the leaf.
The two-hour spike
Demos show the first use case. I build the second one, the use case the demo skipped. For the charting library that meant: what does it do with zero data, with ten thousand points, with a label in Arabic, with a container that resizes? For a form library: nested fields, async validation, server errors. For a data grid: pagination, sorting, keyboard navigation, and what happens at page one hundred.
Time-box it at two hours and write down what breaks. The point is a record, because future arguments about the library get settled by that document instead of by whoever sounds most confident in the meeting.
I also try it in the boring conditions: production build, strict mode, the oldest browser the company still supports, and a slow network. Whatever the library does in the demo is the ceiling of what you know about it. Everything you find in the spike is information that compounds.
The exit question
Before we adopt anything, I write down how we would get off it in a week. Data out: can I export everything this thing is holding, in a format the next tool can read? Code out: is it wrapped behind one module of ours, or do its types and idioms run through the whole codebase? That paragraph is a gift to whoever runs this team in 2029.
This is also where the difference between packages and services sharpens. Plenty of libraries these days arrive as the client of a hosted product, and the same checklist applies, with one extra question: where does our data live, and how fast can we take it home? The evaluation stays the same; the exit cost just gets bigger.
What the checklist buys you
All of this together adds up to an informed bet, and over a career the informed bets average out in your favor. The library we adopted that Friday might have been fine. The problem was the way we chose it: a demo, some enthusiasm, and no record of what we were signing up for.
Software decisions age like loans. You borrow a bit of speed this sprint and pay interest every release afterward. The checklist is just the habit of reading the terms before you sign, and the two hours it costs is the cheapest insurance I know of in this line of work.
