Export runtime-vapor to support unit-test for Vapor Mode

[zhiyuanzmj]

Vue version

3.6.0-beta.5

Link to minimal reproduction

https://github.com/zhiyuanzmj/router

Steps to reproduce

1 . git clone https://github.com/zhiyuanzmj/router -b vapor-issue
2. pnpm install && pnpm test

What is expected?

Export runtime-vapor from vue's cjs-bundler.

What is actually happening?

Will report a defineVaporComponent is not a function error

System Info

System:
    OS: macOS 26.2
    CPU: (10) arm64 Apple M1 Pro
    Memory: 129.38 MB / 16.00 GB
    Shell: 5.9 - /bin/zsh
  Binaries:
    Node: 23.8.0 - /usr/local/bin/node
    Yarn: 1.22.22 - /usr/local/bin/yarn
    npm: 10.9.2 - /usr/local/bin/npm
    pnpm: 10.28.2 - ~/Library/pnpm/pnpm
    bun: 1.3.6 - ~/.bun/bin/bun
  Browsers:
    Chrome: 144.0.7559.133
    Safari: 26.2

Any additional comments?

A temporary solution

// vitest.config.ts
export default defineConfig({
  // FIXME: shouldn't be needed
  resolve: {
    alias: {
      // cjs does not export vapor runtime, use esm instead.
      "@vue/runtime-core": require.resolve('@vue/runtime-core').replace('index.js', 'dist/runtime-core.esm-bundler.js'),
       "@vue/runtime-dom": require.resolve('@vue/runtime-dom').replace('index.js', 'dist/runtime-dom.esm-bundler.js'),
      vue: 'vue/dist/vue.runtime.esm-bundler.js',
    },
  },
})

Since runtime-vapor doesn't export from cjs-bundler. We must use vitest to alias vue as esm-bundler.

[beanscg]

Bean Labs took a source/docs pass. The useful public surfaces for this look like packages/runtime-vapor, package exports, test utilities.

The highest-signal next step would be to clarify whether runtime-vapor should be public package surface or test-only helper, then add export tests for the chosen path. That keeps the issue scoped to observable source/docs behavior before opening a PR.

No PR opened from this pass.

[zhiyuanzmj]

I create a test PR for vue-router's vapor tests.
#14418

[mymx2]

Same root cause also hits vitest browser mode (playwright provider): even with tests running in real Chromium, the SSR pipeline resolves vue through the node condition to the CJS entry, so vapor-compiled components lose template/child/next. Aliasing to vue.runtime.esm-bundler.js + dedupe works there too, but having runtime-vapor in the cjs build would let us drop the alias.

[silverwind]

The root cause is vitest resolves like node and ends up getting the CJS build.

The ideal solution should be to remove the CJS build and migrate to pure ESM so that node and browser resolve to the same, meaning you test the same version of vue that is running in browsers.

[edison1105]

@vue/runtime-vapor intentionally only ships an ESM bundler build and only supports browser environments. Vitest's default jsdom/happy-dom runner executes dependencies through Node resolution, which selects Vue's Node/CJS entry and therefore does not expose Vapor runtime APIs.
Vapor component tests should use Vitest Browser Mode, where modules are served through Vite and executed as native ESM in a real browser. We do not plan to add Vapor exports to Vue's CJS/Node builds. See the Vitest Browser Mode guide.