vite-plugin-prerender

[![npm][npm-img]][npm-url] [![downloads][downloads-img]][downloads-url] [![github][github-img]][github-url] [![license][license-img]][license-url]

_Flexible, framework-agnostic static site generation for sites and SPAs built with Vite._

It is inspired by prerender-spa-plugin

> ✅ Support any framework including Vue, React
>
> ✅ Flexible customised configuration

Install (yarn or npm)

node version: >=12.0.0

vite version: >=2.0.0

``
yarn add vite-plugin-prerender -D
`

or

`
npm i vite-plugin-prerender -D
`

Basic Usage (vite.config.js)

`ts
import vitePrerender from 'vite-plugin-prerender'
import path from 'path'

export default () => {
return {
plugins: [
vitePrerender({
// Required - The path to the vite-outputted app to prerender.
staticDir: path.join(__dirname, 'dist'),
// Required - Routes to render.
routes: ['/', '/about', '/some/deep/nested/route'],
}),
],
}
}
`

Advanced Usage (vite.config.js)

`javascript
import vitePrerender from 'vite-plugin-prerender'
import path from 'path'

const Renderer = vitePrerender.PuppeteerRenderer

export default () => {
return {
plugins: [
vitePrerender({
// Required - The path to the vite-outputted app to prerender.
staticDir: path.join(__dirname, 'dist'),

// Optional - The path your rendered app should be output to.
// (Defaults to staticDir.)
outputDir: path.join(__dirname, 'prerendered'),

// Optional - The location of index.html
indexPath: path.join(__dirname, 'dist', 'index.html'),

// Required - Routes to render.
routes: ['/', '/about', '/some/deep/nested/route'],

// Optional - Allows you to customize the HTML and output path before
// writing the rendered contents to a file.
// renderedRoute can be modified and it or an equivelant should be returned.
// renderedRoute format:
// {
// route: String, // Where the output file will end up (relative to outputDir)
// originalRoute: String, // The route that was passed into the renderer, before redirects.
// html: String, // The rendered HTML for this route.
// outputPath: String // The path the rendered HTML will be written to.
// }
postProcess(renderedRoute) {
// Ignore any redirects.
renderedRoute.route = renderedRoute.originalRoute
// Basic whitespace removal. (Don't use this in production.)
renderedRoute.html = renderedRoute.html.split(/>[\s]+<')
// Remove /index.html from the output path if the dir name ends with a .html file extension.
// For example: /dist/dir/special.html/index.html -> /dist/dir/special.html
if (renderedRoute.route.endsWith('.html')) {
renderedRoute.outputPath = path.join(
__dirname,
'dist',
renderedRoute.route,
)
}

return renderedRoute
},

// Optional - Uses html-minifier (https://github.com/kangax/html-minifier)
// To minify the resulting HTML.
// Option reference: https://github.com/kangax/html-minifier#options-quick-reference
minify: {
collapseBooleanAttributes: true,
collapseWhitespace: true,
decodeEntities: true,
keepClosingSlash: true,
sortAttributes: true,
},

// Server configuration options.
server: {
// Normally a free port is autodetected, but feel free to set this if needed.
port: 8001,
},

// The actual renderer to use. (Feel free to write your own)
// Available renderers: https://github.com/Tribex/prerenderer/tree/master/renderers
renderer: new Renderer({
// Optional - The name of the property to add to the window object with the contents of inject.
injectProperty: '__PRERENDER_INJECTED',
// Optional - Any values you'd like your app to have access to via window.injectProperty.
inject: {
foo: 'bar',
},

// Optional - defaults to 0, no limit.
// Routes are rendered asynchronously.
// Use this to limit the number of routes rendered in parallel.
maxConcurrentRoutes: 4,

// Optional - Wait to render until the specified event is dispatched on the document.
// eg, with document.dispatchEvent(new Event('custom-render-trigger'))
renderAfterDocumentEvent: 'custom-render-trigger',

// Optional - Wait to render until the specified element is detected using document.querySelector
renderAfterElementExists: 'my-app-element',

// Optional - Wait to render until a certain amount of time has passed.
// NOT RECOMMENDED
renderAfterTime: 5000, // Wait 5 seconds.

// Other puppeteer options.
// (See here: https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#puppeteerlaunchoptions)
headless: false, // Display the browser window when rendering. Useful for debugging.
}),
}),
],
}
}
`

Documentation

$3

| Option | Type | Required? | Default | Description |
| ----------- | --------------------------------------------- | --------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| staticDir | String | Yes | None | The root path to serve your app from. |
| outputDir | String | No | None | Where the prerendered pages should be output. If not set, defaults to staticDir. |
| indexPath | String | No | staticDir/index.html | The index file to fall back on for SPAs. |
| postProcess | Function(Object context): [Object \| Promise] | No | None | See the Using the postProcess Option section. |
| minify | Object | No | None | Minifies the resulting HTML using html-minifier. Full list of options available here. |
| server | Object | No | None | App server configuration options (See below) |
| renderer | Renderer Instance or Configuration Object | No | new PuppeteerRenderer() | The renderer you'd like to use to prerender the app. It's recommended that you specify this, but if not it will default to @prerenderer/renderer-puppeteer. |

#### Server Options

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

#### Using The postProcess Option

The postProcess(Object context): Object | Promise function in your renderer configuration allows you to adjust the output of prerender-spa-plugin before writing it to a file. It is called once per rendered route and is passed a context object in the form of:

`javascript
{
// The prerendered route, after following redirects.
route: String,
// The original route passed, before redirects.
originalRoute: String,
// The resulting HTML for the route.
html: String,
// The path to write the rendered HTML to.
// This is null (automatically calculated after postProcess)
// unless explicitly set.
outputPath: String || null
}
`

You can modify context.html to change what gets written to the prerendered files and/or modify context.route or context.outputPath to change the output location.

You are expected to adjust those properties as needed, then return the context object, or a promise that resolves to it like so:

`javascript
postProcess(context) {
// Remove /index.html from the output path if the dir name ends with a .html file extension.
// For example: /dist/dir/special.html/index.html -> /dist/dir/special.html
if (context.route.endsWith('.html')) {
context.outputPath = path.join(__dirname, 'dist', context.route)
}

return context
}

postProcess(context) {
return someAsyncProcessing(context.html)
.then((html) => {
context.html = html;
return context;
});
}
`

---

$3

| Option | Type | Required? | Default | Description |
| ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| maxConcurrentRoutes | Number | No | 0 (No limit) | The number of routes allowed to be rendered at the same time. Useful for breaking down massive batches of routes into smaller chunks. |
| inject | Object | No | None | An object to inject into the global scope of the rendered page before it finishes loading. Must be JSON.stringifiy-able. The property injected to is window['__PRERENDER_INJECTED'] by default. |
| injectProperty | String | No | __PRERENDER_INJECTED | The property to mount inject to during rendering. |
| renderAfterDocumentEvent | String | No | None | Wait to render until the specified event is fired on the document. (You can fire an event like so: document.dispatchEvent(new Event('custom-render-trigger')) |
| renderAfterElementExists | String (Selector) | No | None | Wait to render until the specified element is detected using document.querySelector |
| renderAfterTime | Integer (Milliseconds) | No | None | Wait to render until a certain amount of time has passed. |
| skipThirdPartyRequests | Boolean | No | false | Automatically block any third-party requests. (This can make your pages load faster by not loading non-essential scripts, styles, or fonts.) |
| consoleHandler | function(route: String, message: ConsoleMessage) | No | None | Allows you to provide a custom console.\* handler for pages. Argument one to your function is the route being rendered, argument two is the Puppeteer ConsoleMessage object. |
| [[Puppeteer Launch Options]](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#puppeteerlaunchoptions) | ? | No | None | Any additional options will be passed to puppeteer.launch(), such as headless: false. |

---

$3

| Option | Type | Required? | Default | Description |
| ------------------------ | ---------------------- | --------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| maxConcurrentRoutes | Number | No | 0 (No limit) | The number of routes allowed to be rendered at the same time. Useful for breaking down massive batches of routes into smaller chunks. |
| inject | Object | No | None | An object to inject into the global scope of the rendered page before it finishes loading. Must be JSON.stringifiy-able. The property injected to is window['__PRERENDER_INJECTED'] by default. |
| injectProperty | String | No | __PRERENDER_INJECTED | The property to mount inject to during rendering. |
| renderAfterDocumentEvent | String | No | None | Wait to render until the specified event is fired on the document. (You can fire an event like so: document.dispatchEvent(new Event('custom-render-trigger')) |
| renderAfterElementExists | String (Selector) | No | None | Wait to render until the specified element is detected using document.querySelector` |
| renderAfterTime | Integer (Milliseconds) | No | None | Wait to render until a certain amount of time has passed. |

---

License

MIT

[npm-img]: https://img.shields.io/npm/v/vite-plugin-prerender.svg
[npm-url]: https://www.npmjs.com/package/vite-plugin-prerender
[downloads-img]: https://img.shields.io/npm/dw/vite-plugin-prerender
[downloads-url]: https://www.npmjs.com/package/vite-plugin-prerender
[github-img]: https://img.shields.io/github/stars/Rudeus3Greyrat/vite-plugin-prerender
[github-url]: https://github.com/Rudeus3Greyrat/vite-plugin-prerender
[license-img]: https://img.shields.io/npm/l/vite-plugin-prerender
[license-url]: https://github.com/Rudeus3Greyrat/vite-plugin-prerender