fix(custom-element): batch custom element prop patching

[alex-snezhko]

close #12619

Applies prop updates on custom elements in batch before rendering instead of one at a time serially, resolving discrepancies in behavior compared to normal components.

Summary by CodeRabbit

• New Features
  • Improved custom element update behavior to batch prop changes and defer updates until patching completes, resulting in more efficient and predictable rendering.
• Bug Fixes
  • Ensured watchers on custom element props are triggered correctly and only when actual changes occur, including support for simultaneous prop updates.
• Tests
  • Added tests to verify correct batching and watcher behavior for both synchronous and asynchronous custom elements.

[github-actions[bot]]

Size Report

Bundles

File	Size	Gzip	Brotli
runtime-dom.global.prod.js	102 kB (+276 B)	38.8 kB (+93 B)	34.9 kB (+80 B)
vue.global.prod.js	161 kB (+276 B)	58.7 kB (+100 B)	52.2 kB (+31 B)

Usages

Name	Size	Gzip	Brotli
createApp (CAPI only)	46.9 kB (+94 B)	18.3 kB (+37 B)	16.8 kB (+33 B)
createApp	55 kB (+94 B)	21.4 kB (+38 B)	19.5 kB (+43 B)
createSSRApp	59.2 kB (+94 B)	23.1 kB (+35 B)	21.1 kB (+41 B)
defineCustomElement	60.6 kB (+276 B)	23.1 kB (+81 B)	21.1 kB (+78 B)
overall	69.2 kB (+94 B)	26.6 kB (+39 B)	24.2 kB (+68 B)

[pkg-pr-new[bot]]

Open in StackBlitz

@vue/compiler-core

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

@vue/compiler-dom

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

@vue/compiler-sfc

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

@vue/compiler-ssr

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

@vue/reactivity

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

@vue/runtime-core

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

@vue/runtime-dom

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

@vue/server-renderer

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

@vue/shared

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

vue

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

@vue/compat

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

commit: 0b60a8b

[coderabbitai[bot]]

Walkthrough

Adds internal patch lifecycle hooks to component interface, invokes those hooks from the renderer when patching existing Vue custom elements, implements patching/batching state in VueElement to defer and flush prop updates, and adds tests (sync and async) verifying batched prop updates and watcher behavior.

Changes

Cohort / File(s)	Change Summary
Core interface packages/runtime-core/src/component.ts	Added internal methods _beginPatch(): void and _endPatch(): void to ComponentCustomElementInterface.
Renderer packages/runtime-core/src/renderer.ts	When patching an existing element vnode (n1), detect Vue custom element (_isVueCE) and call _beginPatch() before and _endPatch() after patchElement(), with _endPatch() ensured in a finally block.
Custom element runtime packages/runtime-dom/src/apiCustomElement.ts	Added private flags _patching and _dirty to VueElement. During a patch, pass !this._patching as shouldUpdate to _setProp, mark _dirty when prop values change, and implement _beginPatch() / _endPatch() to batch/defer updates and flush a single update at patch end if needed.
Tests packages/runtime-dom/__tests__/customElement.spec.ts	Added synchronous and async tests under defineCustomElement that patch multiple props together and assert watcher invocation counts and updated render output reflecting batched updates.

Sequence Diagram(s)

sequenceDiagram
    participant Renderer
    participant VueElement
    participant ComponentInstance

    Renderer->>VueElement: detect _isVueCE on existing element (n1.el)
    Renderer->>VueElement: _beginPatch()
    Note right of VueElement: _patching = true\n_dirty = false
    Renderer->>VueElement: resolve and set multiple props (shouldUpdate = false)
    VueElement->>VueElement: on prop change -> _dirty = true
    Renderer->>Renderer: patchElement()  %% vnode patch runs (component updates)
    Renderer->>VueElement: _endPatch()
    Note right of VueElement: _patching = false\nif _dirty -> schedule/trigger update
    VueElement->>ComponentInstance: trigger update (batched)

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• vuejs/core#13897 — Touches VueElement update flow and mutation/flush logic in packages/runtime-dom/src/apiCustomElement.ts (strong code-level overlap).
• vuejs/core#12855 — Modifies VueElement internals and prop resolution timing in packages/runtime-dom/src/apiCustomElement.ts (related to prop/lifecycle handling).

Assessment against linked issues

Objective	Addressed	Explanation
Ensure watchers in a custom element see the latest values of other props when multiple props are updated together. (#12619)	✅	Batched prop updates during patch ensure watchers observe consolidated/latest prop values after patch end.

Poem

🐇
I nibble bugs beneath the moonlit keys,
I begin the patch and quiet the breeze.
Dirty flags wait while props align,
End the patch — watchers see values fine.
Hoppity hop, the DOM's in time!

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title clearly and concisely describes the primary change in this pull request, namely batching custom element prop patching to fix watcher behavior, and follows the conventional commit format without extraneous detail.
Linked Issues Check	✅ Passed	The changes implement internal patch lifecycle hooks, adjust prop update logic to batch changes during patching, and add tests that confirm watchers observe the latest prop values, directly addressing the stale-prop issue described in issue #12619.
Out of Scope Changes Check	✅ Passed	All modifications—including interface method additions, runtime-core hook integration, runtime-dom batching logic, and tests—are focused on implementing batched prop patching for custom elements and do not introduce unrelated functionality.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

• [ ] 📝 Generate docstrings

🧪 Generate unit tests (beta)

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between fb4e8c75af7a387aaff57dc58c2d29f642dba856 and ab92d970be1e86e0bf2e511746fe131856a2febd.

📒 Files selected for processing (3)

• packages/runtime-core/src/component.ts (1 hunks)
• packages/runtime-dom/__tests__/customElement.spec.ts (1 hunks)
• packages/runtime-dom/src/apiCustomElement.ts (4 hunks)

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

• packages/runtime-dom/tests/customElement.spec.ts

🔇 Additional comments (6)

packages/runtime-core/src/component.ts (1)

1273-1280: LGTM! Clean interface additions for patch lifecycle.

The addition of _beginPatch() and _endPatch() internal methods to the ComponentCustomElementInterface follows the existing pattern of internal lifecycle hooks and enables custom elements to batch prop updates during renderer patch operations.

packages/runtime-dom/src/apiCustomElement.ts (5)

232-233: Well-chosen flags for batching state.

The _patching and _dirty flags clearly track the batching lifecycle: _patching indicates an active batch session, while _dirty tracks whether any props changed during that session. Both default to false, which is correct for the initial state.

---

473-478: Correct integration of batching in property setter.

The property setter now passes !this._patching as the shouldUpdate parameter to _setProp, which correctly defers updates during patching while still reflecting attributes. When not patching, updates trigger immediately as before.

---

510-511: Proper dirty flag tracking.

Setting _dirty = true when a prop value changes ensures that a single update is triggered at patch end only if props actually changed during the batch, avoiding unnecessary updates when props remain unchanged.

---

706-709: Clean patch session initialization.

The _beginPatch() method correctly starts a patch session by enabling batching mode and resetting the dirty flag to track changes within the new batch.

---

714-719: Renderer lifecycle guarantees exception safety and no nested patches

• try/finally around patchElement always calls _endPatch() (exception safety)
• _beginPatch()/_endPatch() invoked once per patch cycle per instance (no nested calls)

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{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
language-tools	:white_check_mark: success	:white_check_mark: success
radix-vue	:white_check_mark: success	:white_check_mark: success
pinia	:white_check_mark: success	:white_check_mark: success
primevue	:white_check_mark: success	:white_check_mark: success
nuxt	:white_check_mark: success	:white_check_mark: success
quasar	:white_check_mark: success	:white_check_mark: success
router	:white_check_mark: success	:white_check_mark: success
vite-plugin-vue	:white_check_mark: success	:white_check_mark: success
vitepress	:white_check_mark: success	:white_check_mark: success
vuetify	:white_check_mark: success	:white_check_mark: success
test-utils	:white_check_mark: success	:white_check_mark: success
vue-macros	:white_check_mark: success	:white_check_mark: success
vue-i18n	:x: failure	:x: failure
vant	:white_check_mark: success	:x: failure
vueuse	:white_check_mark: success	:white_check_mark: success
vue-simple-compiler	:white_check_mark: success	:white_check_mark: success