v3.0.0

Upgrade Rationale

prerender-spa-plugin 2.x was developed around PhantomJS and closely integrated with it to provide prerendering support. Unfortunately, PhantomJS has been falling behind in terms of support for modern web platform features, often requiring unwieldy polyfills. In the meantime, alternatives such as puppeteer have filled the void left by PhantomJS.

However, it was impossible for us to maintain full backwards-compatibility with prerender-spa-plugin 2.x while also switching out the rendering backend, so instead we took this as an opportunity to modularize the plugin and make a few much-needed changes while also replacing PhantomJS with puppeteer.

For clarification, basic usage of prerender-spa-plugin 3 is still backwards-compatible with 2.x, but deprecated. For obvious reasons, custom configuration of PhantomJS will no longer function.

Notable Changes

• The plugin initialization signature has changed from new PrerenderSPAPlugin(staticDir: String, routes: Array<String>, config: Object) to new PrerenderSPAPlugin(config: Object). For example: new PrerenderSPAPlugin({ staticDir: String, routes: String, })
• Minification support has been added using html-minifier. Anything under the minify configuration property will be passed to html-minifier.
• You can now pass any JSON-stringifiable object to a renderer’s inject property and it will be added to window['__PRERENDER_INJECTED'] when the pages are rendered. (The window destination property can be configured with injectProperty: String)
• We now support two render backends: Puppeteer and JSDOM.
• Puppeteer is the most accurate of the two, rendering in a bundled Chromium browser, but JSDOM is much faster and can render thousands of routes without a hitch by emulating a browser inside Node.js.
  Puppeteer comes bundled with the plugin under PrerenderSPAPlugin.PuppeteerRenderer. You’ll have to install the JSDOM renderer yourself using npm install @prerenderer/renderer-jsdom. and require('@prerenderer/renderer-jsdom').
• It is now possible to implement your own render backend. We don’t have any documentation on this at the moment, but you can take a look at the source for the two supported renderers.
• Renderers must now be initialized in the plugin configuration if you wish to configure them. Several of the options previously in the root configuration have moved to the renderer configuration. Example:

  new PrerenderSPAPlugin({
    staticDir: path.join(__dirname, 'dist'),
    routes: ['/', '/about', '/config'],
  
    // This allows other renderers to be implemented with a
    // subset or superset of features.
    renderer: new PrerenderSPAPlugin.PuppeteerRenderer({  
      inject: {foo: 'bar'},
      renderAfterDocumentEvent: 'render-event',
      headless: false
    })
  })
  

Breaking Changes & Deprecactions

DEPRECATION: captureAfter* configuration values have moved to the renderer configuration and renamed to renderAfter* for consistency. You can still use captureAfter* but you will recieve a deprecation warning.
DEPRECATION: Attempting to use the old style plugin initialization new PrerenderSPAPlugin(staticDir: String, routes: Array<String>, config: Object) will result in a deprecation warning.
DEPRECATION: postProcessHtml has been replaced with postProcess which allows processing HTML as well as adjusting the output routes. Using postProcessHtml should still function, but result in a deprecation warning.
BREAKING: captureAfter* / renderAfter* options can no longer be mixed, as this could sometimes result in confusing behavior or race conditions. Pick one and stick with it.
BREAKING: Renderers must be configured in their own initializers, separately from the plugin. (See the example above.)
BREAKING: PhantomJS options are no longer supported. You can, however pass launch options to the configuration for the Puppeteer renderer. The full list of options is available here.