Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 3a60751

Browse files
harlan-zwharlan-zw
authored
refactor(bundler)!: named Unhead export, ctx-based transforms, dev-mode validate (#733)
* refactor(bundler): named Unhead export, ctx-based transforms, dev-mode validate Foundational changes that landed alongside the in-progress devtools work. Splits the bundler refactor + DX improvements out from the devtools branch so they can be reviewed and merged independently. ## Bundler - BREAKING: `default` export → named `Unhead` export on `@unhead/bundler/{vite,webpack}` and on every framework wrapper (`@unhead/{react,solid-js,svelte,vue}/vite`). Existing imports must change from `import unhead from ...` to `import { Unhead } from ...`. - New `VitePluginOptions` interface (extends `UnpluginOptions`) with a `validate` flag that injects `ValidatePlugin` in dev so head-tag warnings surface in the console without manual setup. Internal `_framework` field lets framework wrappers identify themselves to the runtime. - New `CreateHeadTransform` + `createHeadTransformContext` foundation: a single transform handles `createHead()` wrapping and lets other plugins register runtime plugins via shared context. - New `SSRStaticReplace` transform: replaces `head.ssr` with a static boolean per environment so the dead branch tree-shakes cleanly. - `UseSeoMetaTransform` now preserves the second argument (e.g. `useSeoMeta(meta, { head })`) when rewriting to `useHead`. - Tests: `createHeadTransform.test.ts` and updated `useSeoMetaTransform.test.ts`. ## Framework wrappers - Vue / React / Solid / Svelte vite plugins updated for the named export and forward `_framework` so the bundler can resolve framework-scoped runtime plugins (`@unhead/vue/plugins`, etc.). - `packages-aliased/addons` deprecation shim re-exports the new named export. ## Vue - Re-exports `useServerHead`, `useServerHeadSafe`, `useServerSeoMeta` as deprecated aliases for the non-`Server` variants (v2 compat). - Re-exports `resolveUnrefHeadInput` from `utils` (v2 compat). ## Schema.org - Exports `schemaAutoImports` from the package root so consumers can wire it into `unplugin-auto-import` without reaching into subpaths. ## Docs - Reorganises `1.guides/2.advanced/{vite-plugin,client-only-tags,extending-unhead}` into a new `1.guides/build-plugins/` section: overview, tree-shaking, seo-meta-transform, minify-transform. - Migration guide moves out of `content/` to top-level `6.migration-guide/`. - Adds `7.api/plugins.md` and updates `use-head` / `use-seo-meta` API pages. ## Examples - `vite-ssr-vue-prerender`: switches to the named `Unhead` import. * chore: dedupe pnpm lockfile to fix vite peer-dep duplication Two [email protected] instances were resolved due to a peer-dep variation on the bundler package's optional `esbuild` peer, causing TS to see two incompatible Plugin types in the new bundler transforms. `pnpm update && pnpm dedupe` collapses them onto a single resolution and bumps vitest to 4.1.4. * fix(bundler): scope createHead matching and restore SSR transform Addresses CodeRabbit review feedback on #733. - SSRStaticReplace: vite.apply now returns true so the plugin actually runs during SSR builds (returning false disabled it entirely, so the head.ssr static replacement never happened) - CreateHeadTransform: scope createHead callsite matching to symbols imported from unhead/@unhead modules; supports named, aliased, and namespace imports; ignores shadowed locals and unrelated packages - Tests: cover false-positive cases (non-Unhead packages, shadowed locals) plus aliased and namespace imports - Docs: rename unhead({...}) -> Unhead({...}) in build-plugins examples, drop undocumented devtools option from overview, fix head.resolveTags() to resolveTags(head) in plugins API page - Migration guide: restore v3 content (was emptied in 66c387c) and add @unhead/addons -> @unhead/bundler rename + named Unhead export sections * docs: address coderabbit nits on v3 migration and plugins API - v3.md: add blank line before ::tip closing marker (markdownlint MD031) - plugins.md: hyphenate "hooks-based" compound adjective
1 parent 9c83934 commit 3a60751

61 files changed

Lines changed: 3183 additions & 2916 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/0.angular/schema-org/guides/get-started/0.installation.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@ useSchemaOrg([
6969

7070
## Recommended: Vite Plugin
7171

72-
If you're using Vite, the [Vite plugin](/docs/head/guides/advanced/vite-plugin) optimizes your production bundle by tree-shaking server-only code and transforming head composables at build time. See the [Vite Plugin guide](/docs/head/guides/advanced/vite-plugin) for framework-specific setup.
72+
If you're using Vite, the [Vite plugin](/docs/head/guides/build-plugins/overview) optimizes your production bundle by tree-shaking server-only code and transforming head composables at build time. See the [Build Plugins guide](/docs/head/guides/build-plugins/overview) for framework-specific setup.
7373

7474
## Optional: Auto-Imports
7575

‎docs/0.react/schema-org/guides/get-started/0.installation.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -67,14 +67,14 @@ useSchemaOrg([
6767

6868
## Recommended: Vite Plugin
6969

70-
If you're using Vite, the [Vite plugin](/docs/head/guides/advanced/vite-plugin) optimizes your production bundle by tree-shaking server-only code and transforming head composables at build time:
70+
If you're using Vite, the [Vite plugin](/docs/head/guides/build-plugins/overview) optimizes your production bundle by tree-shaking server-only code and transforming head composables at build time:
7171

7272
```ts
7373
import react from '@vitejs/plugin-react'
74-
import unhead from '@unhead/react/vite'
74+
import { Unhead } from '@unhead/react/vite'
7575

7676
export default defineConfig({
77-
plugins: [react(), unhead()],
77+
plugins: [react(), Unhead()],
7878
})
7979
```
8080

‎docs/0.solid-js/schema-org/guides/get-started/0.installation.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -117,14 +117,14 @@ See the [Schema.org Params](/docs/schema-org/guides/core-concepts/params) for al
117117

118118
## Recommended: Vite Plugin
119119

120-
If you're using Vite, the [Vite plugin](/docs/head/guides/advanced/vite-plugin) optimizes your production bundle by tree-shaking server-only code and transforming head composables at build time:
120+
If you're using Vite, the [Vite plugin](/docs/head/guides/build-plugins/overview) optimizes your production bundle by tree-shaking server-only code and transforming head composables at build time:
121121

122122
```ts [vite.config.ts]
123123
import solid from 'vite-plugin-solid'
124-
import unhead from '@unhead/solid-js/vite'
124+
import { Unhead } from '@unhead/solid-js/vite'
125125

126126
export default defineConfig({
127-
plugins: [unhead(), solid()],
127+
plugins: [Unhead(), solid()],
128128
})
129129
```
130130

‎docs/0.svelte/schema-org/guides/get-started/0.installation.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -67,14 +67,14 @@ useSchemaOrg([
6767

6868
## Recommended: Vite Plugin
6969

70-
If you're using Vite, the [Vite plugin](/docs/head/guides/advanced/vite-plugin) optimizes your production bundle by tree-shaking server-only code and transforming head composables at build time:
70+
If you're using Vite, the [Vite plugin](/docs/head/guides/build-plugins/overview) optimizes your production bundle by tree-shaking server-only code and transforming head composables at build time:
7171

7272
```ts
7373
import { svelte } from '@sveltejs/vite-plugin-svelte'
74-
import unhead from '@unhead/svelte/vite'
74+
import { Unhead } from '@unhead/svelte/vite'
7575

7676
export default defineConfig({
77-
plugins: [unhead(), svelte()],
77+
plugins: [Unhead(), svelte()],
7878
})
7979
```
8080

‎docs/0.typescript/head/guides/0.get-started/1.installation.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -160,4 +160,4 @@ Your app is now setup for head management, congrats!
160160
Try next:
161161
162162
1. Learn more about app context in the [Wrapping Composables](/docs/typescript/head/guides/core-concepts/wrapping-composables) guide
163-
2. Consider using the [Vite plugin](/docs/head/guides/advanced/vite-plugin)
163+
2. Consider using the [Vite plugin](/docs/head/guides/build-plugins/overview)

‎docs/0.typescript/schema-org/guides/get-started/0.installation.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ useSchemaOrg([
6767

6868
## Recommended: Vite Plugin
6969

70-
If you're using Vite, the [Vite plugin](/docs/head/guides/advanced/vite-plugin) optimizes your production bundle by tree-shaking server-only code and transforming head composables at build time. See the [Vite Plugin guide](/docs/head/guides/advanced/vite-plugin) for framework-specific setup.
70+
If you're using Vite, the [Vite plugin](/docs/head/guides/build-plugins/overview) optimizes your production bundle by tree-shaking server-only code and transforming head composables at build time. See the [Build Plugins guide](/docs/head/guides/build-plugins/overview) for framework-specific setup.
7171

7272
## Optional: Auto-Imports
7373

‎docs/0.vue/schema-org/guides/0.get-started/0.installation.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -71,14 +71,14 @@ useSchemaOrg([
7171

7272
## Recommended: Vite Plugin
7373

74-
If you're using Vite, the [Vite plugin](/docs/head/guides/advanced/vite-plugin) optimizes your production bundle by tree-shaking server-only code and transforming head composables at build time:
74+
If you're using Vite, the [Vite plugin](/docs/head/guides/build-plugins/overview) optimizes your production bundle by tree-shaking server-only code and transforming head composables at build time:
7575

7676
```ts
7777
import vue from '@vitejs/plugin-vue'
78-
import unhead from '@unhead/vue/vite'
78+
import { Unhead } from '@unhead/vue/vite'
7979

8080
export default defineConfig({
81-
plugins: [vue(), unhead()],
81+
plugins: [vue(), Unhead()],
8282
})
8383
```
8484

‎docs/6.migration-guide/.navigation.yml‎

Whitespace-only changes.

docs/content/6.migration-guide/1.v3.md renamed to docs/6.migration-guide/1.v3.md

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,10 +37,98 @@ ValidatePlugin({
3737
})
3838
```
3939

40+
If you're using the [unified Vite plugin](/docs/head/guides/build-plugins/overview), `ValidatePlugin` is automatically injected in dev so warnings surface in your browser console without any manual setup.
41+
4042
Remove `ValidatePlugin` once your migration is complete, or keep it for ongoing validation.
4143

4244
---
4345

46+
## `@unhead/addons` → `@unhead/bundler`
47+
48+
🚦 Impact Level: **High** (only if you import build plugins manually)
49+
50+
The `@unhead/addons` package has been renamed to `@unhead/bundler`. The old package still works as a deprecation shim that re-exports from `@unhead/bundler`, but logs a runtime warning.
51+
52+
```diff
53+
- pnpm add -D @unhead/addons
54+
+ pnpm add -D @unhead/bundler
55+
```
56+
57+
The default export has also been replaced with a named `Unhead` export:
58+
59+
```diff
60+
- import unhead from '@unhead/addons/vite'
61+
+ import { Unhead } from '@unhead/bundler/vite'
62+
63+
export default defineConfig({
64+
- plugins: [unhead()],
65+
+ plugins: [Unhead()],
66+
})
67+
```
68+
69+
::tip
70+
Most users should import from their framework's vite subpath instead, which forwards to `@unhead/bundler` and wires up framework-specific runtime plugins:
71+
72+
```ts
73+
import { Unhead } from '@unhead/vue/vite'
74+
// or @unhead/react/vite, @unhead/svelte/vite, @unhead/solid-js/vite
75+
```
76+
77+
::
78+
79+
Webpack consumers should update similarly:
80+
81+
```diff
82+
- import unhead from '@unhead/addons/webpack'
83+
+ import { Unhead } from '@unhead/bundler/webpack'
84+
```
85+
86+
The minify backend subpaths have moved too:
87+
88+
```diff
89+
- import { createJSMinifier } from '@unhead/addons/minify/rolldown'
90+
- import { createCSSMinifier } from '@unhead/addons/minify/lightningcss'
91+
+ import { createJSMinifier } from '@unhead/bundler/minify/rolldown'
92+
+ import { createCSSMinifier } from '@unhead/bundler/minify/lightningcss'
93+
```
94+
95+
See the [Build Plugins overview](/docs/head/guides/build-plugins/overview) for the new options table.
96+
97+
---
98+
99+
## Framework Vite Plugins: Named `Unhead` Export
100+
101+
🚦 Impact Level: **High**
102+
103+
Every framework Vite plugin now exports a named `Unhead` symbol instead of a default export. Update your `vite.config.ts`:
104+
105+
```diff
106+
// Vue
107+
- import unhead from '@unhead/vue/vite'
108+
+ import { Unhead } from '@unhead/vue/vite'
109+
110+
// React
111+
- import unhead from '@unhead/react/vite'
112+
+ import { Unhead } from '@unhead/react/vite'
113+
114+
// Svelte
115+
- import unhead from '@unhead/svelte/vite'
116+
+ import { Unhead } from '@unhead/svelte/vite'
117+
118+
// Solid
119+
- import unhead from '@unhead/solid-js/vite'
120+
+ import { Unhead } from '@unhead/solid-js/vite'
121+
122+
export default defineConfig({
123+
- plugins: [unhead()],
124+
+ plugins: [Unhead()],
125+
})
126+
```
127+
128+
The plugin behaviour is otherwise unchanged. Nuxt users do not need to update anything.
129+
130+
---
131+
44132
## Legacy Property Names
45133

46134
🚦 Impact Level: **High**
@@ -401,6 +489,12 @@ useHead({ link: [link] })
401489
## Quick Reference: Import Changes
402490

403491
```diff
492+
// Build plugins
493+
- import unhead from '@unhead/addons/vite'
494+
+ import { Unhead } from '@unhead/bundler/vite'
495+
// or, recommended, from your framework subpath:
496+
+ import { Unhead } from '@unhead/vue/vite'
497+
404498
// Legacy properties - update property names directly, no plugin needed
405499
- import { DeprecationsPlugin } from 'unhead/plugins'
406500

docs/content/6.migration-guide/2.v2.md renamed to docs/6.migration-guide/2.v2.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,7 @@ useHead(unheadInstance, {
7474

7575
For legacy support with Vue Meta we allowed end users to provide deprecated properties: `vmid`, `hid`, `children` and `body`.
7676

77-
You must update these properties to the appropriate replacement or remove them. See the [v3 migration guide](/docs/content/migration-guide/v3#legacy-property-names) for the replacements.
77+
You must update these properties to the appropriate replacement or remove them. See the [v3 migration guide](/docs/migration-guide/v3#legacy-property-names) for the replacements.
7878

7979
---
8080

0 commit comments

Comments
 (0)