pageContext

TypeScript we can import the type definitions of the built-in pageContext properties.

import type {PageContextBuiltIn, PageContextBuiltInClient} from 'vite-plugin-ssr/types'

Built-in

  • pageContext.Page: the export { Page } or export default of the page's .page.js file.
  • pageContext.pageExports: all exports of the page's .page.js file.
  • pageContext.routeParams: the route parameters. (E.g. pageContext.routeParams.movieId for a page with a Route String /movie/:movieId.)
  • pageContext.isHydration: [only in the browser, and only when using useClientRouter() i.e. Client Routing] boolean that is true when the page is already rendered to HTML. (When the page is already rendered to HTML we merely have to hydrate it. When doing SSR, it's true for the first page the user navigates to, and false when the user navigates to a new page.)
  • pageContext.url: The url we passed at the server middleware.
    const renderPage = createPageRenderer(/*...*/)
    // Server middleware
    app.get('*', async (req, res, next) => {
      const pageContextInit = {}
      // `pageContext.url` is defined here
      pageContextInit.url = req.url
      const result = await renderPage(pageContextInit)
      /* ... */
    })
  • pageContext.urlNormalized: same than pageContext.url but without URL Origin and Base URL. (E.g. pageContext.urlNormalized === '/product/42?details=yes#reviews' for pageContext.url === 'https://example.org/some-base-url/product/42?details=yes#reviews'.)
  • pageContext.urlPathname: the URL's pathname (after normalization). (E.g. /product/42 for pageContext.url === 'https://example.org/some-base-url/product/42?details=yes#reviews').
  • pageContext.urlParsed: { pathname, search, hash }(after normalization). (E.g. { pathname: 'product/42', search: { details: 'yes' }, hash: 'reviews' }.)

Custom

While built-in pageContext values are set by vite-plugin-ssr, we can define custom pageContext values at:

  • onBeforeRender() and render() hooks.

    // *.page.server.js
    // Environment: Node.js
    
    export function onBeforeRender() {
      return {
        pageContext: {
          // We can define some custom `pageContext` here
        }
      }
    }
    
    export function render() {
      return {
        documentHtml: escapeInject`<html>...`,
        pageContext: {
          // We can define some custom `pageContext` here
        }
      }
    }
  • Server middleware.

    const renderPage = createPageRenderer(/*...*/)
    // Server middleware
    app.get('*', async (req, res, next) => {
      const pageContextInit = {
        url: req.url,
        // We can define some custom `pageContext` here
      }
      const result = await renderPage(pageContextInit)
      /* ... */
    })

By default only pageContext.Page and pageContext.pageExports are available in the browser; we use passToClient to make more pageContext available in the browser.

The pageContext can be accessed at:

  • [Node.js] export function onBeforeRender(pageContext) (*.page.server.js)
  • [Node.js] export function render(pageContext) (*.page.server.js)
  • [Node.js (& Browser)] export default function routeFunction(pageContext) (*.page.route.js)
  • [Browser] const pageContext = await getPage() (import { getPage } from 'vite-plugin-ssr/client')
  • [Browser] useClientRouter({ render(pageContext) }) (import { useClientRouter } from 'vite-plugin-ssr/client/router')
Edit this page