vue-skilld

---
name: vue-skilld
description: "The progressive JavaScript framework for building modern web UI. ALWAYS use when editing or working with *.vue files or code importing \"vue\". Consult for debugging, best practices, or modifying vue, core."
metadata:
  version: 3.5.40
  generated_by: cached
  generated_at: 2026-08-09
---

# vuejs/core `vue@3.5.40`
**Tags:** csp: 1.0.28-csp, v2-latest: 2.7.16, legacy: 2.7.16

**References:** [package.json](./.skilld/pkg/package.json) • [README](./.skilld/pkg/README.md) • [Docs](./.skilld/docs/_INDEX.md) • [Issues](./.skilld/issues/_INDEX.md) • [Discussions](./.skilld/discussions/_INDEX.md) • [Releases](./.skilld/releases/_INDEX.md)

## Search

Use `skilld search "query" -p vue` instead of grepping `.skilld/` directories. Run `skilld search --guide -p vue` for full syntax, filters, and operators.

<!-- skilld:api-changes -->
## API Changes

This section documents version-specific API changes — prioritize recent major/minor releases.

### New APIs (v3.5)

- NEW: `useTemplateRef(key)` — v3.5 introduces this API to replace manual `ref` patterns, returns a shallow ref synced with template element/component [source](./.skilld/docs/api/composition-api-helpers.md:L68)

- NEW: `useId()` — v3.5 generates unique-per-application IDs stable across server/client renders for SSR without hydration mismatches [source](./.skilld/docs/api/composition-api-helpers.md:L101)

- NEW: `onWatcherCleanup(cleanupFn)` — v3.5 registers cleanup functions in watchers, allowing cleanup after `await` without callback params [source](./.skilld/docs/api/reactivity-core.md:L557)

- NEW: `watch()` and `watchEffect()` pause/resume — v3.5 adds `pause()` and `resume()` methods to watcher handles for temporary pausing [source](./.skilld/docs/api/reactivity-core.md:L290)

- NEW: Lazy Hydration strategies for async components — v3.5 adds `hydrate` option to `defineAsyncComponent()` with built-in strategies: `hydrateOnIdle()`, `hydrateOnVisible()`, `hydrateOnMediaQuery(query)`, `hydrateOnInteraction(events)` [source](./.skilld/docs/guide/components/async.md:L111)

- NEW: `<Teleport defer>` prop — v3.5 adds `defer` prop allowing teleport to mount after render cycle, enabling targeting elements rendered after the teleport [source](./.skilld/docs/api/built-in-components.md:L290)

- NEW: `useHost()`, `useShadowRoot()`, `this.$host` — v3.5 adds APIs for custom elements to access host element and shadow root [source](./.skilld/releases/blog-3.5.md:L175)

- NEW: Custom element options — v3.5 `defineCustomElement()` second argument accepts `shadowRoot: false`, `nonce`, and `configureApp(app)` options [source](./.skilld/releases/blog-3.5.md:L186)

- NEW: Reactive Props Destructure stabilized — v3.5 stabilizes destructuring from `defineProps()` with automatic compiler transformation to `props.x` and native default value syntax [source](./.skilld/docs/api/sfc-script-setup.md:L212)

### New APIs (v3.4)

- NEW: `defineModel()` stabilized — v3.4 stabilizes this macro for two-way binding props, replaces v-model boilerplate with direct ref mutation [source](./.skilld/releases/blog-3.4.md:L100)

- NEW: `useModel()` — v3.4 underlying helper for `defineModel()` in non-SFC components, accepts props object and model key [source](./.skilld/docs/api/composition-api-helpers.md:L25)

- NEW: `v-bind` same-name shorthand — v3.4 allows `:id :src :alt` instead of `:id="id" :src="src" :alt="alt"` [source](./.skilld/releases/blog-3.4.md:L111)

### Breaking Changes (v3.4)

- BREAKING: Global `JSX` namespace no longer auto-registered in v3.4 — requires explicit `jsxImportSource: 'vue'` in `tsconfig.json` or `/* @jsxImportSource vue */` per file for TSX [source](./.skilld/releases/blog-3.4.md:L155)

- BREAKING: `app.config.unwrapInjectedRef` removed in v3.4 — was deprecated in 3.3 with default `true`, now always unwraps injected refs without option to disable [source](./.skilld/releases/blog-3.4.md:L169)

- BREAKING: `v-is` directive removed in v3.4 — use `is` attribute with `vue:` prefix instead (e.g., `:is="Comp"`) [source](./.skilld/releases/blog-3.4.md:L171)

- BREAKING: `@vnodeXXX` event listeners changed to compiler error in v3.4 — use `@vue:XXX` listeners instead (e.g., `@vue:click`) [source](./.skilld/releases/blog-3.4.md:L170)

- BREAKING: Reactivity Transform deprecated in v3.3, removed in v3.4 — experimental feature; users can enable via Vue Macros plugin if needed [source](./.skilld/releases/blog-3.4.md:L168)

### Version-Specific Behavior Changes

- BREAKING: `watch()` with `once: true` option added in v3.4 — new option to run callback only once then auto-stop, signature unchanged but new behavior capability [source](./.skilld/docs/api/reactivity-core.md:L395)

- BREAKING: `deep` option for `watch()` can now accept number in v3.5+ — specifies max traversal depth for deep watchers instead of just boolean [source](./.skilld/docs/api/reactivity-core.md:L426)

**Also changed:** `watchEffect()` cleanup callback signature changed (v3.5 adds `onWatcherCleanup()` alternative) · `defineAsyncComponent()` options extended with `hydrate` (v3.5) · `useId()` requires no arguments vs older patterns · Custom element `defineCustomElement(options, extraOptions)` now takes second argument (v3.5) · Props destructuring with defaults no longer requires `withDefaults()` (v3.5)
<!-- /skilld:api-changes -->

<!-- skilld:best-practices -->
## Best Practices

- Use **reactive props destructuring** (v3.5+) — destructured variables from `defineProps` are automatically reactive. Pair with destructuring default values for cleaner prop declarations: `const { count = 0, msg = 'hello' } = defineProps<{ count?: number; msg?: string }>()` [source](./.skilld/releases/blog-3.5.md#reactive-props-destructure)

- Prefer `computed()` over methods for derived values — computed properties cache results based on reactive dependencies and only re-evaluate when dependencies change, while methods re-run on every render [source](./.skilld/docs/guide/essentials/computed.md#computed-caching-vs-methods)

- Avoid creating new objects in computed properties — if your computed must return an object, manually compare with the previous value to avoid triggering effects unnecessarily, since Vue cannot detect deep changes [source](./.skilld/docs/guide/best-practices/performance.md#computed-stability)

- Use `useTemplateRef()` for template refs (v3.5+) — replaces the older pattern of manually declaring refs matching template `ref` names. Provides better type inference and supports dynamic `ref` bindings: `const input = useTemplateRef('my-input')` [source](./.skilld/docs/guide/essentials/template-refs.md#accessing-the-refs)

- Keep props stable to minimize child updates — compute derived props in the parent rather than passing unstable values, so only items whose state actually changed re-render [source](./.skilld/docs/guide/best-practices/performance.md#props-stability)

- Use `shallowRef()` and `shallowReactive()` for large immutable structures — opt out of deep reactivity to reduce overhead for large deeply-nested objects or arrays, but treat nested values as immutable [source](./.skilld/docs/guide/best-practices/performance.md#reduce-reactivity-overhead-for-large-immutable-structures)

- Use getter functions with `watch()` for reactive object properties — never watch a property directly like `watch(obj.count, ...)`. Instead wrap in a getter: `watch(() => obj.count, ...)` [source](./.skilld/docs/guide/essentials/watchers.md#watch-source-types)

- Lazy-load async components with `defineAsyncComponent()` and dynamic `import()` — lets bundlers split code automatically and load components only when rendered [source](./.skilld/docs/guide/components/async.md#basic-usage)

- Use lazy hydration strategies with async components in SSR (v3.5+) — control when async components hydrate on the client using `hydrateOnIdle()` or `hydrateOnVisible()` to improve performance and UX [source](./.skilld/docs/guide/components/async.md#lazy-hydration)

- Use `onWatcherCleanup()` for side effect cleanup (v3.5+) — register cleanup logic inside watchers for async operations to cancel stale requests, properly replacing the older `onCleanup` pattern [source](./.skilld/releases/blog-3.5.md#onwatchercleanup)

- Compose small, focused composables and nest them — extract reusable stateful logic into functions starting with "use" that handle lifecycle (e.g., `onMounted`, `onUnmounted`) and return reactive state [source](./.skilld/docs/guide/reusability/composables.md#what-is-a-composable)

- Use `defineModel()` for v-model binding (v3.4+) — simplifies two-way binding by automatically handling `modelValue` prop and `update:modelValue` emit, working like a normal ref [source](./.skilld/docs/guide/components/v-model.md#basic-usage)

- Use `useId()` for SSR-safe unique IDs (v3.5+) — generates stable, unique-per-application IDs without causing hydration mismatches on form elements and accessibility attributes [source](./.skilld/releases/blog-3.5.md#useid)

- Apply `v-memo` to large subtrees and v-for lists for targeted performance — conditionally skip updates for subtrees when dependencies haven't changed, avoiding unnecessary re-renders on every parent update [source](./.skilld/docs/guide/built-ins/template-syntax.md#v-memo)
<!-- /skilld:best-practices -->

Install it elsewhere with curl -o .claude/skills/vue-skilld/SKILL.md --create-dirs https://uxlab.designcoder.net/api/skills/vue-skilld/source. Record what you changed in this page's notes.