Skip to content

feat: add entry lifecycle hooks - #875

Open
harlan-zw wants to merge 2 commits into
mainfrom
feat/entry-lifecycle-hooks
Open

feat: add entry lifecycle hooks#875
harlan-zw wants to merge 2 commits into
mainfrom
feat/entry-lifecycle-hooks

Conversation

@harlan-zw

@harlan-zw harlan-zw commented Jul 23, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

🔗 Linked issue

Related to nuxt/nuxt#32100 and nuxt/nuxt#35389.

❓ Type of change

  • 📖 Documentation
  • 🐞 Bug fix
  • 👌 Enhancement
  • ✨ New feature
  • 🧹 Chore
  • ⚠️ Breaking change

📚 Description

Adds typed hooks before entry insertion and disposal so integrations can suppress entries or defer cleanup. This replaces Nuxt integration monkey patches while ensuring rejected promises still release deferred entries.

@coderabbitai

coderabbitai Bot commented Jul 23, 2026 •
edited
Loading

Copy link
Copy Markdown

Review Change Stack

📝 Walkthrough

Walkthrough

Adds entries:beforePush and entries:beforeDispose lifecycle hooks, including public types, push suppression, deferred client disposal, validation handling, documentation, and unit tests.

Changes

Entry Lifecycle Hooks

Layer / File(s) Summary
Hook contracts and composition
packages/unhead/src/types/hooks.ts, docs/head/7.api/0.get-started/overview.md		 Adds context types and exposes the new hooks through client and general head hook compositions.
Before-push veto flow
packages/unhead/src/unhead.ts, packages/unhead/src/plugins/validate.ts, docs/head/7.api/hooks/00.entries-before-push.md, packages/unhead/test/unit/entryLifecycle.test.ts		 Allows synchronous push suppression, returns an inert entry when vetoed, avoids invalid validation indexes, and tests frozen and unfrozen pushes.
Deferred client disposal
packages/unhead/src/client/adapter.ts, docs/head/7.api/hooks/01.entries-before-dispose.md, packages/unhead/test/unit/entryLifecycle.test.ts		 Collects disposal promises, finalizes entries after settlement, handles rejection cleanup, and tests multiple deferred promises.

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

Sequence Diagram(s)

Before-push flow

sequenceDiagram
  participant Caller
  participant createUnhead
  participant entriesBeforePush
  Caller->>createUnhead: push(input, options)
  createUnhead->>entriesBeforePush: callHook(input, options, shouldPush)
  entriesBeforePush-->>createUnhead: update shouldPush
  createUnhead-->>Caller: noop entry or active entry
Loading

Deferred disposal flow

sequenceDiagram
  participant ActiveHeadEntry
  participant ClientAdapter
  participant entriesBeforeDispose
  participant DeferredPromises
  ActiveHeadEntry->>ClientAdapter: dispose()
  ClientAdapter->>entriesBeforeDispose: callHook(entry, defer)
  entriesBeforeDispose-->>ClientAdapter: register PromiseLike values
  ClientAdapter->>DeferredPromises: Promise.allSettled(values)
  DeferredPromises-->>ClientAdapter: promises settle
  ClientAdapter-->>ActiveHeadEntry: finalize disposal and invalidate head
Loading
🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 25.00% 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
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Title check ✅ Passed The title is concise, conventional, and accurately summarizes the main change: adding entry lifecycle hooks.
Description check ✅ Passed The description includes linked issues, a selected change type, and a clear summary of the feature and motivation.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/entry-lifecycle-hooks

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

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

@github-actions

github-actions Bot commented Jul 23, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

📦 Bundle Size

⚠️ 12 bundles grew · net +1.5 kB gz

Bundle Gzipped Δ
Client (Minimal) 5.4 kB → 5.5 kB 🔴 +0.2 kB (+3.4%)
Client (Full) 9.5 kB → 9.7 kB 🔴 +0.2 kB (+1.8%)
Client (Self-Contained) 5.7 kB → 5.9 kB 🔴 +0.2 kB (+3.3%)
Server (Minimal) 4.9 kB → 5 kB 🔴 +52 B (+1.0%)
Server (Self-Contained) 5.2 kB → 5.3 kB 🔴 +49 B (+0.9%)
Vue Client (Minimal) 5.9 kB → 6 kB 🔴 +0.2 kB (+2.9%)
Vue Client (Full) 10.5 kB → 10.7 kB 🔴 +0.2 kB (+1.7%)
Vue Server (Minimal) 5.4 kB → 5.4 kB 🔴 +48 B (+0.9%)
React Client (Minimal) 5.8 kB → 6 kB 🔴 +0.2 kB (+3.1%)
React Client (Full) 10.6 kB → 10.8 kB 🔴 +0.2 kB (+1.6%)
React Server (Minimal) 5.2 kB → 5.2 kB 🔴 +49 B (+0.9%)
Schema.org (Minimal) 10.1 kB → 10.2 kB 🔴 +48 B (+0.5%)
All bundles (14)
Bundle Gzipped Brotli Raw
Core
Client (Minimal) 5.5 kB 5 kB 14 kB 🔴
Client (Full) 9.7 kB 8.8 kB 25.3 kB 🔴
Client (Self-Contained) 5.9 kB 5.3 kB 14.8 kB 🔴
Server (Minimal) 5 kB 4.5 kB 12.5 kB 🔴
Server (Self-Contained) 5.3 kB 4.8 kB 13.2 kB 🔴
Vue
Vue Client (Minimal) 6 kB 5.5 kB 15.1 kB 🔴
Vue Client (Full) 10.7 kB 9.7 kB 28.1 kB 🔴
Vue Server (Minimal) 5.4 kB 4.9 kB 13.5 kB 🔴
React
React Client (Minimal) 6 kB 5.5 kB 15.2 kB 🔴
React Client (Full) 10.8 kB 9.8 kB 28.5 kB 🔴
React Server (Minimal) 5.2 kB 4.7 kB 13.2 kB 🔴
Schema.org
Schema.org (Minimal) 10.2 kB 9.2 kB 28.1 kB 🔴
Schema.org Imports 0.1 kB 0.1 kB 0.1 kB ✅
Schema.org Vue Meta 0.4 kB 0.3 kB 0.8 kB ✅

📦 Runtime Dependencies

✅ No runtime dependency changes

All packages (10)
Package External deps Install size Largest dependency Skipped optional
@unhead/angular 10 773.6 kB @jridgewell/trace-mapping 146.7 kB 0
@unhead/bundler 18 5.6 MB @oxc-parser/binding-linux-arm64-gnu 2.2 MB 19
@unhead/cli 22 5.7 MB @oxc-parser/binding-linux-arm64-gnu 2.2 MB 19
@unhead/eslint-plugin 9 683.2 kB @jridgewell/trace-mapping 146.7 kB 0
@unhead/react 19 5.6 MB @oxc-parser/binding-linux-arm64-gnu 2.2 MB 19
@unhead/schema-org 9 683.2 kB @jridgewell/trace-mapping 146.7 kB 0
@unhead/solid-js 19 5.6 MB @oxc-parser/binding-linux-arm64-gnu 2.2 MB 19
@unhead/svelte 19 5.6 MB @oxc-parser/binding-linux-arm64-gnu 2.2 MB 19
@unhead/vue 19 5.6 MB @oxc-parser/binding-linux-arm64-gnu 2.2 MB 19
unhead 9 683.2 kB @jridgewell/trace-mapping 146.7 kB 0
Skipped optional dependencies (114)
  • @unhead/bundler: oxc-parser -> @oxc-parser/binding-android-arm-eabi, oxc-parser -> @oxc-parser/binding-android-arm64, oxc-parser -> @oxc-parser/binding-darwin-arm64, oxc-parser -> @oxc-parser/binding-darwin-x64, oxc-parser -> @oxc-parser/binding-freebsd-x64, oxc-parser -> @oxc-parser/binding-linux-arm-gnueabihf, oxc-parser -> @oxc-parser/binding-linux-arm-musleabihf, oxc-parser -> @oxc-parser/binding-linux-arm64-musl, oxc-parser -> @oxc-parser/binding-linux-ppc64-gnu, oxc-parser -> @oxc-parser/binding-linux-riscv64-gnu, oxc-parser -> @oxc-parser/binding-linux-riscv64-musl, oxc-parser -> @oxc-parser/binding-linux-s390x-gnu, oxc-parser -> @oxc-parser/binding-linux-x64-gnu, oxc-parser -> @oxc-parser/binding-linux-x64-musl, oxc-parser -> @oxc-parser/binding-openharmony-arm64, oxc-parser -> @oxc-parser/binding-wasm32-wasi, oxc-parser -> @oxc-parser/binding-win32-arm64-msvc, oxc-parser -> @oxc-parser/binding-win32-ia32-msvc, oxc-parser -> @oxc-parser/binding-win32-x64-msvc
  • @unhead/cli: oxc-parser -> @oxc-parser/binding-android-arm-eabi, oxc-parser -> @oxc-parser/binding-android-arm64, oxc-parser -> @oxc-parser/binding-darwin-arm64, oxc-parser -> @oxc-parser/binding-darwin-x64, oxc-parser -> @oxc-parser/binding-freebsd-x64, oxc-parser -> @oxc-parser/binding-linux-arm-gnueabihf, oxc-parser -> @oxc-parser/binding-linux-arm-musleabihf, oxc-parser -> @oxc-parser/binding-linux-arm64-musl, oxc-parser -> @oxc-parser/binding-linux-ppc64-gnu, oxc-parser -> @oxc-parser/binding-linux-riscv64-gnu, oxc-parser -> @oxc-parser/binding-linux-riscv64-musl, oxc-parser -> @oxc-parser/binding-linux-s390x-gnu, oxc-parser -> @oxc-parser/binding-linux-x64-gnu, oxc-parser -> @oxc-parser/binding-linux-x64-musl, oxc-parser -> @oxc-parser/binding-openharmony-arm64, oxc-parser -> @oxc-parser/binding-wasm32-wasi, oxc-parser -> @oxc-parser/binding-win32-arm64-msvc, oxc-parser -> @oxc-parser/binding-win32-ia32-msvc, oxc-parser -> @oxc-parser/binding-win32-x64-msvc
  • @unhead/react: oxc-parser -> @oxc-parser/binding-android-arm-eabi, oxc-parser -> @oxc-parser/binding-android-arm64, oxc-parser -> @oxc-parser/binding-darwin-arm64, oxc-parser -> @oxc-parser/binding-darwin-x64, oxc-parser -> @oxc-parser/binding-freebsd-x64, oxc-parser -> @oxc-parser/binding-linux-arm-gnueabihf, oxc-parser -> @oxc-parser/binding-linux-arm-musleabihf, oxc-parser -> @oxc-parser/binding-linux-arm64-musl, oxc-parser -> @oxc-parser/binding-linux-ppc64-gnu, oxc-parser -> @oxc-parser/binding-linux-riscv64-gnu, oxc-parser -> @oxc-parser/binding-linux-riscv64-musl, oxc-parser -> @oxc-parser/binding-linux-s390x-gnu, oxc-parser -> @oxc-parser/binding-linux-x64-gnu, oxc-parser -> @oxc-parser/binding-linux-x64-musl, oxc-parser -> @oxc-parser/binding-openharmony-arm64, oxc-parser -> @oxc-parser/binding-wasm32-wasi, oxc-parser -> @oxc-parser/binding-win32-arm64-msvc, oxc-parser -> @oxc-parser/binding-win32-ia32-msvc, oxc-parser -> @oxc-parser/binding-win32-x64-msvc
  • @unhead/solid-js: oxc-parser -> @oxc-parser/binding-android-arm-eabi, oxc-parser -> @oxc-parser/binding-android-arm64, oxc-parser -> @oxc-parser/binding-darwin-arm64, oxc-parser -> @oxc-parser/binding-darwin-x64, oxc-parser -> @oxc-parser/binding-freebsd-x64, oxc-parser -> @oxc-parser/binding-linux-arm-gnueabihf, oxc-parser -> @oxc-parser/binding-linux-arm-musleabihf, oxc-parser -> @oxc-parser/binding-linux-arm64-musl, oxc-parser -> @oxc-parser/binding-linux-ppc64-gnu, oxc-parser -> @oxc-parser/binding-linux-riscv64-gnu, oxc-parser -> @oxc-parser/binding-linux-riscv64-musl, oxc-parser -> @oxc-parser/binding-linux-s390x-gnu, oxc-parser -> @oxc-parser/binding-linux-x64-gnu, oxc-parser -> @oxc-parser/binding-linux-x64-musl, oxc-parser -> @oxc-parser/binding-openharmony-arm64, oxc-parser -> @oxc-parser/binding-wasm32-wasi, oxc-parser -> @oxc-parser/binding-win32-arm64-msvc, oxc-parser -> @oxc-parser/binding-win32-ia32-msvc, oxc-parser -> @oxc-parser/binding-win32-x64-msvc
  • @unhead/svelte: oxc-parser -> @oxc-parser/binding-android-arm-eabi, oxc-parser -> @oxc-parser/binding-android-arm64, oxc-parser -> @oxc-parser/binding-darwin-arm64, oxc-parser -> @oxc-parser/binding-darwin-x64, oxc-parser -> @oxc-parser/binding-freebsd-x64, oxc-parser -> @oxc-parser/binding-linux-arm-gnueabihf, oxc-parser -> @oxc-parser/binding-linux-arm-musleabihf, oxc-parser -> @oxc-parser/binding-linux-arm64-musl, oxc-parser -> @oxc-parser/binding-linux-ppc64-gnu, oxc-parser -> @oxc-parser/binding-linux-riscv64-gnu, oxc-parser -> @oxc-parser/binding-linux-riscv64-musl, oxc-parser -> @oxc-parser/binding-linux-s390x-gnu, oxc-parser -> @oxc-parser/binding-linux-x64-gnu, oxc-parser -> @oxc-parser/binding-linux-x64-musl, oxc-parser -> @oxc-parser/binding-openharmony-arm64, oxc-parser -> @oxc-parser/binding-wasm32-wasi, oxc-parser -> @oxc-parser/binding-win32-arm64-msvc, oxc-parser -> @oxc-parser/binding-win32-ia32-msvc, oxc-parser -> @oxc-parser/binding-win32-x64-msvc
  • @unhead/vue: oxc-parser -> @oxc-parser/binding-android-arm-eabi, oxc-parser -> @oxc-parser/binding-android-arm64, oxc-parser -> @oxc-parser/binding-darwin-arm64, oxc-parser -> @oxc-parser/binding-darwin-x64, oxc-parser -> @oxc-parser/binding-freebsd-x64, oxc-parser -> @oxc-parser/binding-linux-arm-gnueabihf, oxc-parser -> @oxc-parser/binding-linux-arm-musleabihf, oxc-parser -> @oxc-parser/binding-linux-arm64-musl, oxc-parser -> @oxc-parser/binding-linux-ppc64-gnu, oxc-parser -> @oxc-parser/binding-linux-riscv64-gnu, oxc-parser -> @oxc-parser/binding-linux-riscv64-musl, oxc-parser -> @oxc-parser/binding-linux-s390x-gnu, oxc-parser -> @oxc-parser/binding-linux-x64-gnu, oxc-parser -> @oxc-parser/binding-linux-x64-musl, oxc-parser -> @oxc-parser/binding-openharmony-arm64, oxc-parser -> @oxc-parser/binding-wasm32-wasi, oxc-parser -> @oxc-parser/binding-win32-arm64-msvc, oxc-parser -> @oxc-parser/binding-win32-ia32-msvc, oxc-parser -> @oxc-parser/binding-win32-x64-msvc

Production dependencies only. Peer dependencies and Unhead workspace packages are excluded. Skipped optional dependencies are unavailable on the CI platform.

⚡ Performance (directional)

✅ No significant change (within CI noise)

All benchmarks (14)
Benchmark PR Δ RME
SSR render (CPU) 0.359 ms ~ noise ±8.5%
SSR render (wall) 0.259 ms ~ noise ±4.7%
SSR allocated / render 238.2 KiB ~ noise ±6.8%
Schema.org cached render (CPU) 0.342 ms ~ noise ±6.6%
Schema.org cached render (wall) 0.248 ms ~ noise ±2.9%
Schema.org cached allocated / render 134.6 KiB ~ noise ±0.2%
Streaming wrapStream drain (CPU) 0.227 ms ~ noise ±4.4%
Streaming wrapStream drain (wall) 0.146 ms ~ noise ±4.3%
Streaming allocated / drain 149.9 KiB ~ noise ±0.3%
Streaming suspense chunk (CPU) 0.012 ms ~ noise ±6.7%
Streaming allocated / suspense chunk 4.7 KiB ~ noise ±0.5%
CSR DOM mutations / nav 38 ~ noise —
CSR re-render (CPU) 0.778 ms ~ noise ±5.4%
CSR re-render (wall) 0.447 ms ~ noise ±2.1%

Baseline: main @ d9b3d2a · 2026-07-26 · gzipped is the headline size metric · perf is directional (shared-runner, gated)

@harlan-zw

harlan-zw commented Jul 27, 2026

Copy link
Copy Markdown
Collaborator Author

🤖 Harlan Agent Kit automated review

This was generated and posted by a robot, not Harlan's personal review.

PASS · 95/100 confidence

  • Reviewed ea162eed against main@d9b3d2a6
  • Base current; GitHub reports no conflicts
  • PR title and body match the project template; review threads are resolved
  • Adversarial review found no remaining material code issue
  • Complete diff reviewed; required CI passed 9/9; confidence includes limited local execution

Human merge decision still required.

@harlan-zw harlan-zw added enhancement New feature or request v3 Targets Unhead v3 or the main branch labels Jul 29, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

enhancement New feature or request v3 Targets Unhead v3 or the main branch

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@harlan-zw