Dependency Injection

Dependency Injection: Scalable Provider Trees with Symbol Keys

Dependency injection in the Vue 3 Composition API lets ancestor components or plugins supply shared services, configuration, and state managers cleanly across an entire component tree.

While simple cases use plain string keys with provide() and inject(), large multi-team applications benefit from JavaScript Symbol() keys and readonly() state wrappers. Those safeguards prevent key name collisions and protect shared state from accidental mutations.

flowchart TD
    Key["AuthServiceKey = Symbol('AuthService')"] --> Provider["App.vue: provide(Key, readonlyState)"]
    Provider --> ConsumerA["Navbar.vue: inject(Key)"]
    Provider --> ConsumerB["Dashboard.vue: inject(Key)"]

Patterns for Clean Architecture

• Unique Symbol() Keys: Export symbols from a dedicated keys.js module so third-party plugins or unrelated features never clash on string names.
• readonly() Protection: Wrap provided reactive objects in readonly() so consumers can read reactive values without mutating them directly.
• Explicit Mutation Methods: Expose action functions alongside the readonly state so every state change flows through one controlled place.

Practical SFC Dependency Injection Example

First, export a shared Symbol key from src/keys/authKeys.js.

export const AuthServiceKey = Symbol('AuthService');

Next, wrap authState with readonly() in App.vue and provide it with a logout action.

<script setup>
import { reactive, provide, readonly } from 'vue';
import { AuthServiceKey } from './keys/authKeys';
import UserDashboard from './components/UserDashboard.vue';

const authState = reactive({
  user: { name: 'Alex', email: '[email protected]' },
  isAuthenticated: true
});

function logout() {
  authState.user = null;
  authState.isAuthenticated = false;
}

provide(AuthServiceKey, {
  state: readonly(authState),
  logout
});
</script>

<template>
  <main>
    <UserDashboard />
  </main>
</template>

Finally, consume AuthServiceKey inside UserDashboard.vue using inject().

<script setup>
import { inject } from 'vue';
import { AuthServiceKey } from '../keys/authKeys';

const authService = inject(AuthServiceKey, null);
</script>

<template>
  <div class="user-panel">
    <div v-if="authService?.state.isAuthenticated">
      <h3>Welcome, {{ authService.state.user.name }}</h3>
      <button @click="authService.logout">Log Out</button>
    </div>
    <p v-else>Please sign in to continue.</p>
  </div>
</template>

Common Mistakes

• Creating New Symbols Inside Each File: Calling Symbol('Auth') separately in two files produces two distinct symbols that never match. Always export one shared Symbol constant.
• Passing Mutable Reactive Objects Without readonly(): Letting any child component mutate injected properties makes state bugs hard to track across large trees.
• Forgetting Factory Functions for Expensive Defaults: If a fallback default value creates a class instance or heavy object, pass a factory function with true as the third argument: inject(Key, () => createDefault(), true).

Frequently Asked Questions

How do I add TypeScript types to Symbol() injection keys?

Import InjectionKey from 'vue' and type the symbol: export const AuthKey: InjectionKey<AuthContext> = Symbol('Auth'). Both provide and inject then infer types automatically.

Can a child component override a provided value for its own subtree?

Yes. Calling provide(AuthServiceKey, mockAuth) in an intermediate component overrides that key only for its own descendants.

Does readonly() block the provider itself from updating state?

No. The provider keeps a reference to the original authState and updates it normally; readonly(authState) only returns a read-only proxy view for consumers.