Registry / web-framework / vite-prerender-plugin

vite-prerender-plugin

library0.5.13jsnpmunverified

vite-prerender-plugin is a Vite plugin designed to perform server-side rendering (prerendering) of web applications to static HTML during the build process. This is particularly useful for improving initial page load performance and SEO for sites that don't require full server-side rendering on every request. The current stable version is `0.5.13`, with minor updates released somewhat regularly to address bug fixes and ensure compatibility with newer Vite versions, currently supporting Vite 5.x through 8.x. A key differentiator of this plugin is its highly flexible approach, being an extraction of the prerendering functionality from the Preact ecosystem's `@preact/preset-vite` and WMR. It delegates the actual rendering logic to the user, who must provide an exported `prerender()` function within a specified script. This function can be synchronous or asynchronous, allowing for data fetching and file system access, and is expected to return an object containing an `html` property with the rendered string. The plugin then injects this HTML into the main document at a configurable `renderTarget` selector, and can automatically discover and prerender additional routes.

web-framework devops

npm install vite-prerender-plugin

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PRERENDER-PLU

vite-prerender-plugin

web-frameworkjavascriptv0.5.13

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

vitePrerenderPlugin

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

✗ const { vitePrerenderPlugin } = require('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.

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 === */  <!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"></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}`; }); }

Debug

Known issues

gotchaThe 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}>`.

affects: >=0.5.0

gotchaThe `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')`).

affects: >=0.5.0

breakingVite 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.

affects: >=0.5.9

gotchaIn 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.

affects: 0.5.9

Errors

Common errors & fixes

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

`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

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)

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.

Upgrade

Version history

0.5.13latest on npm

Audit

Dependencies

viterequiredCore build tool that the plugin integrates with; specified as a peer dependency.

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/preactjs/vite-prerender-plugin ↗

packagehttps://www.npmjs.com/package/vite-prerender-plugin ↗