playbooks

home / skills / oro-ad / nuxt-claude-devtools / vue-composition-api

vue-composition-api skill

/playground/.claude/skills/vue-composition-api

This skill helps you implement Vue 3 Composition API patterns in components using script setup, refs, reactive, and computed for robust state management.

npx playbooks add skill oro-ad/nuxt-claude-devtools --skill vue-composition-api

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1.4 KB
---
name: vue-composition-api
description: Vue 3 Composition API expert. Use when working with Vue components, composables, or reactive state.
---

You are an expert in Vue 3 Composition API. Apply these patterns:

## Script Setup

Always use `<script setup lang="ts">` syntax for single-file components.

## Reactivity

- Use `ref()` for primitive values
- Use `reactive()` for objects and arrays
- Use `shallowRef()` for large objects that don't need deep reactivity

## Computed Properties

Prefer `computed()` over methods for derived state:

```typescript
const fullName = computed(() => `${firstName.value} ${lastName.value}`)
```

## Watchers

- Use `watch()` for explicit dependencies
- Use `watchEffect()` for automatic dependency tracking

```typescript
watch(source, (newVal, oldVal) => {
  // React to changes
})

watchEffect(() => {
  // Runs immediately and tracks dependencies
})
```

## Props & Emits

Type with interface syntax:

```typescript
const props = defineProps<{
  title: string
  count?: number
}>()

const emit = defineEmits<{
  (e: 'update', value: string): void
  (e: 'close'): void
}>()
```

## Expose

Use `defineExpose()` only when parent components need direct access:

```typescript
defineExpose({
  focus,
  reset
})
```

## Template Refs

```typescript
const inputRef = ref<HTMLInputElement | null>(null)

onMounted(() => {
  inputRef.value?.focus()
})
```

Overview

This skill is a Vue 3 Composition API expert focused on practical patterns for single-file components and composables. It enforces TypeScript-driven script setup, predictable reactivity primitives, and clear component APIs. Use it to standardize component structure, improve type safety, and reduce reactivity bugs.

How this skill works

The skill inspects component code and recommends Composition API patterns: script setup with TypeScript, appropriate use of ref, reactive, and shallowRef, plus computed properties and watchers. It also validates prop and emit typing, suggests when to expose methods with defineExpose, and checks template refs and lifecycle usage. Suggestions are concrete snippets and best-practice guidance you can apply directly to files.

When to use it

  • Building or refactoring Vue single-file components using TypeScript
  • Creating or maintaining composables that manage shared reactive state
  • Defining typed props and emits for reusable components
  • Optimizing performance by choosing shallowRef for large objects
  • Implementing derived state and side effects with computed, watch, or watchEffect

Best practices

  • Always use <script setup lang="ts"> for component files to leverage type inference and compact syntax
  • Use ref() for primitives, reactive() for objects/arrays, and shallowRef() for large non-deep-reactive values
  • Prefer computed() for derived state instead of methods to ensure caching and clarity
  • Use watch() for explicit dependency reaction and watchEffect() for auto tracking side effects
  • Type props and emits with generic defineProps and defineEmits to get compile-time checks
  • Only call defineExpose() when a parent truly needs imperative access to child methods

Example use cases

  • Refactor an options-api component to script setup with typed props and emits
  • Create a composable that returns reactive state with computed getters and watched side effects
  • Optimize a large data model by switching it to shallowRef to avoid deep reactivity overhead
  • Implement a form component that exposes focus and reset methods via defineExpose
  • Use watchEffect to auto-run derived logic that depends on multiple reactive sources

FAQ

When should I use reactive() vs ref()?

Use ref() for primitive values and reactive() for objects or arrays. If you need direct reactivity for top-level properties use reactive(), else use ref for simple values.

When is shallowRef appropriate?

Use shallowRef for large objects or third-party instances where deep reactivity is unnecessary or too expensive; it tracks only the reference, not nested properties.

Should I always use defineExpose()?

No. Only expose methods or properties when a parent must call them. Avoid exposing internals to keep components encapsulated.