Vite Prerender Plugin

Common errors

• Cannot find module 'magic-string' (or similar Yarn dependency tree issues)

  cause `magic-string` was briefly a peer dependency in `0.5.9`, causing resolution issues, particularly with Yarn's stricter dependency handling.
  fix Upgrade `vite-prerender-plugin` to version `0.5.10` or newer. This issue was resolved by reverting `magic-string` to a regular dependency.

• Cannot read properties of undefined (reading 'filename') in stack trace

  cause An internal error handling source maps or stack traces when a filename was unexpectedly missing during the build process.
  fix This issue was addressed in version `0.5.12`. Upgrade `vite-prerender-plugin` to `0.5.12` or later to apply the fix.

• Application not prerendered / blank content (during build or in output HTML)

  cause The `prerenderScript` path is incorrect, the specified script does not export an `async function prerender(url: string): Promise<{html: string}>`, or the `renderTarget` option does not match your application's mount point.
  fix Verify that the `prerenderScript` path in `vite.config.ts` is absolute and correct. Confirm that the specified script explicitly exports the `prerender` function and that it returns an object with a non-empty `html` string. Also, ensure your `renderTarget` option matches your client-side app's root element ID/class.

Warnings

• gotcha The plugin requires a `prerender` function to be explicitly exported from a script, specified either via a `<script prerender>` attribute in your HTML or the `prerenderScript` plugin option. Failure to provide this will result in prerendering not occurring.
  Fix: Ensure your `vite.config.ts` includes the `prerenderScript` option pointing to an absolute path, or that your `index.html` contains a `<script prerender src="...">` tag, and that the specified script exports an `async function prerender(url: string): Promise<{html: string}>`.
• gotcha The `renderTarget` plugin option must precisely match the query selector where your client-side application mounts. Incorrect configuration will lead to the prerendered content not being injected correctly into your HTML.
  Fix: Verify that `renderTarget` (e.g., `'#app'`) matches the selector used in your client-side entrypoint (e.g., `document.querySelector('#app')`).
• breaking Vite peer dependency updates. Starting from `0.5.9`, the plugin explicitly requires Vite v5.x or newer, and since `0.5.13`, it supports Vite up to v8.x. Using incompatible Vite versions will result in build errors or unexpected behavior.
  Fix: Ensure your installed Vite version matches the peer dependency range specified by `vite-prerender-plugin`, currently `5.x || 6.x || 7.x || 8.x`. Upgrade or downgrade Vite as needed.
• gotcha In version `0.5.9`, `magic-string` was briefly moved to a peer dependency, which could cause Yarn-specific issues with duplicate installs or resolution problems. It was reverted to a regular dependency in `0.5.10`.
  Fix: If experiencing issues with `magic-string` and Yarn on `0.5.9`, upgrade `vite-prerender-plugin` to `0.5.10` or newer to resolve the dependency resolution problem.

Install

• npm install vite-prerender-plugin npm
• yarn add vite-prerender-plugin yarn
• pnpm add vite-prerender-plugin pnpm

Imports

• vitePrerenderPlugin
  wrong:

  const { vitePrerenderPlugin } = require('vite-prerender-plugin');

  correct:

  import { vitePrerenderPlugin } from 'vite-prerender-plugin';

  Vite plugins are typically consumed as ESM modules in `vite.config.ts` or `vite.config.js`.
• PrerenderOptions

  import type { PrerenderOptions } from 'vite-prerender-plugin';

  Import types for plugin configuration options for enhanced TypeScript support.
• PrerenderResult

  import type { PrerenderResult } from 'vite-prerender-plugin';

  Import types for the expected return value of the `prerender` function.

Quickstart

Shows how to configure `vite-prerender-plugin` in `vite.config.ts`, define a `prerender.ts` script for generating HTML, and prerender basic and dynamically added routes. Includes a minimal `index.html` and client-side `main.ts` for context.

/* === 1. Install dependencies === */
// npm install vite vite-prerender-plugin

/* === 2. vite.config.ts === */
import { defineConfig } from 'vite';
import { vitePrerenderPlugin } from 'vite-prerender-plugin';
import { resolve } from 'path';

export default defineConfig({
  plugins: [
    vitePrerenderPlugin({
      renderTarget: '#app', // Query selector for where to insert prerender result
      prerenderScript: resolve(__dirname, './prerender.ts'), // Absolute path to your prerender script
      additionalPrerenderRoutes: ['/about', '/contact', '/404'], // Routes not automatically discovered
    }),
  ],
  build: {
    // Ensure build output is suitable for static hosting
    // For this example, no special SSR options are needed beyond the plugin.
  }
});

/* === 3. prerender.ts === */
// This script runs in a Node.js-like environment during the build process.
// You would typically use your framework's renderToString method here.

interface PrerenderResult { html: string; }

export async function prerender(url: string): Promise<PrerenderResult> {
  let content = '';
  switch (url) {
    case '/':
      content = '<h1>Home Page</h1><p>Welcome to the prerendered app!</p><a href="/about">About</a>';
      break;
    case '/about':
      content = '<h1>About Us</h1><p>Learn more about our mission.</p><a href="/">Home</a>';
      break;
    case '/contact':
      content = '<h1>Contact Us</h1><p>Get in touch with us.</p>';
      break;
    case '/404':
      content = '<h1>404 - Page Not Found</h1><p>The page you requested does not exist.</p>';
      break;
    default:
      content = '<h1>Dynamic Route</h1><p>This content was prerendered for: ' + url + '</p>';
      break;
  }
  // Simulate an app mounting into a div with id 'app'
  return { html: `<div id="app">${content}</div>` };
}

/* === 4. index.html === */
<!-- In your public/index.html -->
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Vite Prerender Example</title>
</head>
<body>
    <div id="app"><!-- Prerendered content will be injected here --></div>
    <script type="module" src="/src/main.ts"></script>
</body>
</html>

/* === 5. src/main.ts (client-side entrypoint) === */
// import './style.css'; // Optional: Basic styling

const app = document.querySelector<HTMLDivElement>('#app');

// Only hydrate or render if the content is not already prerendered
if (app && !app.innerHTML) {
  app.innerHTML = `
    <h1>Client-side Hydration</h1>
    <p>This content is loaded dynamically if prerendering fails or for SPAs.</p>
    <button id="counter">count is 0</button>
  `;
  let count = 0;
  document.getElementById('counter')?.addEventListener('click', () => {
    count++;
    document.getElementById('counter')!.textContent = `count is ${count}`;
  });
}