Vue 2 Server Renderer

Common errors

• ReferenceError: window is not defined

  cause Attempting to access browser-specific global objects (like `window`, `document`, `navigator`) during server-side rendering.
  fix Wrap code accessing browser globals within `if (typeof window !== 'undefined')` checks or defer execution to client-side lifecycle hooks (e.g., `mounted`).

• TypeError: Cannot read property 'replace' of undefined at normalizeFile

  cause This error can occur in specific setups, often related to Webpack configurations (e.g., `SSRClientWebpackPlugin`) or when referencing `process` variables in a way that interferes with internal `vue-server-renderer` logic.
  fix Review Webpack configurations for SSR-related plugins and ensure `process.env` variables are handled correctly. Isolate and test the component causing the issue; sometimes removing an import might reveal the root cause.

• Unexpected token

  cause Invalid syntax in templates provided to the renderer, commonly using triple curly braces `{{{ }}` for string interpolation instead of double `{{ }}`.
  fix Ensure correct Vue 2 template syntax. For simple text interpolation, use `{{ variable }}`. Triple curly braces `{{{ }}}` were used for unescaped HTML in Vue 1 but are not valid for interpolation in Vue 2, which uses `v-html` for raw HTML.

• The client-side rendered virtual DOM tree is not matching server-rendered content.

  cause A hydration mismatch where the Vue application's client-side output differs from the HTML sent by the server.
  fix Carefully inspect component logic that might produce different output between server and client, especially conditional rendering, `v-if`/`v-show` conditions, and initial data states. Ensure consistent data fetching and state serialization across environments.

Warnings

• breaking Vue 2, and consequently `vue-server-renderer`, reached End of Life (EOL) on December 31st, 2023. The package is no longer maintained and will not receive any further bug fixes, security updates, or feature enhancements.
  Fix: Migrate your application to Vue 3 and use `@vue/server-renderer` for SSR. If migration is not immediately feasible, consider commercial extended support options provided by third parties.
• breaking Migration from Vue 2's `vue-server-renderer` to Vue 3's `@vue/server-renderer` involves significant API changes. For instance, `createBundleRenderer` is not available in Vue 3, and the rendering process has evolved.
  Fix: Refer to the official Vue 3 SSR documentation for `@vue/server-renderer` to understand the new API surface and recommended setup, often in conjunction with Vite.
• gotcha Attempting to use browser-specific global APIs (e.g., `window`, `document`, `localStorage`) directly in your Vue components during server-side rendering will result in `ReferenceError: window is not defined` or similar errors, as Node.js environments do not have these globals.
  Fix: Wrap browser-only code in client-side lifecycle hooks (e.g., `mounted`) or use universal utility libraries that abstract platform-specific APIs. Implement conditional checks (e.g., `if (typeof window !== 'undefined')`) where necessary.
• gotcha Hydration mismatches can occur when the client-side rendered virtual DOM tree does not precisely match the HTML structure generated by the server. This can lead to re-rendering of parts of the page, incorrect behavior, or console errors like 'Mismatching childNodes vs. VNodes'.
  Fix: Ensure that your Vue components produce identical HTML on both the server and client, especially regarding data states, conditional rendering, and element attributes. Avoid modifying DOM directly in `created` or `beforeMount` hooks.

Install

• npm install vue-server-renderer npm
• yarn add vue-server-renderer yarn
• pnpm add vue-server-renderer pnpm

Imports

• createRenderer
  wrong:

  const { createRenderer } = require('vue-server-renderer')

  correct:

  import { createRenderer } from 'vue-server-renderer'

  While CommonJS `require` was historically prevalent in Node.js for Vue 2 SSR, modern build systems and Node.js often support ESM `import`.
• createBundleRenderer
  wrong:

  const { createBundleRenderer } = require('vue-server-renderer')

  correct:

  import { createBundleRenderer } from 'vue-server-renderer'

  Used for more advanced server-side rendering with a generated server bundle. This API is deprecated in Vue 3's `@vue/server-renderer`.
• renderToString (method)

  renderer.renderToString(vm, context)

  This is a method of the object returned by `createRenderer` or `createBundleRenderer`, not a direct import. It returns a Promise in modern usage.

Quickstart

This quickstart demonstrates how to create a basic Vue 2 application and render it to a static HTML string using `vue-server-renderer` for server-side rendering.

import Vue from 'vue';
import { createRenderer } from 'vue-server-renderer';

// 1. Create a Vue 2 application instance
const app = new Vue({
  template: `
    <div id="app">
      <h1>Welcome to Vue 2 SSR!</h1>
      <p>This message: {{ serverMessage }}</p>
      <button @click="increment">Client-side interaction: {{ count }}</button>
      <p><em>(Button functionality requires client-side hydration)</em></p>
    </div>
  `,
  data() {
    return {
      serverMessage: 'Rendered on the server.',
      count: 0
    };
  },
  methods: {
    increment() {
      this.count++;
      console.log('Client-side count:', this.count); // This log only appears in browser
    }
  }
});

// 2. Create a renderer instance
const renderer = createRenderer();

// 3. Render the Vue app to an HTML string
renderer.renderToString(app)
  .then(html => {
    const fullHtml = `
<!DOCTYPE html>
<html>
<head>
  <title>Vue 2 SSR Example</title>
  <style>body { font-family: sans-serif; margin: 20px; }</style>
</head>
<body>
  ${html}
  <!-- In a real application, you would hydrate this on the client:
  <script>
    // window.__INITIAL_STATE__ = { serverMessage: '...', count: 0 };
    // new Vue({ el: '#app', data: window.__INITIAL_STATE__ });
  </script> -->
</body>
</html>
    `;
    console.log(fullHtml);
  })
  .catch(err => {
    console.error('Error during Vue 2 SSR:', err);
    process.exit(1);
  });