onBeforePrerenderStart() hook

The onBeforePrerenderStart() 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).

    Instead of providing a list of URLs, if you want a parameterized route to be resolved dynamically on the client-side, see the workaround at #1476 - Pre-rendered dynamic routes (static host deployment).

  • For fetching data in bulk, in order to make the pre-rendering process faster.

For providing URLs

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

// /pages/movie/+route.js
// Environment: Node.js
 
export default '/movie/@movieId'
// /pages/movie/+onBeforePrerenderStart.js
// Environment: Node.js
 
export { onBeforePrerenderStart }
 
async function onBeforePrerenderStart() {
  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 onBeforePrerenderStart() hook.

The onBeforePrerenderStart() hooks are called when we run $ vite build. (The onBeforePrerenderStart() 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 onBeforePrerenderStart() hooks.

// /pages/movie/+route.js
// Environment: Node.js
 
export default '/movie/@movieId'
// /pages/movie/+onBeforePrerenderStart.js
// Environment: Node.js
 
export { onBeforePrerenderStart }
 
async function onBeforePrerenderStart() {
  const movies = await Movie.findAll()
 
  const moviePages = (
    movies
    .map(movie => {
      const url = '/movie/' + movie.id
      const pageContext = {
        data: {
          movie
        }
      }
      return {
        url,
        // Because we already provide the `pageContext`, Vike will *not* call
        // the `data()` (nor the `onBeforeRender()`) hook for `url`.
        pageContext
      }
      /* We could also only return `url` and not provide `pageContext`. In that case
       * Vike would call the `data()` (and `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 this URL '/movies' doesn't match the page's route /movie/@movieId
    pageContext: {
      data: {
        // 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://vike.dev/data-fetching
        movieList: movies.map(({id, title}) => ({id, title})
      }
    }
  }
 
  return [movieListPage, ...moviePages]
}

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

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

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

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

Examples

React Example:

Vue Example:

TypeScript

export { onBeforePrerenderStart }
 
import type { OnBeforePrerenderStartAsync } from 'vike/types'
 
const onBeforePrerenderStart: OnBeforePrerenderStartAsync = async (
): ReturnType<OnBeforePrerenderStartAsync> => {
  // ...
}

Don't omit ReturnType<OnBeforePrerenderStartAsync> (don't write const onBeforePrerenderStart: OnBeforePrerenderStartAsync = async (pageContext) => {), otherwise TypeScript won't strictly check the return type for unknown extra properties: see this TypeScript playground and issue.

See API > pageContext > Typescript for more information on how to extend pageContext with your own extra properties.

See also