fix(useTemplateRef): don't update setup ref for useTemplateRef key

[edison1105]

close #12749

Summary by CodeRabbit

Release Notes

• Bug Fixes

  • Fixed template ref independence to prevent cross-updates between different ref types in both development and production modes.

• Tests

  • Added comprehensive test coverage for template ref key behavior, including production-mode scenarios.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[github-actions]

Size Report

Bundles

File	Size	Gzip	Brotli
runtime-dom.global.prod.js	103 kB (+175 B)	39.1 kB (+67 B)	35.2 kB (+69 B)
vue.global.prod.js	162 kB (+175 B)	59.1 kB (+66 B)	52.6 kB (+20 B)

Usages

Name	Size	Gzip	Brotli
createApp (CAPI only)	47.2 kB (+175 B)	18.4 kB (+74 B)	16.9 kB (+67 B)
createApp	55.3 kB (+175 B)	21.5 kB (+72 B)	19.6 kB (-5 B)
createSSRApp	59.6 kB (+175 B)	23.2 kB (+59 B)	21.2 kB (+63 B)
defineCustomElement	60.9 kB (+175 B)	23.2 kB (+79 B)	21.2 kB (+64 B)
overall	69.7 kB (+175 B)	26.7 kB (+67 B)	24.4 kB (+112 B)

[pkg-pr-new]

Open in StackBlitz

@vue/compiler-core

pnpm add https://pkg.pr.new/@vue/compiler-core@12756

npm i https://pkg.pr.new/@vue/compiler-core@12756

yarn add https://pkg.pr.new/@vue/[email protected]

@vue/compiler-dom

pnpm add https://pkg.pr.new/@vue/compiler-dom@12756

npm i https://pkg.pr.new/@vue/compiler-dom@12756

yarn add https://pkg.pr.new/@vue/[email protected]

@vue/compiler-sfc

pnpm add https://pkg.pr.new/@vue/compiler-sfc@12756

npm i https://pkg.pr.new/@vue/compiler-sfc@12756

yarn add https://pkg.pr.new/@vue/[email protected]

@vue/compiler-ssr

pnpm add https://pkg.pr.new/@vue/compiler-ssr@12756

npm i https://pkg.pr.new/@vue/compiler-ssr@12756

yarn add https://pkg.pr.new/@vue/[email protected]

@vue/reactivity

pnpm add https://pkg.pr.new/@vue/reactivity@12756

npm i https://pkg.pr.new/@vue/reactivity@12756

yarn add https://pkg.pr.new/@vue/[email protected]

@vue/runtime-core

pnpm add https://pkg.pr.new/@vue/runtime-core@12756

npm i https://pkg.pr.new/@vue/runtime-core@12756

yarn add https://pkg.pr.new/@vue/[email protected]

@vue/runtime-dom

pnpm add https://pkg.pr.new/@vue/runtime-dom@12756

npm i https://pkg.pr.new/@vue/runtime-dom@12756

yarn add https://pkg.pr.new/@vue/[email protected]

@vue/server-renderer

pnpm add https://pkg.pr.new/@vue/server-renderer@12756

npm i https://pkg.pr.new/@vue/server-renderer@12756

yarn add https://pkg.pr.new/@vue/[email protected]

@vue/shared

pnpm add https://pkg.pr.new/@vue/shared@12756

npm i https://pkg.pr.new/@vue/shared@12756

yarn add https://pkg.pr.new/@vue/[email protected]

vue

pnpm add https://pkg.pr.new/vue@12756

npm i https://pkg.pr.new/vue@12756

yarn add https://pkg.pr.new/[email protected]

@vue/compat

pnpm add https://pkg.pr.new/@vue/compat@12756

npm i https://pkg.pr.new/@vue/compat@12756

yarn add https://pkg.pr.new/@vue/[email protected]

commit: 58a9da2

[jh-leong]

It seems this change might break an existing case: Playground

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR fixes a conflict where useTemplateRef and defineModel could not coexist with the same name by introducing key-aware ref handling. A new helper function checks if a key belongs to a useTemplateRef, preventing template refs from overriding other ref-like constructs during assignment and cleanup operations.

Changes

Cohort / File(s)	Summary
useTemplateRef Helper packages/runtime-core/src/helpers/useTemplateRef.ts	Extracts template ref key detection logic into a new exported helper function isTemplateRefKey(refs, key) that encapsulates property descriptor checking and enables external callers to determine if a key is already used by useTemplateRef.
Renderer Template Ref Gating packages/runtime-core/src/rendererTemplateRef.ts	Integrates key-aware gating throughout template ref assignment and cleanup: updates canSetRef() to accept optional key parameter, skips ref assignment for useTemplateRef keys in setup refs, gates old-ref cleanup, and passes key information at all call sites to prevent useTemplateRef keys from being overwritten.
useTemplateRef Tests packages/runtime-core/__tests__/helpers/useTemplateRef.spec.ts	Adds two new test cases verifying that setup refs used by useTemplateRef remain independent from template refs sharing the same static key, with coverage for both dev and prod modes using onMounted and DEV guards.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• fix(templateRef): prevent unnecessary set ref on dynamic ref change or component unmount #12642 — Also modifies rendererTemplateRef to change ref-setting behavior, but adds job scheduling/cancellation rather than key-aware gating
• fix(runtime-core): avoid setting direct ref of useTemplateRef in dev #13449 — Modifies ref-setting checks in rendererTemplateRef and useTemplateRef logic to prevent direct ref setting in dev mode, touching overlapping code paths

Suggested labels

ready to merge, :hammer: p3-minor-bug

Suggested reviewers

• LittleSound
• sxzz

Poem

🐰 A template ref and a model collide,
Keys intertwined with nowhere to hide,
But now with awareness, each knows its place,
useTemplateRef won't steal defineModel's grace! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main fix: preventing setup refs from being updated when a useTemplateRef key is used, which directly addresses the core issue.
Linked Issues check	✅ Passed	The PR implements the required fix: it prevents defineModel-declared constants from being overwritten by template refs through key-aware checks in useTemplateRef and rendererTemplateRef.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to fixing the useTemplateRef/defineModel conflict: adding key-aware ref handling logic, new helper function, and comprehensive tests.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[edison1105]

/ecosystem-ci run

[vue-bot]

📝 Ran ecosystem CI: Open

suite	result	latest scheduled
nuxt	✅ success	✅ success
language-tools	✅ success	✅ success
pinia	✅ success	✅ success
primevue	✅ success	✅ success
test-utils	✅ success	✅ success
quasar	✅ success	✅ success
router	❌ failure	❌ failure
vant	❌ failure	✅ success
radix-vue	✅ success	✅ success
vue-i18n	✅ success	✅ success
vue-simple-compiler	✅ success	✅ success
vite-plugin-vue	✅ success	✅ success
vue-macros	✅ success	✅ success
vuetify	✅ success	✅ success
vueuse	✅ success	✅ success
vitepress	✅ success	✅ success