vite-plugin-prerender

vite-plugin-prerender

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)

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)

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]+</gim).join('><')
          // 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

Plugin Options

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:

{
  // 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:

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;
    });
}

@prerenderer/renderer-puppeteer options

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]	?	No	None	Any additional options will be passed to puppeteer.launch(), such as headless: false.

@prerenderer/renderer-jsdom options

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