{"id":12411,"library":"vue-bundle-renderer","title":"Vue Bundle Renderer","description":"Vue Bundle Renderer provides robust server-side rendering (SSR) capabilities for Vue 3 applications, serving as a modern and optimized alternative to the legacy `vue-server-renderer` package. It is deeply integrated into the Nuxt.js ecosystem and is designed to work efficiently with modern JavaScript bundlers like Vite and Webpack. The current stable version is 2.2.0, with a relatively active release cadence, frequently publishing enhancements and fixes, as seen in recent updates for Vite manifest compatibility. Its primary function is to take a Vue application entry and a manifest file (from Vite or Webpack) to generate an HTML string on the server, ensuring proper asset injection and hydration markers for client-side Vue applications. Key differentiators include its focus on Vue 3's composition API, robust TypeScript support, and adaptability to contemporary build tools, offering a more streamlined SSR workflow compared to its predecessor.","status":"active","version":"2.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/nuxt-contrib/vue-bundle-renderer","tags":["javascript","typescript"],"install":[{"cmd":"npm install vue-bundle-renderer","lang":"bash","label":"npm"},{"cmd":"yarn add vue-bundle-renderer","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-bundle-renderer","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as a peer dependency for creating the Vue application instance (`createApp` or `createSSRApp`) that the renderer processes.","package":"vue","optional":false}],"imports":[{"note":"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.","wrong":"import { createRenderer } from 'vue-bundle-renderer'","symbol":"createRenderer","correct":"import { createRenderer } from 'vue-bundle-renderer/runtime'"},{"note":"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.","wrong":"const { normalizeViteManifest } = require('vue-bundle-renderer')","symbol":"normalizeViteManifest","correct":"import { normalizeViteManifest } from 'vue-bundle-renderer'"},{"note":"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.","wrong":"import { normalizeWebpackManifest } from 'vue-bundle-renderer/runtime'","symbol":"normalizeWebpackManifest","correct":"import { normalizeWebpackManifest } from 'vue-bundle-renderer'"}],"quickstart":{"code":"import { createSSRApp } from 'vue';\nimport { createRenderer } from 'vue-bundle-renderer/runtime';\n\n// 1. Define your Vue 3 SSR-friendly application\nconst createVueApp = () => createSSRApp({\n  data: () => ({ message: 'Hello Vue SSR!' }),\n  template: `\n    <div>\n      <h1>{{ message }}</h1>\n      <p>This content was rendered on the server.</p>\n      <button @click=\"console.log('Hydrated click!')\">Click Me (Hydrates!)</button>\n    </div>\n  `,\n});\n\nasync function renderApplication() {\n  // 2. Initialize the renderer. In a production app, `renderOptions`\n  // would typically include a bundle and manifest generated by Vite or Webpack.\n  // For this basic example, we'll omit them to focus on core rendering.\n  const renderer = createRenderer(createVueApp, {\n    // bundle: { /* ... webpack or vite server bundle */ },\n    // manifest: { /* ... webpack or vite client manifest */ }\n  });\n\n  // 3. Define an SSR context. This object can be used by the Vue app\n  // to inject data (e.g., head tags, styles) into the HTML document.\n  const ssrContext: { head?: string; scripts?: string } = {};\n\n  // 4. Render the Vue application to an HTML string.\n  const appHtml = await renderer.renderToString(ssrContext);\n\n  // 5. Construct a complete HTML page with the rendered content.\n  const fullHtml = `\n<!DOCTYPE html>\n<html>\n<head>\n  <meta charset=\"utf-8\">\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n  <title>Vue Bundle Renderer Example</title>\n  ${ssrContext.head || ''} <!-- Injected head tags -->\n</head>\n<body>\n  <div id=\"app\">${appHtml}</div>\n  ${ssrContext.scripts || ''} <!-- Injected scripts for hydration -->\n  <script>\n    // Basic client-side hydration for this example (in a real app, bundler handles this)\n    import { createApp } from 'vue';\n    const app = createApp({\n      data: () => ({ message: 'Hello Vue SSR!' }),\n      template: document.getElementById('app').innerHTML // Or load from bundle\n    });\n    // app.mount('#app'); // This would cause re-render, use hydrate with client bundle\n  </script>\n</body>\n</html>\n`;\n\n  console.log(fullHtml);\n}\n\nrenderApplication().catch(console.error);","lang":"typescript","description":"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."},"warnings":[{"fix":"Rebuild 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.","message":"Migrating 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.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Always ensure your import statement for the renderer factory is `import { createRenderer } from 'vue-bundle-renderer/runtime'`.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"When 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.","message":"Version 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.","severity":"breaking","affected_versions":"<2.1.2"},{"fix":"To avoid potential export-related regressions or unexpected import errors, ensure you are using `vue-bundle-renderer` version 2.2.0 or newer.","message":"During 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.","severity":"gotcha","affected_versions":"2.1.x (prior to 2.2.0)"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure 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'`.","cause":"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`.","error":"Error: Cannot find module 'vue-bundle-renderer/runtime' or 'vue-bundle-renderer'"},{"fix":"Verify 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.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'legacyEntry') or similar errors related to manifest parsing."},{"fix":"Ensure 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.","cause":"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.","error":"Hydration mismatch warning or unexpected client-side rendering behavior in the browser console."}],"ecosystem":"npm"}