Puppeteer Prerender Plugin

This is a Webpack 5 plugin for prerendering Single Page Applications (SPA) with Puppeteer. After Webpack emits all of your files, this plugin starts an Express static server in your dist directory. It then runs Puppeteer on all of your specified routes (e.g. /about) and saves the pages' rendered HTML as separate files (e.g. /dist/about/index.html).

Why?

The main benefit of prerendering your pages is for SEO benefits. Normally for an SPA, you would redirect all of your page requests to a single index.html and let your frontend framework handle routing. However, this also means that search engines will always see the same <meta> tags. By prerendering each route in your SPA, each page will be able to serve their respective <meta> tags for search engines.

Why You Shouldn't Use This

• You are building a SPA that literally has one page.

• Hydration errors are difficult to debug.

• This will greatly increase your build times if you have a lot of routes to prerender (over 100+). Consider using Server Side Rendering (SSR) instead.

Options

Option	Type	Example	Notes
routes	Array<string>	['/pricing', '/']	Required: Array of routes to render.
entryDir	string	dist	Required: Directory to start the Express static server.
entryFile	string	index.html (default)	Entry file for your SPA. Must be located in entryDir directory. This is useful if you do not want dist/index.html to be overwritten by the / route.
publicPath	string	/ (default)	Public path to serve static files from entryDir.
outputDir	string	dist (defaults to entryDir)	Output directory for prerendered routes.
enabled	boolean	false (default)	Disabled by default for performance. This option is useful if you wish to only prerender production builds e.g. process.env.NODE_ENV !== 'development'.
keepAlive	boolean	false (default)	Enable this to keep the server alive after prerendering completes. You will need to manually terminate the shell command afterwards. This is useful if you wish to inspect the actual pages that Puppeteer has seen.
maxConcurrent	number	2 (defaults to routes.length)	Maximum number of concurrent Puppeteer instances. This option is useful for keeping CPU/memory usage down when you have a lot of routes.
discoverNewRoutes	boolean	false (default)	Enable this to also prerender routes linked by a[href^=/] tags in rendered results.
renderFirstRouteAlone	boolean	false (default)	Enable this to prerender the first route before rendering the rest concurrently. This is useful if you wish to cache the first route's state globally for future routes.
injections	Array<{key: string, value: unknown}>	[{ key: 'isPrerender', value: true }]	Data to inject into each page with window[key] = value. This is useful if you wish to provide data to your app that's only present during prerender.
renderAfterEvent	string	__RENDERED__	Event name Puppeteer should wait for before saving page contents. You will need to manually dispatch the event in your app via document.dispatchEvent(new Event('__RENDERED__')).
renderAfterTime	number	5000	Time in ms for Puppeteer to wait before saving page contents.
postProcess	Function	See Example Usage	Function to post-process the saved page contents and route.
puppeteerOptions	Object	See Example Usage	Options to pass to puppeteer.launch(). See Puppeteer documentation for more information.

Important: Your / route must be defined last. Otherwise, routes rendered after / will use dist/index.html with artifacts specific to your homepage instead of a blank SPA index.html.

Example Usage (Vue 2)

webpack.config.ts

import { PuppeteerPrerenderPlugin } from 'puppeteer-prerender-plugin'
import HtmlWebpackPlugin from 'html-webpack-plugin'

export default {
    target: 'web',
    entry: 'main.ts',

    plugins: [
        new HtmlWebpackPlugin({
            template: 'index.html', // Generates dist/index.html first
        }),
        new PuppeteerPrerenderPlugin({
            enabled: process.env.NODE_ENV !== 'development',
            entryDir: 'dist',
            outputDir: 'dist',
            renderAfterEvent: '__RENDERED__',
            postProcess: (result) => {
                result.html = result.html
                    .replace(/<script (.*?)>/g, '<script $1 defer>')
                    .replace('id="app"', 'id="app" data-server-rendered="true"')
            },
            routes: [
                '/pricing', // Renders to dist/pricing/index.html
                '/about',   // Renders to dist/about/index.html
                '/',        // Renders to dist/index.html
            ],
            puppeteerOptions: {
                // Needed to run inside Docker
                headless: 'new',
                args: [
                    '--no-sandbox',
                    '--disable-setuid-sandbox',
                ],
            },
        }),
    ],
}

main.ts

import Vue from 'vue'
import App from 'App.vue'

const app = new Vue(App)
app.mount('#app')

// Tell Puppeteer the page is ready to be saved
document.dispatchEvent(new Event('__RENDERED__'))

Vue 3 Usage

Vue 3 hydration assumes the markup has been rendered with @vue/server-renderer::renderToString function instead of the output markup of a normal SPA. This is due to the fact that renderToString outputs additional comment nodes. As a result, trying to hydrate non-SSR markup will result in hydration errors.

If you wish to prerender Vue 3 apps, you will need to set your postProcess callback to empty the <div id="app"> tag. Otherwise, you will see a "white flash" due to Vue replacing the prerendered markup with its client-rendered markup.

export default {
    plugins: [
        new PuppeteerPrerenderPlugin({
            postProcess: (result) => {
                const dom = new JSDOM(result.html)
                const app = dom.window.document.querySelector('div#app')
                if (app) {
                    // Remove app HTML since Vue 3 cannot hydrate non-SSR markup
                    app.innerHTML = ''
                }

                result.html = dom.serialize()
            },
        }),
    ],
}