vue

name	vue
description	Use when working with .vue files, composables, Pinia stores, or form validation.
allowed-tools	Read, Edit, Write, Glob, Grep, Bash
metadata	{"author":"profiletailors","version":"1.0"}

Vue 3 Skill

Conventions for Vue 3 development with Composition API, TypeScript, and the profiletailors component ecosystem.

When to Use

• Creating or modifying .vue components
• Building composables for reusable logic
• Managing state with Pinia stores
• Implementing form validation with Vee-Validate + Zod
• Working with the @profiletailors/ui component library

Project Standard: Component Maintainability

This project follows a component maintainability standard that defines layering, composable extraction, component decomposition, type contracts, and code quality checks.

Read the full guide at: .agents/skills/frontend-platform/vue/references/vue-component-maintainability.md

Key rules enforced by this standard:

• Single responsibility: template describes WHAT, composable describes HOW, store describes global state
• Composable extraction when <script setup> exceeds ~80 lines or contains computed/watch logic
• Explicit contracts: typed props/emits, no any, withDefaults for optional props
• Parent-orchestrator pattern: decompose components when they exceed ~200 lines
• Pre-merge checklist before every Vue PR

Critical Patterns

1. Component Structure

ALWAYS use <script setup lang="ts">:

<script setup lang="ts">
  // 1. Imports
  import {computed, ref} from 'vue';
  import {useUserStore} from '@/stores/user';

  // 2. Type definitions
  type Props = {
    title: string;
    count?: number;
    isActive?: boolean;
  };

  // 3. Props with defaults
  const props = withDefaults(defineProps<Props>(), {
    count: 0,
    isActive: false,
  });

  // 4. Emits with types
  const emit = defineEmits<{
    (e: 'update', value: number): void;
    (e: 'close'): void;
  }>();

  // 5. Composables and stores
  const userStore = useUserStore();

  // 6. Reactive state
  const localCount = ref(props.count);

  // 7. Computed properties
  const doubled = computed(() => localCount.value * 2);

  // 8. Methods
  const increment = () => {
    localCount.value++;
    emit('update', localCount.value);
  };
</script>

<template>
  <div class="card">
    <h2>{{ title }}</h2>
    <p>Count: {{ localCount }} (Doubled: {{ doubled }})</p>
    <button @click="increment">Increment</button>
  </div>
</template>

<style scoped>
  .card {
    padding: var(--space-4);
  }
</style>

2. Pinia Stores

ALWAYS type state, getters, and actions:

// stores/user.ts
import {defineStore} from 'pinia';
import {api, isAxiosError} from '@/api';
import {toast} from 'vue-sonner';

type User = {
  id: string;
  name: string;
  email: string;
};

type UserState = {
  currentUser: User | null;
  isLoading: boolean;
  error: string | null;
};

export const useUserStore = defineStore('user', {
  state: (): UserState => ({
    currentUser: null,
    isLoading: false,
    error: null,
  }),

  getters: {
    isAuthenticated: (state): boolean => state.currentUser !== null,
    userInitials: (state): string => {
      if (!state.currentUser) return '';
       state..
          .()
          .( n[])
          .();
    },
  },

  : {
     (: ): <> {
      . = ;
      . = ;
       {
         response =  api.(id);
        . = response.;
      }  (e) {
        
         error = e   ? e :  ();
         message = (e) && e.?.?.
            ? e...
            : error. || ;

        . = message;
        toast.(, {: message});
      }  {
        . = ;
      }
    },

    ():  {
      . = ;
    },
  },
});

3. Composables

Return reactive values, prefix with use:

// composables/useCounter.ts
import {ref, computed, type Ref, type ComputedRef} from 'vue';

type UseCounterReturn = {
  count: Ref<number>;
  doubled: ComputedRef<number>;
  increment: () => void;
  decrement: () => void;
  reset: () => void;
};

export const useCounter = (initial = 0): UseCounterReturn => {
  const count = ref(initial);
  const doubled = computed(() => count.value * 2);

  const increment = () => count.value++;
  const decrement = () => count.value--;
  const reset = () => count.value = initial;

  return {count, doubled, increment, decrement, reset};
};

4. Form Validation (Vee-Validate + Zod)

CRITICAL: Manual validation on blur, NOT automatic:

<script setup lang="ts">
  import {useForm} from 'vee-validate';
  import {toTypedSchema} from '@vee-validate/zod';
  import {z} from 'zod';
  import {
    FormField,
    FormItem,
    FormLabel,
    FormControl,
    FormMessage,
    Input,
    Button,
  } from '@profiletailors/ui';

  const schema = z.object({
    email: z.string().email('Invalid email format'),
    password: z.string().min(8, 'Must be at least 8 characters'),
  });

  type FormData = z.infer<typeof schema>;

  const {handleSubmit, validateField, resetForm} = useForm<FormData>({
    validationSchema: toTypedSchema(schema),
    validateOnMount: false, // ✅ CRITICAL: Don't validate on mount
  });

  const onSubmit = handleSubmit((values) => {
    console.log('Form submitted:', values);
  });
</script>

<template>
  <form @submit="onSubmit">
    <FormField v-slot="{ componentField }" name="email">
      <FormItem>
        <FormLabel>Email</FormLabel>
        <FormControl>
          <!-- ✅ Manual validation on blur -->
          <Input
              type="email"
              v-bind="componentField"
              @blur="validateField('email')"
          />
        </FormControl>
        <FormMessage/>
      </FormItem>
    </FormField>

    <Button type="submit">Submit</Button>
  </form>
</template>

5. Component Communication

Scenario	Approach
Parent → Child	Props
Child → Parent	emit()
Sibling/Distant	Pinia store
Provide/Inject	Rarely, for deeply nested

NEVER use global event buses.

UI Components (@profiletailors/ui)

Use Shadcn-Vue components from @profiletailors/ui:

<script setup lang="ts">
  import {Button, Card, CardHeader, CardTitle, CardContent} from '@profiletailors/ui';
</script>

<template>
  <Card>
    <CardHeader>
      <CardTitle>Dashboard</CardTitle>
    </CardHeader>
    <CardContent>
      <Button variant="default" @click="handleAction">
        Take Action
      </Button>
    </CardContent>
  </Card>
</template>

Performance Patterns

<script setup lang="ts">
  import {onUnmounted, shallowRef} from 'vue';

  // ✅ Use shallowRef for large objects that don't need deep reactivity
  const largeData = shallowRef<LargeObject | null>(null);

  // ✅ Clean up side effects
  const intervalId = setInterval(() => {
    // polling logic
  }, 5000);

  onUnmounted(() => {
    clearInterval(intervalId);
  });
</script>

<template>
  <!-- ✅ v-once for truly static content -->
  <footer v-once>
    <p>© 2024 CVIX</p>
  </footer>

  <!-- ✅ v-memo for expensive lists -->
  <div v-for="item in items" :key="item.id" v-memo="[item.id, item.updated]">
    {{ item.name }}
  </div>
</template>

Anti-Patterns

❌ Options API - Always use Composition API with <script setup> ❌ any type - Always provide proper TypeScript types ❌ Mutating props - Props are read-only, emit events instead ❌ Global event bus - Use Pinia for cross-component state ❌ validate-on-blur prop - Use manual validateField() on @blur ❌ Field injection - Use constructor pattern in stores

i18n Pattern

<script setup lang="ts">
  import {useI18n} from 'vue-i18n';

  const {t} = useI18n();
</script>

<template>
  <h1>{{ t('dashboard.title') }}</h1>
  <p>{{ t('dashboard.welcome', { name: user.name }) }}</p>
</template>

Commands

# Development
pnpm --filter @profiletailors/webapp dev

# Testing
pnpm --filter @profiletailors/webapp vitest run
pnpm --filter @profiletailors/webapp vitest --watch

# Type checking
pnpm --filter @profiletailors/webapp vue-tsc --noEmit

# Linting
pnpm --filter @profiletailors/webapp lint

Resources

• Vue 3 Documentation
• Pinia Documentation
• Vee-Validate + Zod
• Shadcn-Vue