available

guest@reformer:~/theses$ cat X-wrap-dependencies.md

Thesis X: Wrap a dependency before it reaches a thousand call sites.

Nov 2026 · 2 min read · #design

Most dependencies don’t need a wrapper. If a library shows up in three files, you can replace it in an afternoon. A wrapper there only adds a layer to read through.

Some dependencies spread everywhere, though. A UI component library is the classic case. It ends up on every screen, and before long it has thousands of call sites.

A real upgrade

I once worked on a Vue 2 app that used bootstrap-vue directly. To get the new version of bootstrap-vue, we had to move to Vue 3, and Vue 3 changed a lot of the syntax.

Nothing stood between our code and the bootstrap-vue components. So the upgrade touched tens of thousands of call sites across the whole app. It was a long and expensive project, and very little of that work made the product better.

With a wrapper, the same upgrade is a change to each component in our own library. The call sites don’t change at all.

<!-- no wrapper: change every call site -->
<b-button variant="primary" @click="save">Save</b-button>

<!-- wrapper: change one file -->
<AppButton kind="primary" @click="save">Save</AppButton>

When to wrap

Not every dependency needs a wrapper. I ask two questions. Will it appear in a lot of call sites? Would it be really hard to replace later? If both answers are yes, I wrap it now.

Sure, a wrapper costs something on day one. You have to design an interface and keep it up. But that cost is small and it stays the same. The cost of not wrapping grows with every new call site.

A wrapper is cheap to add on the first day. It is very expensive to add on the thousandth.

This is the same idea as a port in hexagonal architecture. Your code depends on an interface you own, and the library sits behind it as an adapter. When the library changes, only the adapter has to change.

Own the components

This is also why I genuinely prefer libraries like shadcn/ui. You don’t install them as a package. They copy the component source into your codebase.

That makes the components your wrapper from day one. You can read them, change them and upgrade them one at a time. When something changes upstream, you update your copy, and the call sites stay the same.