feat(plugin-vue): add forced vapor mode option

Add features.vapor to force Vue SFC files to compile in Vapor mode on Vue 3.6+.

Author: edison1105

packages/plugin-vue/__tests__/template-only-vapor.spec.ts

@@ -3,6 +3,7 @@ import type { SFCDescriptor } from 'vue/compiler-sfc'
 import type { ResolvedOptions } from '../src/index'
 import { resolveCompiler } from '../src/compiler'
 import { transformMain } from '../src/main'
+import { clearScriptCache, resolveScript } from '../src/script'
 import { transformTemplateAsModule } from '../src/template'
 import { createDescriptor } from '../src/utils/descriptorCache'
 
@@ -18,6 +19,15 @@ function createOptions(): ResolvedOptions {
   } as ResolvedOptions
 }
 
+function createForcedVaporOptions(): ResolvedOptions {
+  return {
+    ...createOptions(),
+    features: {
+      vapor: true,
+    },
+  }
+}
+
 function parseDescriptor(
   filename: string,
   source: string,
@@ -126,3 +136,93 @@ describe.todo('template-only vapor __multiRoot', () => {
     expect(result?.code).not.toContain('multiRoot as _sfc_multiRoot')
   })
 })
+
+// TODO: remove todo in v3.6
+describe.todo('features.vapor', () => {
+  it('forces a template-only Vue SFC to compile in vapor mode', async () => {
+    const filename = '/root/Forced.vue'
+    const source = '<template><div /><div /></template>'
+    const options = createForcedVaporOptions()
+
+    const result = await transformMain(
+      source,
+      filename,
+      options,
+      createPluginContext(),
+      false,
+      false,
+    )
+
+    expect(result?.code).toContain('const _sfc_main = { __vapor: true }')
+    expect(result?.code).toContain('_sfc_main.__multiRoot = true')
+  })
+
+  it('forces external template modules to compile in vapor mode', async () => {
+    const filename = '/root/ForcedExternal.vue'
+    const source = '<template lang="pug">div\ndiv</template>'
+    const options = createForcedVaporOptions()
+    const descriptor = parseDescriptor(filename, source, options)
+
+    const mainResult = await transformMain(
+      source,
+      filename,
+      options,
+      createPluginContext(),
+      false,
+      false,
+    )
+    const templateResult = await transformTemplateAsModule(
+      descriptor.template!.content,
+      filename,
+      descriptor,
+      options,
+      createPluginContext(),
+      false,
+      false,
+    )
+
+    expect(mainResult?.code).toContain(
+      'import { render as _sfc_render, multiRoot as _sfc_multiRoot }',
+    )
+    expect(mainResult?.code).toContain('_sfc_main.__multiRoot = _sfc_multiRoot')
+    expect(templateResult.code).toContain('export const multiRoot = true')
+  })
+
+  it('passes forced vapor mode to compileScript', () => {
+    const filename = '/root/ForcedScript.vue'
+    const options = createForcedVaporOptions()
+    const descriptor = parseDescriptor(
+      filename,
+      '<script setup>const msg = "hi"</script><template>{{ msg }}</template>',
+      options,
+    )
+    const compileScript = vi.fn(() => ({
+      ...descriptor.scriptSetup!,
+      content: 'const _sfc_main = {}',
+    }))
+
+    clearScriptCache()
+    resolveScript(
+      descriptor,
+      {
+        ...options,
+        compiler: {
+          ...compiler,
+          compileScript,
+        },
+      },
+      false,
+      false,
+    )
+
+    expect(compileScript).toHaveBeenCalledWith(
+      descriptor,
+      expect.objectContaining({
+        vapor: true,
+        templateOptions: expect.objectContaining({
+          vapor: true,
+        }),
+      }),
+    )
+  })
+})

packages/plugin-vue/src/index.ts

@@ -122,6 +122,14 @@ export interface Options {
      * - **default:** /\.ce\.vue$/
      */
     customElement?: boolean | string | RegExp | (string | RegExp)[]
+    /**
+     * Force all Vue SFC (`.vue`) files to compile in Vapor mode.
+     * When enabled, this acts as a plugin-level fallback for SFCs without the
+     * per-file `vapor` marker.
+     * - Available in Vue 3.6 and later.
+     * - **default:** `false`
+     */
+    vapor?: boolean
     /**
      * Set to `false` to disable Options API support and allow related code in
      * Vue core to be dropped via dead-code elimination in production builds,

packages/plugin-vue/src/main.ts

@@ -24,6 +24,7 @@ import { transformTemplateInMain } from './template'
 import { isEqualBlock, isOnlyTemplateChanged } from './handleHotUpdate'
 import { createRollupError } from './utils/error'
 import { EXPORT_HELPER_ID } from './helper'
+import { isVaporMode } from './utils/vapor'
 import type { ResolvedOptions } from './index'
 
 // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
@@ -67,9 +68,10 @@ export async function transformMain(
   // feature information
   const attachedProps: [string, string][] = []
   const hasScoped = descriptor.styles.some((s) => s.scoped)
-  // @ts-expect-error TODO remove when 3.6 is out
   const isTemplateOnlyVapor =
-    !descriptor.script && !descriptor.scriptSetup && descriptor.vapor
+    !descriptor.script &&
+    !descriptor.scriptSetup &&
+    isVaporMode(descriptor, options)
 
   // script
   const { code: scriptCode, map: scriptMap } = await genScriptCode(
@@ -345,9 +347,10 @@ async function genTemplateCode(
 }> {
   const template = descriptor.template!
   const hasScoped = descriptor.styles.some((style) => style.scoped)
-  // @ts-expect-error TODO remove when 3.6 is out
   const needsMultiRoot =
-    !descriptor.script && !descriptor.scriptSetup && descriptor.vapor
+    !descriptor.script &&
+    !descriptor.scriptSetup &&
+    isVaporMode(descriptor, options)
 
   // If the template is not using pre-processor AND is not using external src,
   // compile and inline it directly in the main module. When served in vite this
@@ -404,8 +407,7 @@ async function genScriptCode(
   code: string
   map: RawSourceMap | undefined
 }> {
-  // @ts-expect-error TODO remove when 3.6 is out
-  const vaporFlag = descriptor.vapor ? '__vapor: true' : ''
+  const vaporFlag = isVaporMode(descriptor, options) ? '__vapor: true' : ''
   let scriptCode = `const ${scriptIdentifier} = { ${vaporFlag} }`
   let map: RawSourceMap | undefined
 

packages/plugin-vue/src/script.ts

@@ -1,6 +1,7 @@
 import type { SFCDescriptor, SFCScriptBlock } from 'vue/compiler-sfc'
 import { resolveTemplateCompilerOptions } from './template'
 import { cache as descriptorCache } from './utils/descriptorCache'
+import { isVaporMode } from './utils/vapor'
 import type { ResolvedOptions } from './index'
 
 // ssr and non ssr builds would output different script content
@@ -85,6 +86,8 @@ export function resolveScript(
       ? scriptIdentifier
       : undefined,
     customElement,
+    // @ts-expect-error TODO remove when 3.6 is out
+    vapor: isVaporMode(descriptor, options),
     propsDestructure:
       options.features?.propsDestructure ?? options.script?.propsDestructure,
   })

packages/plugin-vue/src/template.ts

@@ -9,6 +9,7 @@ import type {
 import type { Rollup } from 'vite'
 import { getResolvedScript, resolveScript } from './script'
 import { createRollupError } from './utils/error'
+import { isVaporMode } from './utils/vapor'
 import type { ResolvedOptions } from './index'
 
 export async function transformTemplateAsModule(
@@ -193,7 +194,8 @@ export function resolveTemplateCompilerOptions(
   return {
     ...options.template,
     // @ts-expect-error TODO remove when 3.6 is out
-    vapor: descriptor.vapor,
+
+    vapor: isVaporMode(descriptor, options),
     id,
     ast: canReuseAST(options.compiler.version)
       ? descriptor.template?.ast

packages/plugin-vue/src/utils/vapor.ts

@@ -0,0 +1,22 @@
+import type { SFCDescriptor } from 'vue/compiler-sfc'
+
+interface VaporModeOptions {
+  features?: {
+    vapor?: boolean
+  }
+}
+
+/**
+ * Resolve the effective Vapor mode for a Vue SFC (`.vue`) file.
+ *
+ * `descriptor.vapor` is the per-file opt-in marker. `features.vapor` is the
+ * plugin-level force switch: when enabled, every Vue SFC handled by this plugin
+ * is compiled as Vapor mode even if the descriptor itself is not marked.
+ */
+export function isVaporMode(
+  descriptor: SFCDescriptor,
+  options: VaporModeOptions,
+): boolean {
+  // @ts-expect-error TODO remove when 3.6 is out
+  return !!(descriptor.vapor || options.features?.vapor)
+}