Vue Composables: The Shared State Trap (+ Cheat Sheet)

You build a useCounter() composable, drop <Counter /> on the page twice, and click the first button. Both counters go up.

You didn't copy-paste a bug. You wrote twelve lines of completely ordinary-looking Composition API code, and Vue executed every one of them correctly. The surprise isn't a Vue bug — it's a gap in your mental model of what a composable actually is, and that gap is exactly where a much more expensive version of this same mistake lives: on a server, where "the other counter" is a different user's browser tab.

What you'll learn

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

• Explain why two calls to the same composable sometimes share state and sometimes don't
• Predict it from reading the composable's source, without running the app
• Deliberately design shared (singleton) state when you actually want it
• Clean up a composable's side effects so they don't outlive the component that created them
• Recognize why this exact bug is more dangerous in server-rendered Vue than in the browser
• Keep the cheat sheet at the end open while you build your next composable

Who this is for

You've written at least one composable — a use* function that returns some refs and functions from <script setup>. You don't need to have hit this bug yet; you will recognize it the moment you see it. If ref vs reactive is still fuzzy, Vue Reactivity Explained: ref vs reactive is a good five minutes first — this article builds on it but doesn't require it.

This article is written against Vue 3.5.42, the current stable release (verified via the npm registry, September 2026). Vue 3.6 is still in release candidate; nothing here changes under it — composables are a code-organization pattern, not a runtime feature that Vapor Mode alters.

Table of contents

• The problem: two counters, one number
• The mental model: a composable is just a function
• Stage 1: state that lives inside the function
• Stage 2: composables with side effects need cleanup
• Stage 3: composables that call other composables
• Stage 4: when shared state is what you actually want
• Edge cases and gotchas
• Best practices
• FAQ
• Cheat sheet

The problem: two counters, one number

Here's the composable, written the way it looks in a hundred tutorials:

// useCounter.js
import { ref } from 'vue'

const count = ref(0) // looks like "the counter's state" — but whose?

export function useCounter() {
  function increment() {
    count.value++
  }
  return { count, increment }
}

And here's a component that uses it, dropped onto a page twice:

<!-- Counter.vue -->
<script setup>
import { useCounter } from './useCounter'
const { count, increment } = useCounter()
</script>

<template>
  <button @click="increment">Count: {{ count }}</button>
</template>

<!-- Page.vue -->
<template>
  <Counter />
  <Counter />
</template>

Click the first button five times. Both buttons read Count: 5. Nothing crashed, nothing warned you — useCounter() did precisely what its source says: return the one count that exists.

The bug is not in <Counter />. It's a single misplaced line in useCounter.js — and to see which line, you need the rule that explains both the broken version and the correct one.

The mental model: a composable is just a function

A composable has no special relationship to "a component's state." It's a plain JavaScript function, and JavaScript's own scoping rules decide everything.

• State declared inside the function body is created fresh every time the function runs. Since <Counter /> calls useCounter() once per component instance, each instance gets its own ref — private state.
• State declared outside the function — at module scope, in the file that defines it — is created exactly once, the first time anything imports the module. Every subsequent call to useCounter() returns a reference to that same ref. That's not a bug in the composable pattern; it's how ES modules always work, for the same reason a module-level let cache = new Map() is shared by every caller too.

Vue's Composition API rules (ref, reactive, onMounted, provide/inject, …) never asked where you put your const. You decided that, with ordinary variable scope, before Vue ever entered the picture. The composable naming convention (useXxx) signals what it does, not how many copies of it exist — that second question is answered by reading exactly one thing: is this ref() call inside the exported function, or outside it?

That's the whole model. Everything below is a consequence of it.

Stage 1: state that lives inside the function

Move count inside useCounter, and each call becomes its own closure over its own ref:

// useCounter.js — fixed
import { ref } from 'vue'

export function useCounter(start = 0) {
  const count = ref(start) // created fresh, once per CALL, not once per FILE
  function increment() {
    count.value++
  }
  return { count, increment }
}

Key concept: nothing about the export changed — same function name, same return shape. Only the scope of count moved from module-level to function-level. Now two <Counter /> instances each run useCounter() independently, each closing over its own count, and clicking one leaves the other alone.

This is the default you want almost every time. If you're writing a composable and you haven't deliberately decided otherwise, put the state inside the function.

Stage 2: composables with side effects need cleanup

Composables aren't only about state — they often start something that needs to be stopped. A classic:

// useMousePosition.js
import { ref, onMounted, onUnmounted } from 'vue'

export function useMousePosition() {
  const x = ref(0)
  const y = ref(0)

  function update(e) {
    x.value = e.clientX
    y.value = e.clientY
  }

  onMounted(() => window.addEventListener('mousemove', update))
  onUnmounted(() => window.removeEventListener('mousemove', update)) // <- easy to forget

  return { x, y }
}

Drop the onUnmounted line, and every component that ever used this composable leaves a mousemove listener attached to window forever, each one still running its update closure against a ref nobody reads anymore. It's not a crash — it's a slow, silent leak that only shows up as "the page gets janky after navigating around for a while."

Key concept: a composable's lifecycle hooks (onMounted, onUnmounted, onScopeDispose) tie the side effect to whichever component (or, as Stage 3 shows, effect scope) called the composable. If you start something, you are responsible for stopping it in the matching hook — Vue does not infer the teardown from the setup.

Stage 3: composables that call other composables

Composables compose — useMousePosition might be built from a lower-level useEventListener:

// useEventListener.js
import { onMounted, onUnmounted } from 'vue'

export function useEventListener(target, event, handler) {
  onMounted(() => target.addEventListener(event, handler))
  onUnmounted(() => target.removeEventListener(event, handler))
}

This works fine called from <script setup>, because onMounted/onUnmounted register against the currently running component instance — and during setup(), there is one. It breaks the moment you call it from somewhere that isn't a component, like a Pinia store's setup function running at app-init time, or a plain test file: there's no "current instance" for the hook to attach to, Vue logs a dev warning, and the callback simply never fires.

The general-purpose fix is onScopeDispose, which ties into Vue's effect scope instead of specifically a component instance — and a component's own setup function is itself one:

import { onScopeDispose } from 'vue'

export function useEventListener(target, event, handler) {
  target.addEventListener(event, handler)
  onScopeDispose(() => target.removeEventListener(event, handler))
}

Key concept: onScopeDispose fires whenever the enclosing effect scope tears down — a component unmounting, or an effectScope().stop() call you make yourself outside any component. It's the one cleanup hook that works the same whether the composable is called from a component or from plain code, which is exactly what a composable meant to be reused outside components needs.

If you skipped Vue Reactivity Explained, the same destructuring rule from that article applies here too: if useEventListener returned a reactive() object instead of individual refs, destructuring it in the caller would silently drop reactivity. Composables should almost always return an object of refs (or use toRefs on a reactive one) so a caller can safely write const { x, y } = useMousePosition().

Stage 4: when shared state is what you actually want

Sometimes module-scoped state is the correct design, not a bug — a logged-in user, a theme preference, a WebSocket connection every component should see the same instance of. The fix isn't "always put state inside the function"; it's "put it outside the function on purpose, and say so":

// useAuthUser.js — a deliberate singleton, not an accident
import { ref, readonly } from 'vue'

// Module scope, intentionally: every caller across the whole app
// shares this exact user. This is a global store, not per-call state.
const _user = ref(null)

export function useAuthUser() {
  function login(user) {
    _user.value = user
  }
  function logout() {
    _user.value = null
  }
  // readonly() stops callers from doing `user.value = ...` directly —
  // every write goes through login()/logout(), which is the whole point
  // of centralizing this state in the first place.
  return { user: readonly(_user), login, logout }
}

Key concept: the code that makes this a singleton is identical in shape to the bug from the opening example — a ref declared outside the function. The difference is entirely in intent and in guarding the write path. A comment explaining why this one is module-scoped is not decoration; it's the one piece of information a reader can't get from the code's shape, because the shape is the same as the accidental version.

Edge cases and gotchas

• Server-side rendering makes this bug worse, not just different. In the browser, a module-scoped ref is shared across components in one user's page — annoying, but contained. On a Vue SSR server (Nuxt or a custom setup), a Node process typically renders many different users' requests using the same loaded module. A ref created at module scope is created once when the server starts, not once per request — so useAuthUser's state can leak from the user who requested it first into the response sent to the next user. This is the single most important reason "does this composable's state live inside or outside the function" is worth getting right on purpose, not by habit.
• Testing a composable outside a component throws or warns. Calling onMounted/onUnmounted with no active component instance triggers a dev-mode warning and does nothing. Wrap the call in effectScope() when unit-testing a composable directly, so lifecycle-style hooks (onScopeDispose) have somewhere to attach:

  import { effectScope } from 'vue'
  const scope = effectScope()
  scope.run(() => {
    const { count, increment } = useCounter()
    increment()
    expect(count.value).toBe(1)
  })
  scope.stop() // triggers any onScopeDispose cleanup registered inside

• Hot Module Replacement can hide the bug in dev. Vite's HMR sometimes re-executes a module and resets its module-scope state, which can make a shared-state leak look fixed after a save — then reappear on a full reload. Don't trust "it works now" from an HMR session; reload the page.
• getCurrentInstance() is not the fix. It's tempting to reach for it to detect "am I inside a component," but it's explicitly documented as an internal API for advanced/library use, not a general escape hatch — prefer designing the composable so it doesn't need to know.

Best practices

• Default to state inside the function. Only hoist state to module scope when you specifically want one shared instance across the whole app.
• Say so when you do. A one-line comment ("module-scope singleton, shared across the app") costs nothing and saves the next reader from re-deriving your intent from scope rules.
• Return refs, not a raw reactive() object, so callers can destructure without losing reactivity.
• Clean up every side effect a composable starts — a listener, a timer, a subscription — with onUnmounted for component-only composables, onScopeDispose for anything meant to be reusable outside a component.
• For real app-wide state, reach for Pinia once it grows past one or two values. It gives you the same "one shared store" idea, but with devtools time-travel, SSR-safe store instantiation per request, and a name (defineStore) that makes "this is intentionally shared" obvious from the import alone.

FAQ

Why didn't Vue warn me that my composable's state was shared?

Because there's nothing to warn about — const count = ref(0) at module scope is completely valid JavaScript and Vue reactivity, doing exactly what it's written to do. The "bug" is a mismatch between your intent and the code's actual scope, which no linter can read your mind about.

Does this affect provide/inject the same way?

No — provide/inject is scoped to the component tree by design; each provider creates its own value for its own descendants, so two unrelated component trees don't share it. The module-scope trap is specific to state declared directly in a .js file outside any function.

Is a composable just a React-style custom hook?

They solve the same problem — extracting stateful logic into a reusable function — but the mechanics differ. A composable's refs are proxies you can read anywhere without a special calling rule, and there is no "rules of hooks" about call order; a custom hook's state is closed over by React's fiber and re-runs the whole function on every render. The shared-state trap in this article has no React equivalent, because React hooks don't have a module-scope option — useState is always per-component.

Should every composable clean up after itself, even ones that don't touch the DOM?

If it started anything — a listener, an interval, a subscription to something outside Vue's reactivity — yes. If it only computed derived values from its inputs (computed, plain functions), there's nothing to clean up; computed refs are garbage-collected with everything else that stops referencing them.

Can I tell from the outside whether a composable shares state?

Only by reading its source (or its docs). The call site — const { count, increment } = useCounter() — looks identical either way. That asymmetry is exactly why Stage 4's naming/comment convention matters: the information isn't visible where you'd need it most.

🎮 Try it yourself

▶️ Open the interactive playground →

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

Cheat sheet

Key takeaways

• A composable is a function first; JavaScript's own variable scope — not anything Vue-specific — decides whether its state is private per call or one shared singleton.
• State inside the function body is the safe default; state outside it is a deliberate design choice that deserves a comment.
• Every side effect a composable starts needs a matching cleanup, via onUnmounted or the more general onScopeDispose.
• The same "module scope = shared" rule that causes two counters to double-count in the browser can leak one user's data into another user's response on an SSR server — treat it as a correctness issue, not just a UI quirk.

🧠 Test yourself

Think it clicked? Take the 7-question quiz →

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

Ending

Those two counters that moved together weren't broken — they were exactly one ref doing exactly what a ref declared outside a function always does. Once you can see that scope decision sitting in the source, every "why are these two components sharing state" question stops being a mystery and starts being a one-line answer you can find by reading, not debugging.

Where has this bitten you — a shared composable, or the SSR version of it? Tell me in the comments.

🚀 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:

• ⭐ GitHub — follow me and star the projects: github.com/parsajiravand
• 💬 Discord — join the frontend best-practices community: discord.gg/d9KRhuAwQ
• 📸 Instagram — frontend best practices, daily: @bestpractice___