Prerenderer

Fast, flexible, framework-agnostic prerendering for sites and SPAs.

About prerenderer

The goal of this package is to provide a simple, framework-agnostic prerendering solution that is easily extensible and usable for any site or single-page-app.

Now, if you're not familiar with the concept of prerendering, you might predictably ask...

What is Prerendering?

Recently, SSR (Server Side Rendering) has taken the JavaScript front-end world by storm. The fact that you can now render your sites and apps on the server before sending them to your clients is an absolutely revolutionary idea (and totally not what everyone was doing before JS client-side apps got popular in the first place...)

However, the same criticisms that were valid for PHP, ASP, JSP, (and such) sites are valid for server-side rendering today. It's slow, breaks fairly easily, and is difficult to implement properly.

Thing is, despite what everyone might be telling you, you probably don't need SSR. You can get almost all the advantages of it (without the disadvantages) by using prerendering. Prerendering is basically firing up a headless browser, loading your app's routes, and saving the results to a static HTML file. You can then serve it with whatever static-file-serving solution you were using previously. It just works with HTML5 navigation and the likes. No need to change your code or add server-side rendering workarounds.

In the interest of transparency, there are some use-cases where prerendering might not be a great idea.

• Tons of routes - If your site has hundreds or thousands of routes, prerendering will be really slow. Sure you only have to do it once per update, but it could take ages. Most people don't end up with thousands of static routes, but just in-case...
• Dynamic Content - If your render routes that have content that's specific to the user viewing it or other dynamic sources, you should make sure you have placeholder components that can display until the dynamic content loads on the client-side. Otherwise, it might be a tad weird.

Example prerenderer Usage

(It's much simpler if you use prerenderer with webpack or another build system.)

Input

app/
├── index.html
└── index.js // Whatever JS controls the SPA, loaded by index.html

Output

app/
├── about
│   └── index.html // Static rendered /about route.
├── index.html // Static rendered / route.
├── index.js // Whatever JS controls the SPA, loaded by index.html
└── some
    └── deep
        └── nested
            └── route
                └── index.html // Static rendered nested route.

const fs = require('fs')
const path = require('path')
const mkdirp = require('mkdirp')
const Prerenderer = require('@prerenderer/prerenderer')
// Make sure you install a renderer as well!
const JSDOMRenderer = require('@prerenderer/renderer-jsdom')

const prerenderer = new Prerenderer({
  // Required - The path to the app to prerender. Should have an index.html and any other needed assets.
  staticDir: path.join(__dirname, 'app'),
  // The plugin that actually renders the page.
  renderer: new JSDOMRenderer(),
  postProcess (renderedRoute) {
    // Replace all http with https urls and localhost to your site url
    renderedRoute.html = renderedRoute.html.replace(
      /http:/i,
      'https:',
    ).replace(
      /(https:\/\/)?(localhost|127\.0\.0\.1):\d*/i,
      (process.env.CI_ENVIRONMENT_URL || ''),
    );
  },
})

// Initialize is separate from the constructor for flexibility of integration with build systems.
prerenderer.initialize()
  .then(() => {
    // List of routes to render.
    return prerenderer.renderRoutes(['/', '/about', '/some/deep/nested/route'])
  })
  .then(renderedRoutes => {
    // renderedRoutes is an array of objects in the format:
    // {
    //   route: String (The route rendered)
    //   html: String (The resulting HTML)
    // }
    renderedRoutes.forEach(renderedRoute => {
      try {
        // A smarter implementation would be required, but this does okay for an example.
        // Don't copy this directly!!!
        const outputDir = path.join(__dirname, 'app', renderedRoute.route)
        const outputFile = `${outputDir}/index.html`

        mkdirp.sync(outputDir)
        fs.writeFileSync(outputFile, renderedRoute.html.trim())
      } catch (e) {
        // Handle errors.
      }
    })

    // Shut down the file server and renderer.
    return prerenderer.destroy()
  })
  .catch(err => {
    // Shut down the server and renderer.
    return prerenderer.destroy()
    // Handle errors.
  })

Available Renderers

• @prerenderer/renderer-jsdom - Uses jsdom. Fast, but unreliable and cannot handle advanced usages. May not work with all front-end frameworks and apps.
• @prerenderer/renderer-puppeteer - Uses puppeteer to render pages in headless Chrome. Simpler and more reliable than the previous ChromeRenderer.

Which renderer should I use?

Use @prerenderer/renderer-puppeteer if: You're prerendering up to a couple hundred pages.

Use @prerenderer/renderer-jsdom if: You need to prerender thousands upon thousands of pages, but quality isn't all that important, and you're willing to work around issues for more advanced cases. (Programmatic SVG support, etc.)

An alternative faster dom renderer using linkedom is being considered

Documentation

All of the packages are strongly typed using typescript, if some documentation is missing or when in doubt, we recommend referring to the types which are self documenting

Installation

You need to install puppeteer manually, there is different methods of installation, in the documentation we only cover the simple package installation, which will also install the necessary browsers binary

npm install --save-dev puppeteer

Install your selected assortment of packages with your package manager

Example for Rollup or vite and the Puppeteer renderer:

npm install --save-dev @prerenderer/renderer-puppeteer @prerenderer/rollup-plugin

Then follow the installation instruction of your package of choice, that you can find in the README of that specific package

Prerenderer Options

Server Options

Prerenderer Methods

• constructor(options: Object) - Creates a Prerenderer instance and sets up the renderer and server objects.
• hookServer(cb: (server: Express) => void, stage: Stage = 'pre-fallback') - Use this method to hook into the express server to add middlewares, routes etc
• initialize(): Promise<void> - Starts the static file server and renderer instance (where appropriate).
• getOptions(): PrerenderFinalOptions - Returns the options used to configure prerenderer
• getServer(): Server - Returns the Server class holding the express server
• destroy(): Promise<void> - Destroys the static file server and renderer, freeing the resources.
• renderRoutes(routes: Array<String>): Promise<Array<RenderedRoute>> - Renders set of routes. Returns a promise resolving to an array of rendered routes in the form of:

[
  {
    originalRoute: '/route/path', // The requested route path.
    route: '/route/redirected-path', // The final route path after redirection or history change.
    html: '<!DOCTYPE html><html>...</html>' // The prerendered HTML for the route
  },
  // ...
]

@prerenderer/renderer-jsdom Options

None of the options are required, by default the page will render on DOMContentLoaded

@prerenderer/renderer-puppeteer Options

None of the options are required, by default the page will render when puppeteer is ready which is when DOMContentLoaded fires

@prerenderer/webpack-plugin Options

Implementation details

The @prerenderer/webpack-plugin requires HtmlWebpackPlugin to be configured and serve your html as this plugin is hooked into it.

None of the options are required, by default the renderer-puppeteer will be used and render only the entry file

@prerenderer/rollup-plugin Options

Implementation details

The @prerenderer/rollup-plugin and @prerenderer/webpack-plugin aims to have the same feature set and api for an easy migration

As such the options are the same as the webpack-plugin

Caveats

• For obvious reasons, prerenderer only works for SPAs that route using the HTML5 history API. index.html#/hash/route URLs will unfortunately not work.
• Whatever client-side rendering library you're using should be able to at least replace any server-rendered content or diff with it.
  • For Vue.js 1 use replace: false on root components.
  • For Vue.js 2 and 3 Ensure your root component has the same id as the prerendered element it's replacing. Otherwise you'll end up with duplicated content.

Contributing

This is a monorepo, using lerna, so you'll need to clone the repository, then run npm install inside the directory

Run npm run test to make sure that everything is working correctly

Maintainers

Adrien Foulon

Joshua Bemenderfer