Vue Component and Composable Design Patterns: A Startup Guide

This guide provides a practical overview of Vue component and composable design patterns, with tips and examples, tailored for developers in your startup. It leverages insights from various sources to help you write cleaner, more maintainable, and scalable Vue applications.

Component Design Patterns

1. Components Pattern

Extracting reusable components from existing components simplifies code and enhances reusability^1. This promotes the Single Responsibility Principle, making your codebase more modular and maintainable.

Tip: Identify and extract hidden components within your existing code. Look for repeating UI elements or logic that can be encapsulated.

Example:

<!-- Before: Complex Form -->
<template>
  <div>
    <label for="name">Name:</label>
    <input type="text" id="name" v-model="name">
    <label for="email">Email:</label>
    <input type="email" id="email" v-model="email">
    <button @click="submitForm">Submit</button>
  </div>
</template>

<!-- After: Using Reusable Components -->
<template>
  <div>
    <InputField label="Name" v-model="name" type="text" />
    <InputField label="Email" v-model="email" type="email" />
    <SubmitButton @click="submitForm" />
  </div>
</template>

2. Clean Components

Aim for components that not only work but also work well, considering code readability, maintainability, and testability^1. Clean components are easy to understand, modify, and debug.

Tip: Write components that are easy to understand and maintain. Use clear naming conventions, consistent formatting, and well-defined responsibilities.

Example:

<!-- Bad: Component with mixed concerns -->
<template>
  <div>
    <button @click="handleClick">{{ buttonText }}</button>
    <div v-if="showDetails">{{ details }}</div>
  </div>
</template>
<script setup>
import { ref } from 'vue';

const buttonText = ref('Show Details');
const showDetails = ref(false);
const details = ref('');

async function handleClick() {
  showDetails.value = !showDetails.value;
  if (showDetails.value) {
    details.value = await fetchData();
  }
}
</script>

<!-- Good: Component with focused responsibility -->
<template>
  <div>
    <ShowDetailsButton @click="toggleDetails" :text="buttonText" />
    <DetailsDisplay v-if="showDetails" :details="details" />
  </div>
</template>
<script setup>
import { ref } from 'vue';
import ShowDetailsButton from './ShowDetailsButton.vue';
import DetailsDisplay from './DetailsDisplay.vue';

const showDetails = ref(false);
const details = ref('');
const buttonText = ref('Show Details');

async function toggleDetails() {
  showDetails.value = !showDetails.value;
  if (showDetails.value) {
    details.value = await fetchData();
  }
}
</script>

3. Multiple Components in One File

For small, self-contained components, consider keeping them in the same file^2. This can reduce the number of files in your project and improve development speed, especially for components that are tightly coupled.

Tip: Avoid creating unnecessary files for simple components. Use this approach for components that are only used in one place.

Example:

<template>
  <div>
    <MyButton @click="handleClick">Click Me</MyButton>
  </div>
</template>

<script setup>
import MyButton from './MyButton.vue';

function handleClick() {
  alert('Button clicked!');
}
</script>

<template>
  <button @click="$emit('click')">
    <slot></slot>
  </button>
</template>
<script setup>
defineEmits(['click']);
</script>

4. Controlled Props Pattern

This pattern allows you to override the internal state of a component from the parent^4. This is useful when you need to force a component's state from the outside, such as controlling the visibility of a modal or the selection in a dropdown.

Tip: Use this pattern when you need to force a component's state from the outside. Pass props to the component to control its internal state.

Example:

<!-- Modal.vue -->
<template>
  <div v-if="isOpen" class="modal">
    <div class="modal-content">
      <slot></slot>
      <button @click="closeModal">Close</button>
    </div>
  </div>
</template>
<script setup>
defineProps({
  isOpen: {
    type: Boolean,
    default: false
  }
});

const emit = defineEmits(['close']);

function closeModal() {
  emit('close');
}
</script>

<!-- Parent Component -->
<template>
  <div>
    <button @click="showModal = true">Open Modal</button>
    <Modal :isOpen="showModal" @close="showModal = false">
      <p>Modal Content</p>
    </Modal>
  </div>
</template>
<script setup>
import { ref } from 'vue';
import Modal from './Modal.vue';

const showModal = ref(false);
</script>

5. Component Metadata

Add metadata to components to provide additional information to other components ^2. This can be used for component configuration, to pass additional information, or to facilitate communication between components.

Tip: Use metadata for component configuration or to pass additional information. This can be useful for tooling or to provide context to other components.

Example:

<!-- Component A -->
<template>
  <div>Component A</div>
</template>
<script>
export default {
  meta: {
    componentType: 'display'
  }
}
</script>

<!-- Component B -->
<template>
  <div>Component B</div>
</template>
<script>
export default {
  meta: {
    componentType: 'formField'
  }
}
</script>

Composable Design Patterns

1. Options Object Pattern

Use an object to pass parameters into composables^1. This allows for flexibility and scalability. It's the preferred method for passing numerous options to a composable.

Tip: This pattern is used in VueUse and is highly recommended when you need to configure the behavior of a composable.

Example:

// useFetch.js
import { ref, onMounted } from 'vue';

export function useFetch(url, options = {}) {
  const data = ref(null);
  const loading = ref(false);
  const error = ref(null);

  const { method = 'GET', headers = {}, body = null } = options;

  async function fetchData() {
    loading.value = true;
    try {
      const response = await fetch(url, {
        method,
        headers,
        body: body ? JSON.stringify(body) : null
      });
      if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
      }
      data.value = await response.json();
    } catch (e) {
      error.value = e;
    } finally {
      loading.value = false;
    }
  }

  onMounted(() => {
    fetchData();
  });

  return { data, loading, error, fetchData };
}

// In a component:
import { useFetch } from './useFetch';
export default {
  setup() {
    const { data, loading, error } = useFetch('/api/data', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: { key: 'value' }
    });
    return { data, loading, error };
  }
}

2. Inline Composables

Create composables directly within the component file to avoid creating new files^1. This is particularly useful for composables that are very specific to a single component and not intended for reuse elsewhere. Use inline composables for small, component-specific logic. This keeps related code together and can simplify development.

Tip: Use inline composables for small, component-specific logic that doesn't need to be reused elsewhere. This approach keeps related code together and simplifies your component structure.

Example:

Let's say you have this in your component:

<template>
  <div>{{ formattedDate }}</div>
</template>

<script setup>
import { ref, computed } from 'vue'

const useFormattedDate = () => {
  const rawDate = ref(new Date())
  const formattedDate = computed(() => {
    const options = { year: 'numeric', month: 'long', day: 'numeric' }
    return rawDate.value.toLocaleDateString(undefined, options)
  })
  return { formattedDate }
}

const { formattedDate } = useFormattedDate()
</script>

It's fine for now, but if you need this date formatting anywhere else, you're screwed. Here's the refactored version:

// src/composables/useFormattedDate.ts
import { ref, computed } from 'vue'

export function useFormattedDate() {
  const rawDate = ref(new Date())
  const formattedDate = computed(() => {
    const options = { year: 'numeric', month: 'long', day: 'numeric' }
    return rawDate.value.toLocaleDateString(undefined, options)
  })
  return { formattedDate }
}

<!-- In your component -->
<template>
  <div>{{ formattedDate }}</div>
</template>

<script setup>
import { useFormattedDate } from './composables/useFormattedDate'

const { formattedDate } = useFormattedDate()
</script>

Now, you can reuse useFormattedDate in any component. Problem solved.

3. Coding Better Composables

Extract small pieces of logic into functions that you can easily reuse repeatedly^1. This promotes code reuse, reduces duplication, and makes your code more maintainable.

Tip: Use composables to organize and reuse business logic. Think of composables as reusable building blocks for your application.

Example:

// useLocalStorage.ts
import { ref, watch } from 'vue';

export function useLocalStorage<T>(key: string, defaultValue: T) {
  const storedValue = localStorage.getItem(key);
  const value = ref<T>(storedValue !== null ? JSON.parse(storedValue) : defaultValue);

  watch(
    value,
    (newValue) => {
      localStorage.setItem(key, JSON.stringify(newValue));
    },
    { deep: true }
  );

  return value;
}

// Usage in a component:
<script setup>
import { useLocalStorage } from './useLocalStorage';

const theme = useLocalStorage('theme', 'light');
</script>

4. Start with the Interface

Define how a composable will be used before implementing it^4. This is a form of "design-first" development that helps you clarify the composable's purpose, inputs, and outputs before writing any code.

Tip: Define the inputs (props, options) and outputs (returned values) of the composable first. This helps you focus on the API of the composable.

Example:

// Before Implementation: useCounter.js
// Should accept an initial value
// Should return a count and methods to increment and decrement it
// Implementation:
import { ref } from 'vue';

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

  function increment() {
    count.value++;
  }

  function decrement() {
    count.value--;
  }

  return { count, increment, decrement };
}

5. Reusing Logic with Scoped Slots

Use scoped slots to reuse logic between componentsin a unique way^5. Scoped slots allow a parent component to pass data and logic to its child, providing a flexible way to share functionality.

Tip: Scoped slots can be used to pass data and logic from the parent component to the child component. This allows the child component to render its content based on the data and logic provided by the parent.

Example:

<!-- DataFetcher.vue -->
<template>
  <div>
    <div v-if="loading">Loading...</div>
    <div v-else-if="error">Error: {{ error }}</div>
    <div v-else>
      <slot :data="data" :loading="loading" :error="error"></slot>
    </div>
  </div>
</template>
<script setup>
import { ref, onMounted } from 'vue';

const props = defineProps({
  url: {
    type: String,
    required: true
  }
});

const data = ref(null);
const loading = ref(true);
const error = ref(null);

onMounted(async () => {
  try {
    const response = await fetch(props.url);
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    data.value = await response.json();
  } catch (e) {
    error.value = e.message;
  } finally {
    loading.value = false;
  }
});
</script>

<!-- Usage in a component -->
<DataFetcher url="/api/items">
  <template v-slot="{ data, loading, error }">
    <div v-if="loading">Loading items...</div>
    <div v-else-if="error">Error: {{ error }}</div>
    <div v-else>
      <ul>
        <li v-for="item in data" :key="item.id">{{ item.name }}</li>
      </ul>
    </div>
  </template>
</DataFetcher>

General Tips and Best Practices

1. Ref vs. Reactive

Understand the differences between ref and reactive and choose the appropriate one for your use case^1. ref is used for primitive values, while reactive is used for objects and arrays.

Tip: Use ref for primitive values and reactive for objects and arrays. This helps with Vue's reactivity system.

Example:

<script>
import { ref, reactive } from 'vue';

export default {
  setup() {
    const count = ref(0); // ref for a primitive value
    const user = reactive({ name: 'John', age: 30 }); // reactive for an object
    return { count, user };
  }
}
</script>

2. Effective State Management

Structure the state in your applications effectively^1. This is crucial for managing data flow and ensuring your application remains manageable as it grows. Consider appropriate state management libraries for larger applications.

Tip: Consider using Pinia or Vuex for state management in larger applications. These libraries provide centralized state management and make it easier to handle complex application state.

Example: (Illustrative - actual implementation depends on the chosen state management library)

// Pinia Example (Conceptual)
import { defineStore } from 'pinia';

export const useUserStore = defineStore('user', {
  state: () => ({
    isLoggedIn: false,
    user: null
  }),
  actions: {
    login(userData) {
      this.isLoggedIn = true;
      this.user = userData;
    },
    logout() {
      this.isLoggedIn = false;
      this.user = null;
    }
  }
});

3. Use Quotes to Watch Nested Values

Watch nested values directly by using quotes^2. This allows you to observe changes to specific properties within an object, triggering updates when those properties change. *Tip: Use quotes in the watch option to watch nested properties of an object. This is a more efficient and specific way to monitor changes.

Example:

<script>
import { ref, watch } from 'vue';

export default {
  setup() {
    const data = ref({ user: { name: 'John' } });

    watch(() => data.value.user.name, (newName) => {
      console.log('Name changed:', newName);
    });

    return { data };
  }
}
</script>

4. The Extract Conditional Pattern

Split up components based on conditional logic^3. This improves readability and maintainability by separating concerns. It makes components easier to understand and test.

Tip: If a component has complex conditional logic, consider breaking it into smaller components. This creates more focused and manageable components.

Example:

<!-- Before: Complex Conditional Logic -->
<template>
  <div>
    <div v-if="isLoading">Loading...</div>
    <div v-else-if="error">Error: {{ error }}</div>
    <div v-else>
      <UserList v-if="users.length > 0" :users="users" />
      <NoUsersMessage v-else />
    </div>
  </div>
</template>

<!-- After: Using Extracted Components -->
<template>
  <LoadingIndicator v-if="isLoading" />
  <ErrorMessage v-if="error" :message="error" />
  <UsersDisplay v-else :users="users" />
</template>

5. 6 Reasons to Split up Components

Break down components into smaller pieces to improve code organization and reusability^3. This increases the readability, maintainability, and testability of your code.

Tip: Smaller components are easier to understand, test, and maintain. They also promote reusability, as you can use them in multiple parts of your application.

Example:

<!-- Before: Monolithic Component -->
<template>
  <div>
    <Header />
    <Sidebar />
    <MainContent />
    <Footer />
  </div>
</template>

<!-- After: Using Extracted Components -->
<template>
  <AppLayout>
    <template v-slot:header><Header /></template>
    <template v-slot:sidebar><Sidebar /></template>
    <template v-slot:main><MainContent /></template>
    <template v-slot:footer><Footer /></template>
  </AppLayout>
</template>

6. Don't Override Component CSS

Avoid directly modifying a component's CSS from outside the component^2. This can lead to unexpected behavior and make it difficult to maintain your application's styles. Encapsulate styles within the component itself.

Tip: Use props or slots to customize the appearance of a component. This allows for controlled styling and prevents unexpected style conflicts.

Example:

<!-- Button.vue -->
<template>
  <button :class="['button', variant]" @click="emit('click')">
    <slot></slot>
  </button>
</template>
<script setup>
const props = defineProps({
  variant: {
    type: String,
    default: 'primary'
  }
});

const emit = defineEmits(['click']);
</script>
<style scoped>
.button {
  /* Base button styles */
}
.primary {
  /* Primary button styles */
}
.secondary {
  /* Secondary button styles */
}
</style>