vue-application-structure

Vue Application Structure Skill

Step 1 — Directory Layout (Feature-Based)

Organise by feature, not by file type. Co-locate everything a feature needs:

src/
  features/
    auth/
      AuthLoginForm.vue
      useAuth.ts          ← composable
      auth.store.ts       ← Pinia store
      auth.types.ts
      auth.api.ts         ← HTTP calls
  components/             ← shared/generic UI components
    BaseButton.vue
    TheNavbar.vue
  composables/            ← shared composables used across features
    useBreakpoint.ts
  router/
    index.ts
    guards.ts
  stores/                 ← global stores (not feature-specific)
    ui.store.ts
  lib/                    ← utilities, formatters, constants
  assets/
  App.vue
  main.ts

Step 2 — Composition API Conventions

• Use <script setup lang="ts"> exclusively — no Options API, no defineComponent.
• Declare defineProps and defineEmits with TypeScript interfaces, not runtime validators.
• Keep template logic minimal — extract complex expressions into computed refs or composables.
• Use alias imports for cross-directory modules and ESM import/export syntax only.

<script setup lang="ts">
interface Props {
  userId: string
  readonly?: boolean
}
const props = withDefaults(defineProps<Props>(), { readonly: false })
const emit = defineEmits<{ saved: [userId: string] }>()
</script>

Step 3 — Composable Design

• Name composables with the use prefix: useAuth, useCart, useDebounce.
• Each composable has a single responsibility.
• Return reactive state and actions from a composable; do not mutate props.
• Composables that wrap a Pinia store should not duplicate store state — return store refs directly.

// composables/useDebounce.ts
export function useDebounce<T>(value: Ref<T>, delay: number): Readonly<Ref<T>> {
  const debounced = ref<T>(value.value) as Ref<T>
  watchEffect(() => {
    const timer = setTimeout(() => { debounced.value = value.value }, delay)
    return () => clearTimeout(timer)
  })
  return readonly(debounced)
}