fix(compiler-core): preserve vnode lifecycle in stable v-for

[edison1105]

close #9239
close #12569

I’m not sure if this change is correct. Here is my understanding:
When an element uses ref, vnodeHook, or custom directives, the patchFlag should be NEED_PATCH. However, when they are used together with v-for, the patchFlag gets lost.
related commit 1c9a481

playground
playground with this PR

The following problems will be fixed

• vFor + ref / with this PR
• vFor + ref(function) / with this PR
• vFor + vnode hook / with this PR
• vFor + custom directive / with this PR
  • Custom directive's unmounted event is not triggered on v-for element #12569

The last two are from #9240 (comment) created by skirtles-code

Summary by CodeRabbit

• Bug Fixes

  • Improved update detection for elements inside v-for loops using refs, custom directives, and vnode hooks.
  • Preserved required updates for stable repeated content, including directive and lifecycle hook behavior.
  • Improved cleanup of refs and unmount callbacks when repeated or conditional content is removed.
  • Corrected update handling when other patch information is already present.

• Tests

  • Added coverage for patching, ref cleanup, callback handling, and update-hook ordering across these scenarios.

[github-actions]

Size Report

Bundles

File	Size	Gzip	Brotli
runtime-dom.global.prod.js	108 kB	40.7 kB	36.5 kB
vue.global.prod.js	167 kB (+305 B)	60.9 kB (+124 B)	54.2 kB (+165 B)

Usages

Name	Size	Gzip	Brotli
createApp (CAPI only)	49.7 kB	19.3 kB	17.7 kB
createApp	57.8 kB	22.3 kB	20.4 kB
createSSRApp	62.5 kB	24.3 kB	22.1 kB
defineCustomElement	64.1 kB	24.3 kB	22.1 kB
overall	72.1 kB	27.5 kB	25.1 kB

[pkg-pr-new]

Open in StackBlitz

@vue/compiler-core

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

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

yarn add https://pkg.pr.new/@vue/compiler-core@11682.tgz

@vue/compiler-dom

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

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

yarn add https://pkg.pr.new/@vue/compiler-dom@11682.tgz

@vue/compiler-sfc

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

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

yarn add https://pkg.pr.new/@vue/compiler-sfc@11682.tgz

@vue/compiler-ssr

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

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

yarn add https://pkg.pr.new/@vue/compiler-ssr@11682.tgz

@vue/reactivity

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

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

yarn add https://pkg.pr.new/@vue/reactivity@11682.tgz

@vue/runtime-core

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

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

yarn add https://pkg.pr.new/@vue/runtime-core@11682.tgz

@vue/runtime-dom

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

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

yarn add https://pkg.pr.new/@vue/runtime-dom@11682.tgz

@vue/server-renderer

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

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

yarn add https://pkg.pr.new/@vue/server-renderer@11682.tgz

@vue/shared

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

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

yarn add https://pkg.pr.new/@vue/shared@11682.tgz

vue

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

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

yarn add https://pkg.pr.new/vue@11682.tgz

@vue/compat

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

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

yarn add https://pkg.pr.new/@vue/compat@11682.tgz

commit: a6e60cb

[coderabbitai]

📝 Walkthrough

Walkthrough

The compiler now separates patch requirements from block requirements for stable v-for elements. The v-for transform preserves required blocks and adds NEED_PATCH where needed. Tests cover refs, directives, vnode hooks, and lifecycle cleanup.

Changes

Compiler patch flag analysis

Layer / File(s)	Summary
Patch flag detection packages/compiler-core/src/ast.ts, packages/compiler-core/src/transforms/transformElement.ts	VNodeCall records needsPatch and isBlockRequired. Element transformation tracks refs, vnode hooks, runtime directives, and block requirements separately.
Stable v-for block selection packages/compiler-core/src/transforms/vFor.ts	Stable v-for children retain required blocks. Non-block children that require patching receive NEED_PATCH.
Compiler and runtime validation packages/compiler-core/__tests__/transforms/transformElement.spec.ts, packages/vue/__tests__/index.spec.ts	Tests cover patch flags, block status, ref cleanup, function-ref nulling, directive and vnode unmount hooks, and update-hook ordering.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant transformElement
  participant buildProps
  participant vFor
  transformElement->>buildProps: analyze refs, hooks, directives, and block requirements
  buildProps-->>transformElement: return needsPatch and isBlockRequired
  transformElement->>vFor: provide annotated child VNode call
  vFor->>vFor: retain required blocks or add NEED_PATCH

Loading

Possibly related PRs

• vuejs/core#12411: Modifies runtime fragment diffing for stable v-for and fragment patching, while this change modifies compiler block and patch-flag generation.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes address ref cleanup in v-for and directive unmounted hooks, covering the objectives in [#9239] and [#12569].
Out of Scope Changes check	✅ Passed	The compiler changes and lifecycle tests remain within the stated v-for patch-flag and cleanup objectives.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main compiler change: preserving vnode lifecycle behavior in stable v-for rendering.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[edison1105]

@copilot resolve the merge conflicts in this pull request

[edison1105]

@copilot resolve the merge conflicts in this pull request

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (6)

packages/compiler-core/__tests__/transforms/transformElement.spec.ts (2)

1089-1096: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Add prefixIdentifiers for consistency with the sibling tests.

The other new tests pass { prefixIdentifiers: true }. This test omits it, so it exercises a different codegen mode. The assertion still holds, but the difference is not intentional-looking.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/compiler-core/__tests__/transforms/transformElement.spec.ts` around
lines 1089 - 1096, Add `{ prefixIdentifiers: true }` to the
`parseWithForTransform` options in the `preserve block for stable v-for + custom
directive with children` test, matching the sibling tests while preserving its
existing assertions.

---

1098-1112: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add a case for the camelCase hook alias.

This test covers @vue:before-update. transformOn also accepts @vue:beforeUpdate, and the block-requirement check in transformElement.ts (lines 599-604) matches only the hyphenated form. Add a test with @vue:beforeUpdate to lock the behavior after that check is normalized.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/compiler-core/__tests__/transforms/transformElement.spec.ts` around
lines 1098 - 1112, Extend the existing “preserve block for stable v-for +
before-update vnode hook” test coverage with a camelCase `@vue:beforeUpdate`
variant, using the same transform options and assertions for
`getVForChild(node)`, `isBlock`, and `patchFlag`. This should validate the
normalized block-requirement check in `transformElement.ts` for both hook
aliases.

packages/vue/__tests__/index.spec.ts (2)

8-16: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

The new Function hint is a false positive here.

Every call site passes a literal template that is written in this test file, so no untrusted input reaches compile. The helper mirrors the production compileToFunction in packages/vue/src/index.ts. No change is needed.

One optional simplification: Vue.compile in the full build already applies the same steps and sets _rc. Reusing it would remove the duplicated harness.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/vue/__tests__/index.spec.ts` around lines 8 - 16, No code change is
required for the new Function usage in compileToFunction because all test
templates are literals and the helper intentionally mirrors the production
implementation. Optionally simplify the test harness by reusing Vue.compile,
which already performs compilation and sets _rc.

Source: Linters/SAST tools

---

407-412: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Assert the full call sequence for the function ref.

values[values.length - 1] passes even if the ref function is invoked extra times during the update. An exact assertion locks the expected sequence of one element followed by one null.

♻️ Proposed stricter assertion

       app.mount(container)
-      expect(values).toHaveLength(1)
-      expect(values[0]).toBeInstanceOf(HTMLDivElement)
+      expect(values).toHaveLength(1)
+      expect(values[0]).toBeInstanceOf(HTMLDivElement)
 
       show.value = false
       await nextTick()
-      expect(values[values.length - 1]).toBeNull()
+      expect(values).toHaveLength(2)
+      expect(values[1]).toBeNull()

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/vue/__tests__/index.spec.ts` around lines 407 - 412, Strengthen the
assertions in the function-ref test around the show.value toggle so it verifies
the complete values sequence, exactly one element reference followed by one
null, rather than checking only the last entry. Keep the existing initial
element validation and nextTick update flow unchanged.

packages/compiler-core/src/transforms/vFor.ts (1)

211-217: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Simplify the patch-flag merge.

The undefined branch exists only to satisfy the type of |. A nullish default removes the branch.

♻️ Proposed simplification

             if (childBlock.needsPatch) {
-              childBlock.patchFlag =
-                childBlock.patchFlag === undefined
-                  ? PatchFlags.NEED_PATCH
-                  : ((childBlock.patchFlag |
-                      PatchFlags.NEED_PATCH) as PatchFlags)
+              childBlock.patchFlag =
+                ((childBlock.patchFlag ?? 0) | PatchFlags.NEED_PATCH) as PatchFlags
             }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/compiler-core/src/transforms/vFor.ts` around lines 211 - 217, In the
childBlock patch-flag update within the vFor transform, simplify the undefined
handling by defaulting childBlock.patchFlag to the empty numeric flag before
OR-ing PatchFlags.NEED_PATCH. Remove the conditional branch while preserving the
resulting NEED_PATCH flag for both undefined and existing patch flags.

packages/compiler-core/src/transforms/transformElement.ts (1)

760-765: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

needsPatch can stay true after transformElement adds more patch flags.

buildProps computes needsPatch from the props-only patchFlag. transformElement can later add TEXT or DYNAMIC_SLOTS to the same flag (lines 158, 181, 194). For a stable v-for child with a vnode hook and a dynamic text child, needsPatch stays true, so vFor ORs NEED_PATCH onto TEXT when it demotes the block. The result is still correct, because any non-zero patch flag makes the parent block track the vnode, but NEED_PATCH is then redundant in the generated code. Consider clearing needsPatch in transformElement when the final patchFlag already requires patching.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/compiler-core/src/transforms/transformElement.ts` around lines 760 -
765, Recompute or clear needsPatch in transformElement after adding TEXT or
DYNAMIC_SLOTS to patchFlag, so it is false when the final patchFlag is already
non-zero and does not require NEED_PATCH. Update the needsPatch handling near
the final patchFlag logic while preserving NEED_PATCH for cases whose completed
patchFlag still indicates no other patching.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/compiler-core/src/transforms/transformElement.ts`:
- Around line 599-604: The before-update block check in transformElement must
recognize both hyphenated and camelCase aliases. In
packages/compiler-core/src/transforms/transformElement.ts:599-604, normalize the
static arg with camelize before comparing it to vue:beforeUpdate; in
packages/compiler-core/__tests__/transforms/transformElement.spec.ts:1098-1112,
add a sibling test using `@vue`:beforeUpdate and assert child.isBlock === true.

---

Nitpick comments:
In `@packages/compiler-core/__tests__/transforms/transformElement.spec.ts`:
- Around line 1089-1096: Add `{ prefixIdentifiers: true }` to the
`parseWithForTransform` options in the `preserve block for stable v-for + custom
directive with children` test, matching the sibling tests while preserving its
existing assertions.
- Around line 1098-1112: Extend the existing “preserve block for stable v-for +
before-update vnode hook” test coverage with a camelCase `@vue:beforeUpdate`
variant, using the same transform options and assertions for
`getVForChild(node)`, `isBlock`, and `patchFlag`. This should validate the
normalized block-requirement check in `transformElement.ts` for both hook
aliases.

In `@packages/compiler-core/src/transforms/transformElement.ts`:
- Around line 760-765: Recompute or clear needsPatch in transformElement after
adding TEXT or DYNAMIC_SLOTS to patchFlag, so it is false when the final
patchFlag is already non-zero and does not require NEED_PATCH. Update the
needsPatch handling near the final patchFlag logic while preserving NEED_PATCH
for cases whose completed patchFlag still indicates no other patching.

In `@packages/compiler-core/src/transforms/vFor.ts`:
- Around line 211-217: In the childBlock patch-flag update within the vFor
transform, simplify the undefined handling by defaulting childBlock.patchFlag to
the empty numeric flag before OR-ing PatchFlags.NEED_PATCH. Remove the
conditional branch while preserving the resulting NEED_PATCH flag for both
undefined and existing patch flags.

In `@packages/vue/__tests__/index.spec.ts`:
- Around line 8-16: No code change is required for the new Function usage in
compileToFunction because all test templates are literals and the helper
intentionally mirrors the production implementation. Optionally simplify the
test harness by reusing Vue.compile, which already performs compilation and sets
_rc.
- Around line 407-412: Strengthen the assertions in the function-ref test around
the show.value toggle so it verifies the complete values sequence, exactly one
element reference followed by one null, rather than checking only the last
entry. Keep the existing initial element validation and nextTick update flow
unchanged.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 0f115176-c5ff-46ba-8a7d-2e87a7712f1f

📥 Commits

Reviewing files that changed from the base of the PR and between 6f0803f and 88d2699.

📒 Files selected for processing (5)

• packages/compiler-core/__tests__/transforms/transformElement.spec.ts
• packages/compiler-core/src/ast.ts
• packages/compiler-core/src/transforms/transformElement.ts
• packages/compiler-core/src/transforms/vFor.ts
• packages/vue/__tests__/index.spec.ts

[edison1105]

/ecosystem-ci run

[vue-bot]

📝 Ran ecosystem CI: Open

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