fix(runtime-core): avoid setting direct ref of useTemplateRef in dev #13449

alex-snezhko · 2025-06-08T20:39:46Z

Avoid directly setting the ref value in dev mode whenever a ref object from a useTemplateRef call is used for rendering, updating only the component owner refs object instead (which useTemplateRef is hooked up to correctly update from).

When code like the following:

<script setup>
import { useTemplateRef } from 'vue'
const myRef = useTemplateRef('myRef')
</script>

<template>
  <div ref="myRef">Foo</div>
</template>

is compiled in inline mode the output would contain:

createElementBlock("div", {
  ref_key: "myRef",
  ref: myRef
}, "Foo")

which then attempts to update the myRef object directly, showing a warning: Set operation on key "value" failed: target is readonly.; this change should avoid this warning from showing.

closes #12852

Summary by CodeRabbit

Tests
- Expanded coverage for template ref behavior with direct refs, ref_key, ref_for, and dynamic rendering across development and production modes, including negative/edge cases for warnings and lifecycle updates.
Bug Fixes
- Added guards to prevent unintended ref assignments and improved cleanup of stored refs during updates, ensuring correct behavior for multiple and dynamic refs.

coderabbitai · 2025-06-08T20:39:54Z

Walkthrough

Guards were added around template-ref assignments via a new canSetRef helper to avoid setting .value on known template refs in development; ref cleanup was enhanced. The test suite for useTemplateRef was expanded with scenarios for direct refs, ref_key, ref_for, dynamic keys, and production/dev modes.

Changes

Cohort / File(s)	Change Summary
Runtime template-ref logic `packages/runtime-core/src/rendererTemplateRef.ts`	Introduced `canSetRef` guard used around all `.value` assignments and retrievals, added cleanup of owner's refs map when unsetting reactive old refs, and adjusted array-ref handling to honor the guard.
Tests for useTemplateRef `packages/runtime-core/__tests__/helpers/useTemplateRef.spec.ts`	Added comprehensive tests covering direct refs with `ref_key`, `ref_for`, dynamic render changes, dynamic `ref_key`, dev-mode negative case, and production-mode scenarios; assert warning behavior and ref values.

Sequence Diagram(s)

sequenceDiagram
    participant Component
    participant Renderer
    participant RefHelper as canSetRef
    participant Owner as Owner.refs

    Component->>Renderer: render vnode with template ref (rawRef, key k?, for?)
    Renderer->>RefHelper: canSetRef(rawRef)
    alt canSetRef = true
        RefHelper-->>Renderer: true
        Renderer->>rawRef: set rawRef.value (element or array)
        alt oldRawRef is reactive and has key k
            Renderer->>Owner: clear Owner.refs[k]
        end
    else canSetRef = false
        RefHelper-->>Renderer: false
        Renderer-->>Owner: update Owner.refs map instead of rawRef.value (if applicable)
    end
    Renderer->>Component: render complete (refs updated/cleaned)

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Assessment against linked issues

Objective	Addressed	Explanation
Suppress "Set operation on key 'value' failed: target is readonly" warning for useTemplateRef with direct ref and `ref_key` (#12852)	✅
Ensure correct ref assignment and cleanup for direct refs, dynamic keys, and arrays (#12852)	✅
No warnings in production mode for useTemplateRef with direct refs and `ref_key` (#12852)	✅

Possibly related PRs

vuejs/core#12900: touches ref-unsetting behavior in runtime-core; likely related to cleanup semantics adjusted here.

Suggested labels

scope: reactivity

Poem

In burrows of code where the template refs play,
I hop through the logic and chase bugs away.
Keys cleared, values guarded, no readonly alarm —
Tests snugly expanded to hold everything calm.
A rabbit-approved patch — light feet, steady charm. 🐇

Tip

🔌 Remote MCP (Model Context Protocol) integration is now available!

Pro plan users can now connect to remote MCP servers from the Integrations page. Connect with popular remote MCPs such as Notion and Linear to add more context to your reviews and chats.

📜 Recent review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

💡 Knowledge Base configuration:

MCP integration is disabled by default for public repositories
Jira integration is disabled by default for public repositories
Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between db8a3c1 and 7603545.

📒 Files selected for processing (1)

packages/runtime-core/src/rendererTemplateRef.ts (6 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

packages/runtime-core/src/rendererTemplateRef.ts

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

GitHub Check: test / e2e-test

✨ Finishing Touches

📝 Generate Docstrings

🧪 Generate unit tests

Create PR with unit tests
Post copyable unit tests in a comment

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

Review comments: Directly reply to a review comment made by CodeRabbit. Example:
- I pushed a fix in commit <commit_id>, please review it.
- Open a follow-up GitHub issue for this discussion.
Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query.
PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
- @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
- @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

CodeRabbit Commands (Invoked using PR/Issue comments)

Type @coderabbitai help to get the list of available commands.

Other keywords and placeholders

Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (`.coderabbit.yaml`)

You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
Please see the configuration documentation for more information.
If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Status, Documentation and Community

Visit our Status Page to check the current availability of CodeRabbit.
Visit our Documentation for detailed information on how to use CodeRabbit.
Join our Discord Community to get help, request features, and share feedback.
Follow us on X/Twitter for updates and announcements.

github-actions · 2025-06-08T20:40:47Z

Size Report

Bundles

File	Size	Gzip	Brotli
runtime-dom.global.prod.js	101 kB (+42 B)	38.4 kB (+14 B)	34.6 kB (+11 B)
vue.global.prod.js	159 kB (+42 B)	58.6 kB (+14 B)	52.1 kB (+16 B)

Usages

Name	Size	Gzip	Brotli
createApp (CAPI only)	46.7 kB (+42 B)	18.2 kB (+9 B)	16.7 kB (+7 B)
createApp	54.6 kB (+42 B)	21.3 kB (+11 B)	19.4 kB (+8 B)
createSSRApp	58.8 kB (+42 B)	23 kB (+15 B)	21 kB (+8 B)
defineCustomElement	59.6 kB (+42 B)	22.8 kB (+11 B)	20.8 kB (+9 B)
overall	68.7 kB (+42 B)	26.4 kB (+9 B)	24.1 kB (+22 B)

pkg-pr-new · 2025-06-08T20:40:57Z

Open in StackBlitz

@vue/compiler-core

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

@vue/compiler-dom

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

@vue/compiler-sfc

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

@vue/compiler-ssr

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

@vue/reactivity

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

@vue/runtime-core

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

@vue/runtime-dom

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

@vue/server-renderer

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

@vue/shared

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

vue

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

@vue/compat

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

commit: 7603545

packages/vue/__tests__/e2e/Transition.spec.ts

edison1105 · 2025-06-09T00:27:29Z

/ecosystem-ci run

vue-bot · 2025-06-09T01:42:25Z

📝 Ran ecosystem CI: Open

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

packages/runtime-core/src/rendererTemplateRef.ts

fix(runtime-core): avoid setting direct ref of useTemplateRef in dev

b8e63f7

alex-snezhko commented Jun 8, 2025

View reviewed changes

packages/vue/__tests__/e2e/Transition.spec.ts Outdated Show resolved Hide resolved

edison1105 added the 🔨 p3-minor-bug Priority 3: this fixes a bug, but is an edge case that only affects very specific usage. label Jun 9, 2025

zhouxianjun mentioned this pull request Jun 9, 2025

useTemplateRef warning appears after rollup packaging #12852

Closed

fix: revert transition test change

1ad19a8

edison1105 reviewed Jun 10, 2025

View reviewed changes

packages/runtime-core/src/rendererTemplateRef.ts Show resolved Hide resolved

test: add tests with ref_for in prod mode

db8a3c1

edison1105 added the ready to merge The PR is ready to be merged. label Jun 11, 2025

Merge branch 'main' into readonly-template-ref-no-set

7603545

edison1105 merged commit 4a2953f into vuejs:main Aug 21, 2025
14 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix(runtime-core): avoid setting direct ref of useTemplateRef in dev #13449

fix(runtime-core): avoid setting direct ref of useTemplateRef in dev #13449

alex-snezhko commented Jun 8, 2025 •

edited by coderabbitai bot

Loading

Uh oh!

coderabbitai bot commented Jun 8, 2025 •

edited

Loading

Chat

Support

CodeRabbit Commands (Invoked using PR/Issue comments)

Other keywords and placeholders

CodeRabbit Configuration File (`.coderabbit.yaml`)

Status, Documentation and Community

Uh oh!

github-actions bot commented Jun 8, 2025 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Jun 8, 2025 •

edited

Loading

Uh oh!

Uh oh!

edison1105 commented Jun 9, 2025

Uh oh!

vue-bot commented Jun 9, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

fix(runtime-core): avoid setting direct ref of useTemplateRef in dev #13449

fix(runtime-core): avoid setting direct ref of useTemplateRef in dev #13449

Conversation

alex-snezhko commented Jun 8, 2025 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

coderabbitai bot commented Jun 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Assessment against linked issues

Possibly related PRs

Suggested labels

Poem

Chat

Support

CodeRabbit Commands (Invoked using PR/Issue comments)

Other keywords and placeholders

CodeRabbit Configuration File (.coderabbit.yaml)

Status, Documentation and Community

Uh oh!

github-actions bot commented Jun 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Size Report

Bundles

Usages

Uh oh!

pkg-pr-new bot commented Jun 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

edison1105 commented Jun 9, 2025

Uh oh!

vue-bot commented Jun 9, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

alex-snezhko commented Jun 8, 2025 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Jun 8, 2025 •

edited

Loading

CodeRabbit Configuration File (`.coderabbit.yaml`)

github-actions bot commented Jun 8, 2025 •

edited

Loading

pkg-pr-new bot commented Jun 8, 2025 •

edited

Loading