pageContext

The pageContext object holds information about the current page.

pageContext should be treated as read-only after the rendering of the page is finished, see Lifecycle.

Built-in

Built-in properties:

  • pageContext.Page: the export { Page } or export default 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.urlOriginal: the current URL.

    On the server-side, pageContext.urlOriginal is the value you passed at the server middleware:

    // Server middleware
    app.get('*', async (req, res, next) => {
      const pageContextInit = {}
      // `pageContext.urlOriginal` is defined here
      pageContextInit.urlOriginal = req.url
      const result = await renderPage(pageContextInit)
      /* ... */
    })

    On the client-side, when using Server Routing, the pageContext.urlOriginal value is undefined (unless you use passToClient).

    On the client-side, when using Client Routing, the value of pageContext.urlOriginal is the browser's current URL (window.location.href).

  • pageContext.urlPathname: alias of pageContext.urlParsed.pathname.

  • pageContext.urlParsed: URL information:

    {
      origin: null | string
      pathname: string
      pathnameOriginal: string
      search: Record<string, string>
      searchAll: Record<string, string[]>
      searchOriginal: null | string
      hash: string
      hashOriginal: null | string
    }

    For example:

    // https://example.com/some-base-url/hello/s%C3%A9bastien?fruit=%C3%A2pple&fruit=orânge#%C3%A2ge
    {
      origin: 'https://example.com',
      pathname: '/hello/sébastien', // Without Base URL
      pathnameOriginal: '/some-base-url/hello/s%C3%A9bastien',
      search: { fruit: 'orânge' },
      searchAll: { fruit: ['âpple', 'orânge'] },
      searchOriginal: '?fruit=%C3%A2pple&fruit=orânge',
      hash: 'âge',
      hashOriginal: '#%C3%A2ge'
    }
  • pageContext.exports: See Guides > Custom Exports/Hooks.

  • pageContext.exportsAll: Same as pageContext.exports but cumulative.

  • pageContext.isHydration: Whether the current page is already rendered to HTML. When using Client Routing, the value is usually true for the first page the user navigates to, and false for any subsequent navigation. (When using Server Routing, the value is always true.)

  • pageContext.isBackwardNavigation: Whether the user is navigating back in history. The value is true when the user clicks on his browser's backward navigation button, or when invoking history.back(). The isBackwardNavigation property only works with Client Routing. (The value is always null when using Server Routing.)

  • pageContext.is404: If an error occurs, whether the error is a 404 Page Not Found or a 500 Internal Error, see API > _error.page.js.

  • pageContext.isClientSideNavigation: Whether the page was navigated by the the client-side router. In other words, when using Client Routing, the value is false for the first page the user visits, and true for any subsequent navigation. (When using Server Routing, the value is always false.)

Custom

You can define custom pageContext properties at:

  • Hooks onBeforeRender() and render().
    export function onBeforeRender() {
      return {
        pageContext: {
          // Custom `pageContext` properties
          someCustomProp: 'some-value'
        }
      }
    }
    export function render() {
      return {
        documentHtml: escapeInject`<html><!--...--></html>`,
        pageContext: {
          // Custom `pageContext` properties
          someCustomProp: 'some-value'
        }
      }
    }
  • Server middleware.
    // Server middleware
    app.get('*', async (req, res, next) => {
      const pageContextInit = {
        urlOriginal: req.url,
        // Custom `pageContext` properties
        someCustomProp: 'some-value'
      }
      const pageContext = await renderPage(pageContextInit)
      /* ... */
    })

Anywhere

Any component

The pageContext object can be accessed from within any UI component, see Guides > Access pageContext anywhere.

Client-side

While some pageContext values are also available on the client-side, most values are only available in Node.js and you have to use passToClient to make them available in the browser.

When using Server Routing, the following are also available in the browser by default:

  • pageContext.Page
  • pageContext.exports

When using Client Routing, the following are also available in the browser by default:

  • pageContext.Page
  • pageContext.exports
  • pageContext.isHydration
  • pageContext.isBackwardNavigation
  • pageContext.routeParams
  • pageContext.urlOriginal
  • pageContext.urlPathname
  • pageContext.urlParsed

TypeScript

// Server-side pageContext built-in values
import type { PageContextBuiltIn } from 'vite-plugin-ssr/types'

// Client-side pageContext built-in values, when using Server Routing
import type {
  PageContextBuiltInClientWithServerRouting as PageContextBuiltInClient
} from 'vite-plugin-ssr/types'

// Client-side pageContext built-in values, when using Client Routing
import type {
  PageContextBuiltInClientWithClientRouting as PageContextBuiltInClient
} from 'vite-plugin-ssr/types'

Lifecycle

The main purpose of pageContext is to hold information needed to render the page.

On the server-side, upon rendering a URL to HTML, a new pageContext object is created and used only for/during the creation of the HTTP response.

On the client-side, upon client-side page navigation, the pageContext object of the previous page is discarded and a new pageContext object is created.

At build-time, upon pre-rendering URLs to HTML, the pageContext object of each pre-rendered URL is generated and saved at dist/client/${URL}/index.pageContext.json.

Vite-plugin-ssr adds information to pageContext only while rendering the page, and we recommend to treat pageContext as read-only after the rendering of the page is finished. Consequently:

  • We recommend against using pageContext to store UI state. (Use a proper state management tool instead.)
  • If you use pre-rendering, then the pageContext object of each of your pre-rendered URL is set in stone already at build-time.