Run a time-boxed spike: define the job in writing, try the library on real inputs in a throwaway branch, check license and security signals, and write a one-paragraph verdict. Two hours is enough for most libraries. If you cannot decide by then, the answer is usually no.
Why time-box it
Open-ended evaluations drift into prototypes, and prototypes become production code with nobody having made a decision. A fixed box forces a verdict and keeps the throwaway branch throwaway.
The plan, hour by hour
Minutes 0 to 15: define the job. Write down the inputs, outputs and failure behavior you need. Add two awkward cases: a malformed input and a large one.
Minutes 15 to 60: try it. In a scratch branch, install the library at a specific version and run your real inputs. Do not paste production secrets or customer data into a test. Use sanitized samples.
Minutes 60 to 90: check the signals. Use the checklist from our library selection checklist: license, security policy, advisories, maintenance, footprint.
Minutes 90 to 120: decide and record. Write one paragraph: adopt, adopt with a wrapper, or reject, with the three facts that drove it.
What to look for while trying it
| Observation | Why it matters |
|---|---|
| Install output lists many extra packages | Large transitive footprint to own |
| Install runs scripts | Code executes on your machines at install time; see npm install script security |
| Errors are vague or swallowed | Hard to debug in production |
| Malformed input crashes or hangs | Possible denial of service path |
| Docs and behavior disagree | Higher chance of surprises later |
Check the install, not just the API
When you install in a spike, look at what was added. The npm documentation describes lifecycle scripts such as preinstall, install and postinstall that run during installation, which is a reason to review what a new package would execute. Trying a new package inside a disposable container or virtual machine limits the blast radius while you evaluate it.
Writing the verdict
A usable verdict is short and specific:
- Decision: adopt with a wrapper.
- Version tested: the exact version.
- Evidence: handled our malformed samples, has a security policy, last release within the year, three transitive packages.
- Open risks: single maintainer; we will watch for advisories and keep an exit plan.
Keep it in the pull request description. Six months later, it is the document that answers "why did we pick this?".
Common spike mistakes
- Evaluating on the library's own examples instead of your data.
- Skipping the license check because the code works.
- Adopting the scratch branch directly, with its shortcuts.
- Testing the latest version in the spike and a different one in production.
Where Safeguard fits
After a library is adopted, Safeguard's dependency scanning and continuous monitoring can track it for new advisories, and policies can enforce rules in pull requests. Run a free scan at gold.safeguard.sh/scan.
Quick check
What if two hours is not enough?
Extend once, for a stated reason. If the library still is not clearly right, choose the simpler option or write the small piece yourself.
Should security review every spike?
No. Engineers run the checklist; involve security for sensitive domains or for unresolved asks.
Sources
Last reviewed: 19 October 2026.
