Taming the Store: Migration Patterns and Refactoring Pain in Vue Applications by

When working with Vue applications, the store often becomes the backbone of business logic, workflows, and shared state. Over time, however, the way we access and interact with the store has evolved — creating a mix of patterns in large codebases. These transitions, while natural, can become troublesome when teams need to refactor components or adopt new best practices.

In this article, we’ll walk through common migration patterns observed in real-world Vue projects, explore why they complicate refactoring, and suggest future-ready approaches for maintainable store usage.

The Evolution of Store Patterns

1. Legacy: Direct this.$store Access

In early Vue 2 projects, it was common to call the store directly from a component. While simple, this approach tightly couples components to the store, making every reference to this.$store a target for refactoring. Namespacing issues and unclear dependency surfaces only add to the pain.

JavaScript

export default {
  mounted() {
    this.$store.dispatch('fetchData');
  },
  computed: {
    items() {
      return this.$store.state.items;
    }
  }
}

2. Transitional: Vuex Helpers (mapGetters, mapState, mapActions)

Vuex introduced helpers that made state and actions feel more “declarative.” This improved readability and testability, but the component is still heavily tied to Vuex. Refactoring a store module still meant changing multiple scattered references across components.

JavaScript

import { mapState, mapActions } from 'vuex';
export default {
  computed: {
    ...mapState(['items'])
  },
  methods: {
    ...mapActions(['fetchData'])
  }
}

3. Modern: useStore() with the Composition API

With Vue 3 and the Composition API, store usage became more explicit and flexible. All store usage is localized inside setup, making it easier to refactor. Dependencies are explicit, and components are more predictable.

JavaScript

import { useStore } from 'vuex';
import { computed, onMounted } from 'vue';

export default {
  setup() {
    const store = useStore();
    const items = computed(() => store.state.items);
    onMounted(() => {
      store.dispatch('fetchData');
    });
    return { items };
  }
}

4. Future-Ready: Custom Composables

The next step in modernization is abstracting store access into domain-specific composables. Now, components consume a clear API surface, free from direct store wiring. This dramatically reduces refactor effort; changing store modules no longer requires touching dozens of components.

**useAgentClassification.js**

JavaScript

import { useStore } from 'vuex';
import { computed } from 'vue';

export function useAgentClassification() {
  const store = useStore();
  const classifications = computed(() => store.state.classification.items);
  const fetchClassifications = () =>
    store.dispatch('classification/fetch');
  return { classifications, fetchClassifications };
}

Component using the composable

JavaScript

import { useAgentClassification } from '@/composables/useAgentClassification';

export default {
  setup() {
    const { classifications, fetchClassifications } = useAgentClassification();
    return { classifications, fetchClassifications };
  }
}

Why Refactoring Becomes Troublesome

Across these patterns, the core pain points are:

• Scattered references: this.$store, mapState, and mapActions spread logic across multiple places.
• Hidden coupling: Components often depend on module names and mutation/action strings, making them brittle.
• Cross-module complexity: Root actions calling module actions create chains that are hard to trace.
• Persistent view state: Local storage introduces side effects that complicate debugging.
• Workflow depth: Audit flows, debounced filtering, and role-based control all increase the surface area of store dependencies.

When teams need to rename a module, split responsibilities, or upgrade architecture, these patterns create ripple effects across the codebase.

Recommendations for a Modern Store Architecture

• Adopt composables for domain logic: Create useFooStore() hooks that wrap store access. Abstract debounced filtering, audit workflows, and role checks inside composables.
• Favor explicit imports over magic helpers: Avoid mapState and mapActions in new code. Use useStore directly in the Composition API.
• Separate state concerns: Use composables for view state (e.g., localStorage-backed). Reserve Vuex for business workflows and cross-module communication.
• Design for refactorability: Encapsulate store usage in one place per domain. Document module boundaries and enforce them with TypeScript where possible.

Conclusion

Store patterns in Vue have matured significantly, but legacy and transitional patterns often linger in codebases. While this.$store and mapState were useful stepping stones, they introduce friction during large-scale refactors.

The way forward is clear: move toward composables that abstract store access, align state management with domain boundaries, and embrace the Composition API consistently. By doing so, you’ll make your Vue codebase more future-proof, easier to refactor, and more pleasant for developers to work with.