fix(vue): expose @unhead/vue/stream/iife with correct types (#707)

harlan-zw · web-flow · commit a8f1a17ba73b · 2026-03-27T17:29:09.000+11:00
The `unhead` build hook overwrites `dist/stream/iife.mjs` post-build to export
`streamingIifeCode` (string) and `streamingIifeSize` (number), but the generated
`.d.ts` still declared the source-level `init` export. This caused consumers to
need `as unknown as` casts when importing.

Now the build hook writes correct `.d.ts` files alongside the overwritten `.mjs`,
and `@unhead/vue` re-exports the subpath so Vue users can import from
`@unhead/vue/stream/iife`.
diff --git a/packages/unhead/build.config.ts b/packages/unhead/build.config.ts
@@ -38,6 +38,16 @@ export default defineBuildConfig({
         `export const streamingIifeCode = ${JSON.stringify(code)};\nexport const streamingIifeSize = ${code.length};\n`,
       )
 
+      // Write correct type declarations for the post-build exports
+      writeFileSync(
+        resolve(ctx.options.rootDir, 'dist/stream/iife.d.ts'),
+        `export declare const streamingIifeCode: string;\nexport declare const streamingIifeSize: number;\n`,
+      )
+      writeFileSync(
+        resolve(ctx.options.rootDir, 'dist/stream/iife.d.mts'),
+        `export declare const streamingIifeCode: string;\nexport declare const streamingIifeSize: number;\n`,
+      )
+
       console.log(`Built streaming IIFE: ${code.length} bytes`)
       await bundle.close()
     },
diff --git a/packages/unhead/src/stream/iife-code.d.ts b/packages/unhead/src/stream/iife-code.d.ts
@@ -0,0 +1,4 @@
+/** The bundled IIFE code as a string, for inlining in HTML */
+export declare const streamingIifeCode: string
+/** Byte length of the bundled IIFE code */
+export declare const streamingIifeSize: number
diff --git a/packages/unhead/src/stream/vite.ts b/packages/unhead/src/stream/vite.ts
@@ -38,8 +38,7 @@ export function createStreamingPlugin(options: StreamingPluginOptions): Plugin {
     async configResolved() {
       if (!iifeCodeLoaded) {
         iifeCodeLoaded = true
-        // After build, iife.mjs exports streamingIifeCode string (not the source module)
-        const mod = await import('unhead/stream/iife') as unknown as { streamingIifeCode: string }
+        const mod = await import('unhead/stream/iife')
         iifeCode = mod.streamingIifeCode
       }
     },
diff --git a/packages/vue/build.config.ts b/packages/vue/build.config.ts
@@ -15,6 +15,7 @@ export default defineBuildConfig({
     { input: 'src/scripts', name: 'scripts' },
     { input: 'src/utils', name: 'utils' },
     { input: 'src/stream/vite', name: 'stream/vite' },
+    { input: 'src/stream/iife', name: 'stream/iife' },
   ],
   hooks: {
     'rollup:options': (_, options) => {
diff --git a/packages/vue/package.json b/packages/vue/package.json
@@ -64,6 +64,10 @@
     "./stream/vite": {
       "types": "./dist/stream/vite.d.ts",
       "default": "./dist/stream/vite.mjs"
+    },
+    "./stream/iife": {
+      "types": "./dist/stream/iife.d.ts",
+      "default": "./dist/stream/iife.mjs"
     }
   },
   "main": "dist/index.mjs",
@@ -100,6 +104,9 @@
       ],
       "stream/vite": [
         "dist/stream/vite"
+      ],
+      "stream/iife": [
+        "dist/stream/iife"
       ]
     }
   },
diff --git a/packages/vue/src/stream/iife.ts b/packages/vue/src/stream/iife.ts
@@ -0,0 +1 @@
+export { streamingIifeCode, streamingIifeSize } from 'unhead/stream/iife'
diff --git a/packages/vue/test/client-hydration.test.ts b/packages/vue/test/client-hydration.test.ts
@@ -1,6 +1,6 @@
 import { JSDOM } from 'jsdom'
-import { init as initIife } from 'unhead/stream/iife'
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { init as initIife } from '../../unhead/src/stream/iife'
 import { createStreamableHead } from '../src/stream/client'
 
 let originalWindow: any
diff --git a/test/exports/vue.yaml b/test/exports/vue.yaml
@@ -37,6 +37,9 @@
   createStreamableHead: function
   HeadStream: object
   VueHeadMixin: object
+./stream/iife:
+  streamingIifeCode: string
+  streamingIifeSize: number
 ./stream/server:
   createBootstrapScript: function
   createStreamableHead: function
diff --git a/tsconfig.json b/tsconfig.json
@@ -18,7 +18,7 @@
       "unhead/stream/client": ["packages/unhead/src/stream/client"],
       "unhead/stream/server": ["packages/unhead/src/stream/server"],
       "unhead/stream/vite": ["packages/unhead/src/stream/vite"],
-      "unhead/stream/iife": ["packages/unhead/src/stream/iife"],
+      "unhead/stream/iife": ["packages/unhead/src/stream/iife-code"],
       "@unhead/ssr": ["packages/unhead/src/server/index"],
       "@unhead/dom": ["packages/unhead/src/client/index"],
       "@unhead/vue": ["packages/vue/src/index"],

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+export { streamingIifeCode, streamingIifeSize } from 'unhead/stream/iife'`