vue-conventions

Vue 3 Conventions

This skill consolidates idioms for Vue 3 SPA projects with <script setup> and the Composition API. Apply alongside js-foundation:typescript-patterns (general TS strictness).

Vue 2 fallback notes are at the end — applied only when project is on "vue": "^2".

Project layout

src/
├── main.ts                          # createApp + mount
├── App.vue                          # root SFC
├── router/
│   ├── index.ts                     # createRouter + routes
│   └── guards.ts                    # navigation guards
├── views/                           # route components (page-level)
│   ├── HomeView.vue
│   └── UsersView.vue
├── components/
│   ├── ui/                          # primitives (Button, Input, Modal)
│   └── features/                    # feature-specific
│       └── users/
│           ├── UserCard.vue
│           └── UserFilter.vue
├── composables/                     # use*.ts
│   ├── useDebounce.ts
│   └── useUsers.ts
├── stores/                          # Pinia stores
│   └── users.ts
├── lib/                             # framework-agnostic utilities
│   └── http.ts
├── types/
│   └── user.ts
└── assets/
    └── styles/
        └── global.css

Mirror what exists. Don't restructure as part of feature work.

File naming

Component name in <template>: PascalCase (<UserCard />) OR kebab-case (<user-card />) — both work, Vue handles conversion.

SFC structure

<script setup lang="ts">
// 1. Imports
import { ref, computed, onMounted } from 'vue';
import { useRouter } from 'vue-router';
import type { User } from '@/types/user';

// 2. Props/emits/slots
interface Props {
  userId: string;
  initialName?: string;
}
const props = withDefaults(defineProps<Props>(), { initialName: '' });
const emit = defineEmits<{
  save: [name: string];
  cancel: [];
}>();

// 3. Reactive state
const name = ref(props.initialName);
const error = ref<string | null>(null);

// 4. Composables
const router = useRouter();

// 5. Computed
const isValid = computed(() => name.value.length >= 2);

// 6. Methods
function onSave() {
  if (!isValid.value) {
    error.value = 'Name must be at least 2 characters';
    return;
  }
  emit('save', name.value);
}

// 7. Lifecycle
onMounted(() => {
  console.log('UserForm mounted for', props.userId);
});
</script>

<template>
  <form @submit.prevent="onSave">
    <input v-model="name" placeholder="Name" />
    <p v-if="error" role="alert">{{ error }}</p>
    <div class="actions">
      <button :disabled="!isValid">Save</button>
      <button type="button" @click="emit('cancel')">Cancel</button>
    </div>
  </form>
</template>

<style scoped>
form {
  display: flex;
  flex-direction: column;
  gap: 8px;
}
.actions {
  display: flex;
  gap: 8px;
}
</style>