Vue provide/inject: Why You Should Never Skip readonly()

A teammate asks you why cart.total changed. You open the component that renders it — nothing there mutates it. You check its parent — nothing there either. Twenty minutes later you find it: a <PromoBanner> three levels down, nowhere near the cart, called cart.items.push(...) because it had a reference to the object and nobody stopped it. Vue didn't do anything wrong. provide/inject handed that component the exact same reactive object the cart store holds, and JavaScript let it write to what it was handed. The bug isn't in Vue's reactivity — it's in a contract nobody enforced.

By the end of this article you'll be able to:

Who this is for: you've used ref, reactive, and basic provide/inject in a Vue 3 Composition API app, and you want the version of this pattern that survives more than two components.

This is written against Vue 3.5 (verified 3.5.44 on npm's latest tag, October 2026). Everything here is Composition API with <script setup>; there is no Options API equivalent worth writing, since this.$options.provide was always the weaker version of this same idea.

Here's the setup almost every provide/inject tutorial shows, including Vue's own introductory example:

Run this and it works. cart.items updates, the cart badge re-renders, nothing throws. That's exactly why it's dangerous: there is no error to notice, no test that fails, no lint rule that fires. inject("cart") returned the same reactive() proxy the provider created — not a message describing a change, not a frozen snapshot — the object itself. Anything with a reference to it can write to it, from anywhere in the tree, and Vue's reactivity system will faithfully propagate that write, because propagating writes is its entire job.

The bug only shows up later, as a debugging problem: cart.total is wrong, or cart.items has an entry nobody can explain, and the mutation could be coming from any of the components that called inject("cart"). Vue devtools' state inspector will show you the current value, but it won't point you at the nine places across the tree that are allowed to change it.

The mental model: provide/inject is Vue's version of passing a reference down an arbitrarily deep call stack — it shares the exact object, with none of the access control a function's parameters would give you. A prop is already a one-way, shallow-readonly-by-convention handoff that Vue warns about if you mutate it directly. provide/inject has no equivalent warning built in, because the whole point of the API is to skip the explicit, typed handoff of props — and that convenience is also the hole.

Vue's own guide is explicit about the fix, and about whose job it is: "it is recommended to keep any mutations to reactive state inside of the provider whenever possible," and when a descendant genuinely needs to change something, the provider should expose "a function that is responsible for mutating the state" rather than the state's writable surface. That single line is doing a lot of work, and it's easy to skip because unlike a type error, skipping it doesn't break anything today.

The fix is two changes to the provider, and zero changes to how descendants read the value.

Now the PromoBanner from earlier doesn't quietly succeed:

readonly() wraps the value in a second proxy that intercepts writes and, in development, logs a warning naming the exact key that was targeted instead of silently applying — Vue's reactivity docs show this same message for a plain mutation attempt on a readonly() copy of a reactive object. The write doesn't happen; the original, writable cart inside the provider is unaffected. PromoBanner has no way to change the cart except by calling the addItem function it was also given — which means every mutation path is now a named function you can grep for, breakpoint, or log.

readonly()'s wrapping is deep: nested objects and arrays reached through the readonly proxy are themselves readonly, so cart.items.push(...) is caught, not just reassigning cart.items itself. If you only need the top level protected (rare, and usually a sign the shape should be flatter), shallowReadonly() exists, but reach for plain readonly() by default — a one-level gap is exactly where the next PromoBanner finds the one key that still writes.

String keys ("cart") work but give TypeScript nothing to check — a typo in the key, or injecting before the provider ever renders, both fail silently at runtime. InjectionKey<T> fixes both:

The symbol key means a typo can't collide with an unrelated provide("cart", ...) elsewhere in the tree, and inject()'s return type is now narrowed to DeepReadonly<CartState> | undefined — the undefined is real, because inject without a default genuinely returns undefined when there's no matching provider above the component, and the type system now makes you prove you've considered that.

Reach for provide/inject (with this pattern) when the state is genuinely tree-scoped — a form wizard's shared step state, a modal's context, a design-system component's configuration — and you want to avoid prop-drilling it through components that don't care about it.

Pair every provide() of mutable state with:

Reach for Pinia instead when the state needs to be read or changed from components that aren't descendants of a single provider — a cart that's also read from the header nav and a checkout page outside that subtree, for instance. provide/inject is scoped to a component subtree by design; a store isn't. Using provide/inject for truly global, cross-tree state usually means re-providing it near the root anyway, at which point a store does the same job with less wiring.

No. readonly(cart) returns a new proxy; the original cart reference the provider holds is still the plain reactive() object, fully writable. Only the reference that goes through provide() is wrapped.

The wrapping itself is cheap — it's a proxy, created once, not a deep clone. Reads are tracked the same way reactive() reads are. You won't notice this on anything short of a very large, deeply nested object being read in a tight loop, and that's a different problem to measure separately.

Yes, and that's correct, not a hole. If the provider exposes addItem(), a child calling addItem() is mutating state through the one sanctioned path — that's the entire point. readonly() blocks direct property writes on the injected value; it was never meant to block the mutator functions you provide alongside it.

No — it's the right tool for state scoped to one part of the tree, not a general store replacement. See "Best practices" above for the line between them.

Without a default, inject() returns undefined at runtime. With InjectionKey<T>, TypeScript types that return as T | undefined, so a missing provider becomes a type error you fix during development instead of a crash a user finds. You can also pass a default as inject(key, defaultValue).

▶️ Open the interactive playground →

Runs right in your browser — poke at it and watch the concept react live.

Think it clicked? Take the 8-question quiz →

Instant feedback, a hint on every question, and an explanation for each answer — right or wrong.

That PromoBanner bug from the top is now impossible to write by accident: there's no writable cart to reach for, only an addItem call that shows up in a stack trace with your name on it. The next time inject() hands back an object, ask the one question this article is about: can whoever holds this write to it, and did you mean for them to?

What's the messiest provide/inject mutation bug you've chased down? Drop it in the comments — there's a good chance someone else is debugging the exact same shape right now.

🚀 Want more like this? Every guide, playground, and quiz lives on bestpractic.org — open it and sign up free so the next one finds you.

Thanks for reading! Let's stay connected: