Creating Reusable Composables in Vue.js 3

Anton Ioffe - December 29th 2023 - 9 minutes read

As modern web development continues to evolve, Vue.js 3 stands at the forefront of this transformation, offering powerful constructs to enhance code reusability and maintainability. In this article, we delve into the realm of architecting robust and reusable composable functions, leveraging the full breadth of Vue's Composition API. We will guide you through the art of composing composables, untangle the reactive intricacies of state management, and explore advanced techniques for complex state handling. We’ll also examine how these composables seamlessly integrate with state management solutions like Vuex and Pinia, and conclude with insightful strategies for testing and gracefully refactoring your existing codebase. Whether you are looking to streamline your development process or enrich your applications with modular, maintainable components, this comprehensive exploration is your blueprint to mastering the power of composables in Vue.js 3.

Composing Composables: Design Patterns and Best Practices

In approaching the design of effective composables, it is crucial to encapsulate logic in a way that promotes clarity and reusability. Encapsulation is achieved by ensuring that each composable addresses a single concern, thereby adhering to the principle of separation of concerns. This design pattern not only simplifies understanding and maintenance but also fosters a more modular and scalable codebase. For instance, a composable such as useApi might exclusively handle API calls and related logic, while useFormValidation could encapsulate validation logic for user inputs. This distinct separation makes composables easier to swap, combine, and improve without causing ripple effects throughout the application.

When writing composable functions, adopt clear and consistent naming conventions that reflect their purpose and functionality. A well-named composable function like useLocalStorage immediately conveys its utility in managing local storage interactions, which aids in both readability and discoverability among team members. By following this pattern, developers can quickly grasp the scope and capability of a given composable, leading to heightened efficiency and a codebase that is easier to navigate.

Best practices in crafting composables advocate for purity and simplicity in their implementation. Composable functions should ideally be pure in that they possess no side effects, and their output should solely depend on their input. Simplicity can be attained by limiting the responsibilities of each composable. Avoid the temptation to overload a composable with multiple, loosely related features as this complicates testing and reuse. When complexity arises, consider decomposing the composable into smaller, cohesive units, each targeting a specific aspect of functionality.

Modular architecture in Vue.js applications is further reinforced through the alignment of composables with domain-specific logic. By organizing composables around distinct application domains, developers can enhance modularity and foster code that aligns closely with the business logic it represents. In a larger application, structuring your directory to reflect different domains such as authentication, user profiles, or payment systems, and subsequently creating composables within these domains, can accelerate development and make the codebase more intuitive for new developers.

Furthermore, embracing simplicity in the API design of composables ensures their ease of use and reusability. A best practice is to provide a straightforward and predictable interface, usually consisting of a reactive state, computed properties, and functions. This uniformity allows other developers to integrate and combine composables with minimal learning curve. As a rule of thumb, when a composable's interface becomes complicated or hard to understand, it's likely a signal that it should be refactored into more granular, focused composables. By adhering to these best practices, Vue.js developers can craft a harmonious and efficient codebase that fully realizes the potential of the Composition API.

State Management and Reactive Principles in Composables

Managing state in Vue.js composables requires an intricate understanding of Vue's reactivity system to forge dynamic and responsive applications. Vue 3 entrusts developers with ref, reactive, and computed constructs for maintaining reactivity within composables. ref is particularly adept for wrapping primitive values in a reactive cloak, ensuring updates reverberate through to re-renderings. Here's a basic usage within a counter composable:

import { ref } from 'vue';

export function useCounter() {
    const count = ref(0);

    function increment() {

    return { count, increment };

For structuring more intricate state, reactive dives in as a savior, enabling developers to fashion a responsive state object:

import { reactive } from 'vue';

export function useUser() {
    const user = reactive({
        firstName: '',
        lastName: ''

    function updateFirstName(name) {
        user.firstName = name;

    return { user, updateFirstName };

To derive state efficiently, computed properties facilitate the creation of responsive values that adaptively update whenever their reactive dependencies shift:

import { computed } from 'vue';

export function useFullName(user) {
    const fullName = computed(() => `${user.firstName} ${user.lastName}`);

    return { fullName };

However, the sophistication of Vue's reactivity prompts developers to meticulously balance reactivity's spectrum to optimize for performance. Judicious reactivity minimizes render updates, preserving computing resources—particularly when sidestepping deep nesting and ensuring a minimal reactive surface area. Employing watch mechanisms like watch or watchEffect can circumnavigate performance landmines by targeting specific sources of reactivity:

import { reactive, watch } from 'vue';

export function useSensitiveState() {
    const state = reactive({ criticalData: '' });

    function updateCriticalData(newData) {
        state.criticalData = newData;

    watch(() => state.criticalData, (newValue, oldValue) => {
        // Handle critical data changes with precision

    return { state, updateCriticalData };

These reactive constructs, when harnessed with discernment, not only ensure a performant application but also uphold straightforward, traceable codebases. Adherence to these reactive guidelines within composables guarantees the vibrance of your Vue application's user experience while bestowing developers with a predictable state management architecture.

Complex State Handling and Composition Techniques

In advanced Vue.js applications, the handling of complex state within composables necessitates a sophisticated yet clear approach. Consider a scenario where we are developing a feature-rich to-do application, and we require composables that manage tasks, user preferences, and application settings. Each of these areas of functionality can be encapsulated in separate composables, which then are composed together in the main view. Here's an example of how this might look in code:

import { reactive, toRefs } from 'vue';

function useTasks() {
    const state = reactive({ tasks: [], filter: 'all' });
    // Functionality to manipulate tasks
    return { ...toRefs(state), /* task manipulation methods */ };

function useUserPreferences() {
    const state = reactive({ darkMode: false });
    // Functionality to switch themes
    return { ...toRefs(state), /* theme methods */ };

function useApplicationSettings() {
    const state = reactive({ notificationsEnabled: true });
    // Functionality to handle settings
    return { ...toRefs(state), /* settings methods */ };

function useTodoManager() {
    const tasks = useTasks();
    const preferences = useUserPreferences();
    const settings = useApplicationSettings();
    // Composable that orchestrates tasks, preferences, and settings
    return { tasks, preferences, settings };

We create a clear and consistent API for each composable by exposing only the necessary reactivity points via toRefs, allowing the consuming components to maintain awareness of their reactive contract. This structure reinforces predictability and keeps mutations traceable.

Namespacing to avoid collisions in such a composed environment could be illustrated as follows:

function createNamespacedHelpers(namespace) {
    return {
        useState() {
            const state = useTodoManager();
            return { [namespace]: state };

// In the consuming component
const { todoManagerState } = createNamespacedHelpers('todoManager').useState();

By employing a function like createNamespacedHelpers, we dynamically generate a namespaced version of our state, thereby preventing any potential naming conflicts.

For encapsulation, consider the useTasks composable; it's the gatekeeper for all task-related logic and state. By design, it doesn't expose the raw reactive state directly but uses toRefs to expose a more controlled API:

// Inside useTasks composable
import { ref } from 'vue';

function useTasks() {
    const tasks = ref([]);
    const addTask = (task) => {
    // Only the tasks and the addTask method are exposed
    return { tasks, addTask };

When it comes to performance, we judiciously decide when to use reactivity. For example, if a piece of state does not need to be reactive, we can just use a simple variable. When composing multiple composables like useTodoManager, we ensure that reactivity is used only when components need to react to changes, avoiding unnecessary re-renders:

import { computed } from 'vue';

function useFilteredTasks(tasks, filter) {
    const filteredTasks = computed(() => 
        tasks.filter(task => task.match(filter)));
    // Exporting only the computed property minimizes reactivity
    return { filteredTasks };

Lastly, to prevent complexity, we must continuously refactor our composables to ensure they remain focused and understandable. A complex composable should be decomposed into multiple, more focused composables. This approach keeps each unit small, focused, and manageable, thus facilitating easier debugging, testing, and maintenance while also enabling better scalability and sustainability in the application.

Composables in the Larger Ecosystem: Integration with Vuex and Pinia

In the realm of Vue.js, the shift from Vuex to the Composition API, alongside the adoption of Pinia as an official store, marks a pivotal evolution in state management practices. With composables, developers can now encapsulate and expose stateful logic in a more granular and flexible manner, distinct from the more rigid store modules of Vuex. Although Vuex provides a well-established pattern for managing state, Vue 3 introduces composables as first-class citizens that align with the framework's compositional architecture.

The flexibility of composables can be harnessed within Pinia stores, elevating the compositional experience. For example, state can be initialized within Pinia using composables, affording the developer the creative space to structure complex stores with neatly encapsulated logic. Through this integration, developers gain the ability to shape their application’s architecture in a way that can dynamically respond to evolving business logic without succumbing to the rigidity typically encountered in large Vuex modules.

Refactoring Vuex modules to use composables demands an intimate understanding of the business logic entwined within. By methodically extracting and relocating these domain-specific operations into composable functions, you are effectively untangling the monolithic state management approach of Vuex and allowing for more targeted updates and reactive dependencies. This modularity not only enhances flexibility but also promotes reusability across various components without the need to directly interact with the global store.

When transitioning to this model, stateful logic within Vuex actions can be converted into independent composables that interact with the store via Pinia's store.$state object. This mixture brings forth the dual advantage of maintaining a centralized store while benefitting from the compositional patterns that encourage reuse. However, developers must be judicious in determining the scoping of state between global, accessible via the store, and local, managed within composables.

By interfacing between the compositional powers of Vue 3 and Pinia, developers can construct a store pattern that embodies the spirit of modularity and reusability without abandoning the paradigms Vuex has instilled within the Vue ecosystem. In practice, this integration demands careful attention to detail to ensure that the inherently reactive nature of composables does not lead to performance bottlenecks, especially when dealing with large and complex global states. In conclusion, while composables proffer an enticing alternative to traditional state management, they must be wielded with strategic intent, always mindful of their impact on the overall system's performance and maintainability.

Testing and Refactoring Vue.js Composables

To ensure the robustness and reliability of composables in Vue.js, testing is a critical step that should not be overlooked. Adopting unit testing patterns enables developers to verify the individual parts of the composable's behavior. Harnessing tools like Jest alongside Vue Test Utils paves the way for a streamlined testing process where reactive data and functions represented by composables are tested in isolation. Here is an example of a Jest test for a useCounter composable:

import { useCounter } from './composables';
import { reactive } from 'vue';
import { mount } from '@vue/test-utils';

describe('useCounter', () => {
  test('increments the counter', () => {
    const component = {
      setup() {
        return reactive(useCounter());
      template: '<div>{{ count }}</div>'

    const wrapper = mount(component);

When it comes to testing dependencies within composables, mocking is an invaluable technique. It allows for the simulation of dependency behavior and testing of the composable in a controlled environment. Mock dependency injection can bypass actual data calls or browser-specific implementations, which renders the testing process both more predictable and efficient. For example, mocking a data fetching service allows you to test how the composable handles different API response scenarios without making real HTTP requests.

Unit testing composables often uncovers areas ripe for refactoring. Methodically identifying and extracting pieces of legacy code — code that often intertwines state management, side effects, and UI logic — into discrete composables achieves a cleaner, more modular codebase. The refactoring process should proceed incrementally, ensuring that each transformation enhances the existing functionality without introducing new issues.

A key strategy in refactoring is to identify repeatable patterns within the legacy code that can be turned into generic composables. For example, refactoring a legacy data fetching pattern into a reusable composable might look like this:

// Before refactoring: Legacy code with data fetching logic
export default {
  data() {
    return {
      isLoading: false,
      data: null
  created() {
  methods: {
    async fetchData() {
      this.isLoading = true; = await getData(); // getData() fetches data from an API
      this.isLoading = false;

// After refactoring: A useDataFetch composable
export function useDataFetch(apiMethod) {
  const data = ref(null);
  const isLoading = ref(false);

  const fetchData = async () => {
    isLoading.value = true;
    data.value = await apiMethod();
    isLoading.value = false;

  return { data, isLoading, fetchData };

Finally, embracing the process of refactoring as part of the development lifecycle encourages a culture of continuous improvement. With a focus on increasing the modularity and testability of the application, composables can be critically assessed and optimized over time. Devoting attention to refactoring and rigorous testing advances the scalability and clarity of Vue.js applications, turning composables into powerful, reliable, and highly reusable resources for developers.


This article explores the concept of creating reusable composables in Vue.js 3, focusing on best practices, state management, composition techniques, integration with Vuex and Pinia, as well as testing and refactoring. The key takeaways include the importance of encapsulating logic in clear and reusable composables, the use of reactive principles in state management, the composition of complex state handling, the integration of composables with Vuex and Pinia, and the importance of testing and refactoring. As a challenging task, readers can try refactoring a legacy codebase into modular and reusable composables, enhancing their codebase's maintainability and reusability.

Don't Get Left Behind:
The Top 5 Career-Ending Mistakes Software Developers Make
FREE Cheat Sheet for Software Developers