Prerenderer

repository·dev·Indexed 42 days ago

A framework-agnostic tool for prerendering Single Page Applications (SPAs) into static HTML files to improve SEO and performance. It provides plugins for Vite, Rollup, and Webpack 5, and supports multiple rendering engines including @prerenderer/renderer-puppeteer for high fidelity and @prerenderer/renderer-jsdom for high-volume sites.

Tokens: 12.3K
Snippets: 36
Records: 51
Agent score: 51%

What's inside Prerenderer

What is Prerendering?
dev
Prerendering is a technique to gain the benefits of Server-Side Rendering (SSR) without the complexity. It works by launching a headless browser, loading your application's routes, and saving the resulting state as static HTML files. These files can then be served by any static file server.
When to use Prerendering:
- When you want fast, static delivery of SPA routes.
- When you want to avoid the implementation overhead of full SSR.
When to avoid Prerendering:
- High route volume: If you have thousands of routes, the build process will be slow.
- Highly dynamic content: If content is user-specific, ensure you use placeholder components that load on the client-side to avoid showing incorrect static data.
https://github.com/tofandel/prerenderer/blob/dev/README.md
Install @prerenderer/rollup-plugin
dev
Install the Rollup plugin along with a renderer. You can choose between puppeteer for a full browser environment or jsdom for a lighter, simulated DOM environment.
Note: Yarn 1 is known to have issues resolving dependencies; it is recommended to use npm or an up-to-date version of yarn.
```
# For Puppeteer renderer
npm i -D @prerenderer/rollup-plugin @prerenderer/renderer-puppeteer puppeteer

# For JSDOM renderer
npm i -D @prerenderer/rollup-plugin @prerenderer/renderer-jsdom
```
https://github.com/tofandel/prerenderer/blob/dev/packages/rollup-plugin/README.md
Install @prerenderer/webpack-plugin
dev
To use the webpack plugin, you must install it along with one of the supported renderers. This plugin requires webpack 5 and HtmlWebpackPlugin to be present in your project as it hooks into the latter.
```
# For Puppeteer renderer
npm i -D @prerenderer/webpack-plugin @prerenderer/renderer-puppeteer

# OR for JSDOM renderer
npm i -D @prerenderer/webpack-plugin @prerenderer/renderer-jsdom
```
https://github.com/tofandel/prerenderer/blob/dev/packages/webpack-plugin/README.md
Install Prerenderer packages
dev
Prerenderer is a monorepo consisting of several packages. You must install the core package along with a renderer and a build system plugin (like Rollup or Webpack) to use it.
For a setup using Rollup or Vite with the Puppeteer renderer, install the following:
```
npm install --save-dev @prerenderer/rollup-plugin @prerenderer/renderer-puppeteer puppeteer
```
Important: If your package manager does not automatically install peer dependencies, you must manually install puppeteer to ensure the necessary browser binaries are available:
```
npm install --save-dev puppeteer
```
https://github.com/tofandel/prerenderer/blob/dev/README.md
Trigger custom render events in your application
dev
If you use the renderAfterDocumentEvent option in your prerenderer configuration, you must manually dispatch that event within your application code to signal that the page is ready to be prerendered. For example, in a Vue application, you might do this inside the onMounted lifecycle hook.
```
document.dispatchEvent(new Event('custom-render-trigger'))
```
https://github.com/tofandel/prerenderer/blob/dev/packages/rollup-plugin/README.md
Configure rendererOptions for Puppeteer/JSDOM
dev
The rendererOptions object allows fine-grained control over the rendering lifecycle and the browser environment. Key options include:
- maxConcurrentRoutes: Limits the number of routes rendered in parallel (defaults to 0/no limit).
- renderAfterDocumentEvent: Waits for a specific custom DOM event to be dispatched.
- renderAfterElementExists: Waits until a specific element is detected via document.querySelector.
- renderAfterTime: Waits for a specified number of milliseconds (not recommended).
- timeout: Cancels the render if it takes longer than this many milliseconds.
- inject: An object containing values to be attached to the window object.
- injectProperty: The name of the property on window where inject data is stored (defaults to '__PRERENDER_INJECTED').
- headless: (Puppeteer only) Boolean to show/hide the browser window.
```
rendererOptions: {
  maxConcurrentRoutes: 4,
  renderAfterElementExists: 'my-app-element',
  renderAfterDocumentEvent: 'custom-render-trigger',
  timeout: 20000,
  inject: {
    foo: 'bar'
  },
  headless: false
}
```
https://github.com/tofandel/prerenderer/blob/dev/packages/webpack-plugin/README.md
Configure PrerendererWebpackPlugin options
dev
The PrerendererWebpackPlugin constructor accepts an options object to control the prerendering process.
Core Options
- routes (Required): An array of strings representing the routes to prerender.
- indexPath (Optional): The location of your index.html file.
- renderer (Optional): The string name of the renderer to use (e.g., '@prerenderer/renderer-puppeteer').
- postProcess (Optional): A function to modify the rendered HTML or output path before it is written to disk. It receives a renderedRoute object.
- server (Optional): Configuration for the local server used during prerendering. Includes port (defaults to autodetected).
- rendererOptions (Optional): An object passed directly to the renderer class's constructor.
https://github.com/tofandel/prerenderer/blob/dev/packages/webpack-plugin/README.md

Configure @prerenderer/webpack-plugin or @prerenderer/rollup-plugin

dev

Both the Webpack and Rollup plugins share the same API to facilitate easy migration.

Note: The @prerenderer/webpack-plugin requires HtmlWebpackPlugin to be configured, as it hooks into it to serve your HTML.

Option	Type	Default	Description
`routes`	Array<string>	`['/']`	List of routes to prerender.
`fallback`	Boolean	false	If true, existing output HTML files are re-emitted as `{original_name}_fallback.html`.
`renderer`	string or instance	`'@prerenderer/renderer-puppeteer'`	The renderer instance or name to require.
`rendererOptions`	Object	None	Options passed to the renderer.
`postProcess`	(renderedRoute: Route) => void	None	Customize HTML and output path before writing.
`urlModifier`	(url: string) => string	None	Hook to modify the URL used to retrieve compiled assets.
`entryPath`	String	`indexPath`	The entry HTML file to use.
`...`			Inherits all Prerenderer Options.

Configure Prerenderer Server options

dev

The server option allows you to configure the internal Express server used to host your application during the prerendering process.

Option	Type	Required?	Default	Description
`port`	Integer	No	First free port after 8000	The port for the app server to run on.
`proxy`	Object	No	No proxying	Proxy configuration (matches webpack-dev-server signature).
`host`	String	No	127.0.0.1	The host to send requests to. Use with caution; changing this may result in external URLs being rendered. Use `postProcess` to change URLs in the resulting HTML instead.
`listenHost`	String	No	127.0.0.1	The IP address the server will listen to. (0.0.0.0 allows external access).
`before`	Function	No	No operation	Deprecated: Use `hookServer()` instead to add custom middleware.

Configure @prerenderer/renderer-puppeteer options

dev

The Puppeteer renderer uses a real browser. It defaults to rendering when DOMContentLoaded fires.

Option	Type	Default	Description
`maxConcurrentRoutes`	Number	0 (No limit)	Limits simultaneous renders.
`inject`	Object	None	Object to inject into the global scope.
`injectProperty`	String	`__PRERENDER_INJECTED`	Property name for `inject` on `window`.
`renderAfterDocumentEvent`	String	`DOMContentLoaded`	Wait for a specific document event.
`renderAfterTime`	Integer (ms)	None	Wait for a specific duration.
`renderAfterElementExists`	String (Selector)	None	Wait for an element to appear via `document.querySelector`.
`elementVisible`	Boolean	None	If true, waits until `renderAfterElementExists` is visible.
`elementHidden`	Boolean	None	If true, waits until `renderAfterElementExists` is hidden.
`timeout`	Integer (ms)	30000	Aborts rendering if this limit is reached.
`skipThirdPartyRequests`	Boolean	`false`	Blocks third-party requests to speed up rendering.
`headless`	Boolean	`true`	Whether to run the browser in headless mode.
`consoleHandler`	function	None	Custom handler for `console.*` calls. Receives `(route, message)`.
`viewport`	Viewport	None	Passed to `puppeteer.launch()`.
`launchOptions`	LaunchOptions	None	Passed to `puppeteer.launch()`.
`navigationOptions`	WaitForOptions	None	Passed to `page.goto()`.

Configure @prerenderer/renderer-jsdom options

dev

The JSDOM renderer is a lightweight option. By default, it renders on the DOMContentLoaded event.

Option	Type	Default	Description
`maxConcurrentRoutes`	Number	0 (No limit)	Limits simultaneous renders to manage load.
`inject`	Object	None	Object to inject into the global scope (must be JSON stringifiable).
`injectProperty`	String	`__PRERENDER_INJECTED`	The property name where `inject` is mounted on `window`.
`renderAfterDocumentEvent`	String	`DOMContentLoaded`	Wait for a specific document event (e.g., `document.dispatchEvent(new Event('custom-render-trigger'))`).
`renderAfterElementExists`	String (Selector)	None	Wait for an element to appear via `document.querySelector`.
`renderAfterTime`	Integer (ms)	None	Wait for a specific duration.
`timeout`	Integer (ms)	30000	Aborts rendering if this limit is reached while waiting.
`JSDOMOptions`	BaseOptions	`{ runScripts: 'dangerously', resources: 'usable', pretendToBeVisual: true }`	Additional options for `JSDOM.fromUrl`.

Configure Prerenderer options

dev

When initializing a Prerenderer instance, you can provide several configuration options. Note that if you are using a plugin (Webpack or Rollup), staticDir is automatically inferred from the bundler configuration.

Core Options

Option	Type	Required?	Default	Description
`staticDir`	String	Yes	None	The root path to serve your app from.
`indexPath`	String	No	`staticDir/index.html`	The index file to fall back on for SPAs.
`server`	Object	No	None	App server configuration options.
`renderer`	IRenderer Instance, constructor or String	No	`new PuppeteerRenderer()`	The renderer to use. Defaults to `@prerenderer/renderer-puppeteer`.
`rendererOptions`	Object	No	None	Options passed to the renderer if it was not provided as an instance.
`postProcess`	(renderedRoute: Route, routes: Route[]) => void	No	None	Customize HTML and output path before writing to file. You can also add routes by pushing to the `routes` parameter.

// Example conceptual configuration
const prerenderer = new Prerenderer({
  staticDir: './dist',
  renderer: 'puppeteer',
  rendererOptions: {
    headless: true
  }
});