Codestin Search App

harlan-zw · 2026-04-06T04:34:28Z

🔗 Linked issue

Resolves #711

❓ Type of change

📚 Description

Mitigates v3 breaking changes that were not previously deprecated in v2. Adds runtime migration detection to ValidatePlugin so users upgrading get actionable warnings instead of silent breakage.

ValidatePlugin migration rules (packages/unhead/src/plugins/validate.ts):

missing-template-params-plugin — warns when templateParams entries exist but TemplateParamsPlugin is not registered
missing-alias-sorting-plugin — warns when before:/after: tag priorities are used but AliasSortingPlugin is not registered
deprecated-prop-children — detects legacy children prop (should be innerHTML)
deprecated-prop-hid-vmid — detects legacy hid/vmid props (should be key)
deprecated-prop-body — detects legacy body: true prop (should be tagPosition: 'bodyClose')
deprecated-option-mode — detects removed mode option on head.push() calls

All rules follow the existing ESLint-style config pattern and can be individually set to 'off'.

DOM hook deprecations (packages/unhead/src/types/hooks.ts):

dom:renderTag — marked @deprecated (not called internally, will be removed in v4)
dom:rendered — marked @deprecated (DOM rendering is synchronous, will be removed in v4)

Vue legacy shim (packages/vue/src/legacy.ts):

Re-adds @unhead/vue/legacy export path with a console.warn deprecation notice
Re-exports from @unhead/vue/client so existing imports continue working

Migration guide (MIGRATION.md):

Comprehensive v2→v3 migration guide ordered by impact
Documents all removed/renamed APIs, composables, types, and hooks

@deprecated

- Add migration detection rules to ValidatePlugin: missing-template-params-plugin, missing-alias-sorting-plugin, deprecated-prop-children, deprecated-prop-hid-vmid, deprecated-prop-body - Mark dom:renderTag and dom:rendered hooks as @deprecated in types - Add @unhead/vue/legacy deprecation shim with re-export from client Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

coderabbitai · 2026-04-06T04:34:42Z

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds v2→v3 migration validation rules and deprecation warnings, marks two DOM hooks deprecated in types, expands unit tests for migration validations, and introduces a legacy Vue export that re-exports the client with a runtime deprecation notice.

Changes

Cohort / File(s)	Summary
Validation Migration Checks `packages/unhead/src/plugins/validate.ts`, `packages/unhead/test/unit/plugins/validate.test.ts`	Added five `ValidationRuleId`s (`deprecated-prop-body`, `deprecated-prop-children`, `deprecated-prop-hid-vmid`, `missing-alias-sorting-plugin`, `missing-template-params-plugin`); implemented `tags:afterResolve` checks to report missing v3 plugins and deprecated v2 tag props; expanded tests to cover these rules and severity disabling.
Hook Deprecations `packages/unhead/src/types/hooks.ts`	Annotated `dom:renderTag` and `dom:rendered` in `DOMHeadHooks` with `@deprecated` JSDoc (no signature changes).
Vue Legacy Export `packages/vue/build.config.ts`, `packages/vue/package.json`, `packages/vue/src/legacy.ts`, `test/exports/vue.yaml`	Added `legacy` build entry and package export subpath `./legacy`; added `src/legacy.ts` which emits a runtime deprecation warning and re-exports `./client`; updated test exports to include `./legacy` entries.
Docs `MIGRATION.md`	New migration guide documenting v3 breaking changes, prop renames, plugin replacements, API removals, and ValidatePlugin-based checks.

Sequence Diagram(s)

(omitted)

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

feat: ValidatePlugin for head tag validation #690: Extends the ValidatePlugin—directly related as this PR further adds validation rules and checks in the same plugin.
feat(validate): add performance validation rules #691: Overlapping edits to the validation plugin adding rule identifiers and runtime checks.
feat: access resolved head with onRendered #712: Related changes touching DOM render hook surface (deprecations and client rendering behavior updates).

Poem

🐰
I hopped through code with tidy paws,
Tucked old props under brand-new laws.
I nudged the plugins, rang the bell,
Left a legacy door with a gentle swell.
Thump-thump — change smells like clover.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	Title clearly describes the main change: adding v2 migration rules to ValidatePlugin and marking DOM hooks as deprecated.
Description check	✅ Passed	Description covers the linked issue, type of change (breaking change + new features), and detailed explanation of all modifications across multiple files.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch worktree-feat-v3-migration-rules

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 and usage tips.}

github-actions · 2026-04-06T04:36:43Z

Bundle Size Analysis

Bundle	Size	Gzipped
Client (Minimal)	10.6 kB	4.3 kB
Server (Minimal)	10.3 kB	4.2 kB
Vue Client (Minimal)	11.6 kB	4.8 kB
Vue Server (Minimal)	11.3 kB	4.6 kB

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/unhead/src/plugins/validate.ts`:
- Around line 578-579: The current check "'body' in tag.props" triggers the
deprecation warning even for body: false; narrow it to only match the legacy
case by changing the condition to check for strict true (e.g. tag.props.body ===
true) before calling report('deprecated-prop-body', ...). Update the condition
around the report call in the validate plugin so only tags with body set to true
emit the deprecation warning.

🪄 Autofix (Beta)

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: add0bad8-88ec-4e76-b803-53d44064a6fe

📥 Commits

Reviewing files that changed from the base of the PR and between 2bb83dd and 072385e.

📒 Files selected for processing (1)

packages/unhead/src/plugins/validate.ts

Addresses CodeRabbit review — `'body' in tag.props` triggered false positives for `body: false`. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

Recommends using ValidatePlugin during v2→v3 upgrade to detect deprecated props, missing TemplateParamsPlugin/AliasSortingPlugin, and other common migration issues. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

coderabbitai

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@MIGRATION.md`:
- Line 41: The TOC anchors for the "Schema.org Plugin" heading are incorrect
(they use "schema-org"); update the fragment(s) in the MIGRATION.md TOC to match
the markdown-generated anchor (remove the period so "Schema.org" becomes
"schemaorg"), e.g. change links referencing "schema-org" to "schemaorg" (and
similarly adjust any combined fragments like "schema-org-plugin" to
"schemaorg-plugin"), apply the same fixes for the second occurrence noted, and
re-run markdownlint (MD051) to verify the link-fragments are resolved.
- Around line 196-209: The "Vue Legacy Exports" section incorrectly says the
`/legacy` export path "has been removed" but the PR actually reintroduces it
with a deprecation shim; update this section to state that `@unhead/vue/legacy`
is reintroduced as a deprecated compatibility shim that re-exports from
`@unhead/vue/client` (see packages/vue/src/legacy.ts) and emits a runtime
`console.warn` deprecation notice, or alternatively remove the section if the
intent is to stop supporting it—ensure the text references the re-export and
deprecation behavior so it matches the code change.

🪄 Autofix (Beta)

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: ad41fdf7-d082-4c03-a62f-6b6125c87239

📥 Commits

Reviewing files that changed from the base of the PR and between de8e14c and 2ebc692.

📒 Files selected for processing (1)

MIGRATION.md

@deprecated

- Detect `mode` option on head.push() (silently ignored in v3) - Fix MIGRATION.md: /legacy is deprecated not removed - Fix Schema.org anchor links in TOC - Fix dom:rendered @deprecated JSDoc wording

harlan-zw and others added 2 commits April 6, 2026 14:37

fix: add explicit type annotation for strict TypeScript check

072385e

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

fix: update export snapshot for @unhead/vue/legacy

9549a20

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

coderabbitai Bot reviewed Apr 6, 2026

View reviewed changes

Comment thread packages/unhead/src/plugins/validate.ts Outdated

fix: narrow body deprecation check to body: true only

de8e14c

Addresses CodeRabbit review — `'body' in tag.props` triggered false positives for `body: false`. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

harlan-zw mentioned this pull request Apr 6, 2026

v3 Release #711

Closed

coderabbitai Bot reviewed Apr 6, 2026

View reviewed changes

Comment thread MIGRATION.md Outdated

Comment thread MIGRATION.md Outdated

harlan-zw added 2 commits April 7, 2026 13:45

fix: add deprecated-option-mode rule, fix MIGRATION.md accuracy

dc6aa7e

- Detect `mode` option on head.push() (silently ignored in v3) - Fix MIGRATION.md: /legacy is deprecated not removed - Fix Schema.org anchor links in TOC - Fix dom:rendered @deprecated JSDoc wording

chore: sync

342c962

harlan-zw merged commit f5edf07 into main Apr 7, 2026
6 checks passed

This was referenced Apr 7, 2026

feat(validate): add 7 performance/web vitals validation rules #725

Merged

feat(devtools): vite devtools integration #731

Merged

fix(legacy): restore exports for v2 migration #741

Merged

coderabbitai Bot mentioned this pull request Apr 25, 2026

feat(cli,eslint-plugin): add @unhead/cli and @unhead/eslint-plugin #755

Merged

6 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

feat: v2 migration rules in ValidatePlugin + DOM hook deprecations#722

feat: v2 migration rules in ValidatePlugin + DOM hook deprecations#722
harlan-zw merged 7 commits into
mainfrom
worktree-feat-v3-migration-rules

harlan-zw commented Apr 6, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Apr 6, 2026 •

edited

Loading

Reviews paused

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Possibly related PRs

Poem

❌ Failed checks (1 warning)

Uh oh!

github-actions Bot commented Apr 6, 2026

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Uh oh!

Conversation

harlan-zw commented Apr 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔗 Linked issue

❓ Type of change

📚 Description

Uh oh!

coderabbitai Bot commented Apr 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviews paused

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Possibly related PRs

Poem

❌ Failed checks (1 warning)

Uh oh!

github-actions Bot commented Apr 6, 2026

Bundle Size Analysis

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

harlan-zw commented Apr 6, 2026 •

edited

Loading

coderabbitai Bot commented Apr 6, 2026 •

edited

Loading