Vue3 Component Decomposition

Vue 3 Component Decomposition

Break large Vue 3 components into smaller, testable units without losing readability.

When to Use

• Component is handling multiple concerns (UI rendering, fetching, form logic, filtering, side effects)
• setup() or <script setup> grows hard to scan
• Template contains complex expressions or repeated blocks
• Changes in one feature frequently break unrelated behavior

Decomposition Workflow

1. Map responsibilities before moving code:

• view (markup/presentational)
• state (refs/reactive/computed)
• effects (watch/watchEffect/lifecycle)
• io (API calls)

2. Extract presentational subcomponents first. 3. Define explicit interfaces between parent and child (props, emits, slots). 4. Extract reusable stateful logic into composables. 5. Keep the parent as orchestrator of data flow and feature composition.

Component Best Practices

• Use one component per file and multi-word component names.
• Keep template expressions simple; move complex expressions to computed values.
• Use :key with v-for and do not combine v-if with v-for on the same element.
• Use typed, explicit prop contracts and typed emits.
• Prefer slots for variable UI regions over boolean prop explosion.
• Keep child components focused on one UI concern.

Composable Best Practices

• Name composables with use prefix (useOrdersTable, useUserFilters).
• Return a plain object of refs/computed/methods so destructuring preserves reactivity.
• Accept reactive inputs (value/ref/getter) and normalize with toValue().
• If logic depends on reactive inputs, call toValue() in watchEffect() (or watch refs/getters directly).
• Perform DOM side effects in onMounted() and always clean up in onUnmounted().
• Avoid hidden global mutable state unless intentionally building shared state.

Suggested Structure

src/
  components/
    feature/
      OrdersPage.vue               # orchestrator
      OrdersToolbar.vue            # presentational controls
      OrdersTable.vue              # table rendering
      OrdersTableRow.vue           # row rendering
  composables/
    useOrdersQuery.ts              # fetch/pagination/sort
    useOrdersFilters.ts            # filter state and derived query
    useOrdersSelection.ts          # row selection logic

Guardrails

• Do not extract tiny wrappers with no independent value.
• Do not create "god composables"; split by business capability.
• Do not pass entire parent state into children; pass only required props.
• Do not mix business logic into presentational components.

PR Checklist

• Parent component reads as feature orchestration, not implementation dump.
• Children have clear APIs and can be reasoned about in isolation.
• Composables have focused responsibilities and predictable return shapes.
• Side effects are cleaned up and SSR-safe.
• Template complexity is reduced and tests can target smaller units.

References

• Vue docs: Composables - https://vuejs.org/guide/reusability/composables.html
• Vue style guide (outdated but still useful):
• https://vuejs.org/style-guide/rules-essential.html
• https://vuejs.org/style-guide/rules-strongly-recommended.html

Vue 3 Decomposition Playbook

Use this playbook when splitting a large Vue 3 component.

1) Identify Seams

Split logic by concern, not by line count:

• UI rendering blocks
• Async data loading
• Derived state and filters
• User actions (submit, delete, select)
• Browser effects (event listeners, resize, observers)

If a section can be explained independently, it is a candidate for extraction.

2) Extract Child Components

Start with repeated or visually distinct template regions.

Good candidates:

• Toolbars, filters, headers
• Tables/lists and list rows
• Forms and modal bodies

Define a minimal API per child:

• Props: input data only
• Emits: user intent only (save, cancel, delete)
• Slots: layout customization

3) Extract Composables

Move stateful logic that is reused or noisy in the parent.

Composable shape:

export function useSomething(input: MaybeRefOrGetter<string>) {
  const value = ref("")
  const loading = ref(false)
  const error = ref<Error | null>(null)

  watchEffect(() => {
    const normalized = toValue(input)
    // react to normalized input
  })

  return { value, loading, error }
}

Rules:

• Return plain object of refs/computed/methods.
• Keep one responsibility per composable.
• Cleanup side effects in onUnmounted().

4) Keep Parent as Orchestrator

Parent component should compose children and composables:

• wires composables together
• maps outputs to child props
• handles top-level route/page concerns

If parent starts owning low-level details again, extract one more seam.

5) Contract and Naming Guidelines

• Multi-word component names (OrdersTableRow.vue).
• Composable names start with use (useOrdersFilters.ts).
• Prefer full words over abbreviations in file names.
• Keep naming consistent (PascalCase for components, camelCase for props declarations).

6) Anti-Patterns

• Passing large mutable objects everywhere instead of focused props.
• Child components mutating business state directly.
• One composable handling API, validation, analytics, and UI flags.
• v-if and v-for on the same element.
• Heavy inline template expressions.

7) Done Criteria

• Each extracted unit has a clear responsibility.
• Templates are mostly declarative and easy to scan.
• Data flow direction is clear (parent down, events up).
• Logic can be tested at composable or child level without full page setup.