Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
createRenderer
✓ import { createRenderer } from 'vue-bundle-renderer/runtime'
✗ import { createRenderer } from 'vue-bundle-renderer'
The `createRenderer` function is specifically exported from the `/runtime` subpath, not the root package, to facilitate tree-shaking and clarify its runtime nature. Attempting to import from the root path will result in an undefined symbol.
normalizeViteManifest
✓ import { normalizeViteManifest } from 'vue-bundle-renderer'
✗ const { normalizeViteManifest } = require('vue-bundle-renderer')
This package is primarily developed for ESM environments and ships with TypeScript types. While CJS usage might be possible via transpilation, direct `require` statements are not the idiomatic or recommended way to import. This utility is exported directly from the root package.
normalizeWebpackManifest
✓ import { normalizeWebpackManifest } from 'vue-bundle-renderer'
✗ import { normalizeWebpackManifest } from 'vue-bundle-renderer/runtime'
This utility function for Webpack manifests is exported directly from the root package. Ensure correct named import and avoid appending `/runtime` to the import path for this specific utility.
This example demonstrates the core usage of `vue-bundle-renderer` by creating a simple Vue 3 SSR application, initializing the renderer, and rendering the application to a complete HTML string. It highlights the `createRenderer` function and the concept of an SSR context, omitting bundler-generated manifest files for brevity.
import { createSSRApp } from 'vue';
import { createRenderer } from 'vue-bundle-renderer/runtime';
// 1. Define your Vue 3 SSR-friendly application
const createVueApp = () => createSSRApp({
data: () => ({ message: 'Hello Vue SSR!' }),
template: `
<div>
<h1>{{ message }}</h1>
<p>This content was rendered on the server.</p>
<button @click="console.log('Hydrated click!')">Click Me (Hydrates!)</button>
</div>
`,
});
async function renderApplication() {
// 2. Initialize the renderer. In a production app, `renderOptions`
// would typically include a bundle and manifest generated by Vite or Webpack.
// For this basic example, we'll omit them to focus on core rendering.
const renderer = createRenderer(createVueApp, {
// bundle: { /* ... webpack or vite server bundle */ },
// manifest: { /* ... webpack or vite client manifest */ }
});
// 3. Define an SSR context. This object can be used by the Vue app
// to inject data (e.g., head tags, styles) into the HTML document.
const ssrContext: { head?: string; scripts?: string } = {};
// 4. Render the Vue application to an HTML string.
const appHtml = await renderer.renderToString(ssrContext);
// 5. Construct a complete HTML page with the rendered content.
const fullHtml = `
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Vue Bundle Renderer Example</title>
${ssrContext.head || ''} <!-- Injected head tags -->
</head>
<body>
<div id="app">${appHtml}</div>
${ssrContext.scripts || ''} <!-- Injected scripts for hydration -->
<script>
// Basic client-side hydration for this example (in a real app, bundler handles this)
import { createApp } from 'vue';
const app = createApp({
data: () => ({ message: 'Hello Vue SSR!' }),
template: document.getElementById('app').innerHTML // Or load from bundle
});
// app.mount('#app'); // This would cause re-render, use hydrate with client bundle
</script>
</body>
</html>
`;
console.log(fullHtml);
}
renderApplication().catch(console.error);
Debug
Known issues
breakingMigrating from `vue-server-renderer` (the Vue 2 era SSR package) to `vue-bundle-renderer` for Vue 3 is a significant architectural change. The API, manifest handling, and integration patterns are fundamentally different. Direct migration is not possible; expect a complete rewrite of your SSR logic.fixRebuild your SSR layer using `createRenderer` and adapt manifest generation and consumption for modern bundlers like Vite or Webpack 5. Refer to the `vue-bundle-renderer` and official Vue 3 SSR documentation for guidance on new patterns.
affects: >=1.0.0
gotchaThe `createRenderer` function must be imported from the `/runtime` subpath (`vue-bundle-renderer/runtime`). Attempting to import it directly from the root package (`vue-bundle-renderer`) will result in a runtime error indicating the symbol is undefined or cannot be found.fixAlways ensure your import statement for the renderer factory is `import { createRenderer } from 'vue-bundle-renderer/runtime'`. affects: >=1.0.0
breakingVersion 2.1.2 introduced specific support for Vite v7 manifest types, denoted by `Fixes: deps: Support vite v7 manifest type`. While this improved compatibility, it implies that older versions of `vue-bundle-renderer` (pre-2.1.2) may not correctly parse or utilize Vite v7 generated manifests, leading to rendering errors or missing assets.fixWhen using Vite v7 or newer, ensure you update `vue-bundle-renderer` to version 2.1.2 or higher to guarantee compatibility with the manifest format. Verify your Vite configuration generates a manifest suitable for the renderer version.
affects: <2.1.2
gotchaDuring the 2.1.x release cycle, there was a temporary regression (fixed in v2.2.0) where an export might have been missing or incorrectly handled (`Fixes: Add back export`). Users who installed specific patches within this range might have encountered import errors for certain symbols.fixTo avoid potential export-related regressions or unexpected import errors, ensure you are using `vue-bundle-renderer` version 2.2.0 or newer.
affects: 2.1.x (prior to 2.2.0)
Errors
Common errors & fixes
Error: Cannot find module 'vue-bundle-renderer/runtime' or 'vue-bundle-renderer'
This error typically occurs if you are trying to use `vue-bundle-renderer` in a CommonJS environment without proper transpilation, or if you are using an incorrect subpath import for `createRenderer`.
fixEnsure your Node.js project is configured for ESM imports (e.g., `"type": "module"` in `package.json` or run with a transpiler). For `createRenderer`, always use `import { createRenderer } from 'vue-bundle-renderer/runtime'`. TypeError: Cannot read properties of undefined (reading 'legacyEntry') or similar errors related to manifest parsing.
The Vite or Webpack manifest object provided to the renderer has an incompatible structure for the `vue-bundle-renderer` version being used, or the manifest file itself is corrupted/incorrectly generated.
fixVerify that your bundler (Vite or Webpack) is generating the manifest correctly. Ensure your `vue-bundle-renderer` version is compatible with your bundler's manifest format (e.g., `vue-bundle-renderer@2.1.2+` for Vite v7 manifests). Utilize `normalizeViteManifest` or `normalizeWebpackManifest` if your manifest needs pre-processing before passing it to the renderer.
Hydration mismatch warning or unexpected client-side rendering behavior in the browser console.
The HTML generated on the server by `vue-bundle-renderer` does not precisely match the HTML subsequently rendered by Vue on the client-side. Common causes include client-side only code running during SSR, direct DOM manipulation before hydration, or differences in rendering logic between environments.
fixEnsure your Vue application is fully isomorphic. Avoid client-specific code paths during SSR; use lifecycle hooks like `onMounted` for client-side only operations. Debug by comparing the server-rendered HTML output with the initial client-rendered HTML before hydration takes over.
Audit
Dependencies
vuerequiredRequired as a peer dependency for creating the Vue application instance (`createApp` or `createSSRApp`) that the renderer processes.