Skip to Content
v0.8.0 · shippedNative iOS / Android / Flutter / Capacitor SDKs, A2A discovery, SOC 2 readiness, residency, BYO storage, BYOK. Read the changelog →
Migration guidesVue 2 → Vue 3

Vue 2 → Vue 3

Days Med risk

Vue 2 reached end-of-life on 2023-12-31. Most apps have already migrated; this guide covers the holdouts and the Mushi-specific pieces.

The Mushi Vue adapter (@mushi-mushi/vue) supports Vue 3 only. Apps still on Vue 2 must use the vanilla @mushi-mushi/web SDK; this guide brings you onto the adapter.

Vue 2 is no longer receiving security patches. The Vue team’s official recommendation is to migrate. If you cannot, HeroDevs ships a paid LTS  for Vue 2.7 with security backports.

What changes (high level)

  • new Vue({...}).$mount(...) → createApp(App).mount(...)
  • Options API still works in Vue 3, but the Composition API is the recommended style. You can mix both during the migration.
  • Filters are gone. Methods or computed properties replace them.
  • Functional components must be converted to regular components or use defineComponent with functional: true removed.
  • v-model on a custom component changed semantics — see the Vue 3 migration guide .
  • Vue Router 3 → 4. Vuex 3 → 4 (or Pinia, recommended).
  • Mushi: @mushi-mushi/web direct usage → @mushi-mushi/vue adapter.

API mapping (Mushi-specific)

Vue 2 (with @mushi-mushi/web)Vue 3 (with @mushi-mushi/vue + @mushi-mushi/web)
Mushi.init({ projectId, apiKey }) in main.jsSame Mushi.init(...) PLUS app.use(MushiPlugin, { projectId, apiKey })
Manually attach Vue.config.errorHandler = ... to forward to MushiThe adapter wires Vue 3’s app.config.errorHandler automatically
Reach into Mushi directly from any componentUse useMushi() composable inside <script setup>

Migration checklist

Migration checklist
10 required steps
  1. Step 01
    Run vue-compat (the bridge build)
  2. Step 02
    Fix every Vue 2-style deprecation warning
  3. Step 03
    Remove @vue/compat alias once warnings are zero
  4. Step 04
    Upgrade Vue Router 3 → 4
  5. Step 05
    Decide: Vuex 4 or Pinia
  6. Step 06
    Install the Mushi Vue adapter
  7. Step 07
    Replace direct Mushi.init usage with the adapter
  8. Step 08
    Migrate components to useMushi()
  9. Step 09
    Remove any Vue-2-era Mushi error-handler shims
  10. Step 10
    Smoke-test: throw an error, verify it lands as a Mushi report

Common gotchas

  • Forgetting Mushi.init() after app.use(MushiPlugin, ...). The Vue plugin only wires the composable + error handler; it does NOT mount the visual widget. You need both calls. (This is also why the in-console Install SDK card emits both lines — it caught a previous regression where users thought one was enough.)
  • <script setup> and Options API mixing. Both work in Vue 3, but useMushi() only works inside setup() / <script setup> because it’s a composable. For Options API components, use inject('mushi') (the plugin provides it).
  • Stale Vue 2 plugins. Some older Mushi-adjacent plugins (Sentry-Vue v6, Vue-Logger v1) only support Vue 2. Audit your plugin list.

Mushi behaviour during the migration

You can run just @mushi-mushi/web in compat mode and it works. The adapter is purely additive — it gives you a nicer composable API and auto-wires the error handler. Migrate Mushi to the adapter only after your app is on real Vue 3 (compat alias removed).

References

Last updated on
Next.js Pages → App RouterSPA → SSR