⚠️
The vite-plugin-ssr project has been renamed Vike.
  • If you are already using vite-plugin-ssr then migrate to Vike.
  • For new projects, don't use vite-plugin-ssr but use Vike instead.

prerender() hook

The prerender() hook is executed during pre-rendering (and only during pre-rendering) and has two purposes:

  • For providing a list of URLs for parameterized routes (e.g. /movie/1 and /movie/2 for a route /movie/@id).
  • For fetching data in bulk in order to make pre-rendering faster.

For providing URLs

Most of the time, we use the prerender() hook in order to provide the URLs of parameterized routes.

// /pages/movie.page.route.js
// Environment: Node.js

export default '/movie/@movieId'
// /pages/movie.page.server.js
// Environment: Node.js

export { prerender }

async function prerender() {
  const movies = await Movie.findAll()
  const moviePageURLs = movies.map(movie => '/movie/' + movie.id)
  return moviePageURLs
}

If we don't have any parameterized route, then we can pre-render our app without defining any prerender() hook.

The prerender() hooks are called when we run $ vite build. (The prerender() hooks are never called in development.)

For bulk data fetching

If we have a high number of pages that are to be pre-rendered, then running the command $ vite build may become slow.

We can make it significantly faster by providing the pageContext of pages in prerender() hooks.

// /pages/movie.page.route.js
// Environment: Node.js

export default '/movie/@movieId'
// /pages/movie.page.server.js
// Environment: Node.js

export { prerender }

async function prerender() {
  const movies = await Movie.findAll()

  const moviePages = (
    movies
    .map(movie => {
      const url = '/movie/' + movie.id
      const pageProps = { movie }
      const pageContext = { pageProps }
      return {
        url,
        // Because we already provide the `pageContext`, vite-plugin-ssr will *not* call
        // the `onBeforeRender()` hook for `url`.
        pageContext
      }
      /* We could also only return `url` and not provide `pageContext`. In that case
       * vite-plugin-ssr would call the `onBeforeRender()` hook. But that would be wasteful
       * since we already have all the data of all movies from our `await Movie.findAll()` call.
       * Instead, we provide `pageContext` to make the pre-rendering build step faster.
       */
      // return { url }
    })
  )

  // We can also return URLs that don't match the page's route.
  // That way we can provide the `pageContext` of other pages.
  // Here we provide the `pageContext` of the `/movies` page since
  // we already have the data.
  const movieListPage = {
    url: '/movies', // Note how the URL `/movies` isn't part of the page's route `/movie/@movieId`
    pageContext: {
      pageProps: {
        // We filter out the data we don't need in order to minimize what is sent to the browser.
        // We explain this practice at https://vite-plugin-ssr.com/data-fetching
        movieList: movies.map(({id, title}) => ({id, title})
      }
    }
  }

  return [movieListPage, ...moviePages]
}

Essentially, the prerender() hook allows us to prefetch data for multiple pages at once.

Providing pageContext in prerender() hooks should only be used for making the pre-rendering build step faster and we recommend against using prerender() hooks for other purposes.

For example, we should avoid providing additional pageContext in prerender() hooks that wouldn't otherwise exist. Instead, we should make sure that our onBeforeRender() hooks provide all the pageContext we need.

The reason being that prerender() hooks are never called in development and we should keep our app consistent between development and production.

Examples

React Example:

Vue Example: