api-reference

Renderer hooks

Vike uses special +-prefixed files to wire up the rendering pipeline. The starter kit provides two renderer hooks out of the box.

onRenderHtml

Server-side hook called during SSR and prerendering. Renders the page to an HTML string and returns the full document.

async function onRenderHtml(pageContext: PageContext): Promise<{ documentHtml: string; pageContext: Record<string, unknown> }>

Parameters

pageContextPageContextThe Vike page context object containing Page, pageProps, urlPathname, and other metadata.

Returns

Promise<{ documentHtml: string; pageContext: {} }>

Example

// renderer/+onRenderHtml.tsx
import ReactDOMServer from 'react-dom/server'
import { Layout } from './Layout'

export async function onRenderHtml(pageContext: any) {
const { Page, pageProps } = pageContext
const html = ReactDOMServer.renderToString(
  <Layout><Page {...pageProps} /></Layout>
)
return {
  documentHtml: `<!DOCTYPE html><html>...${html}...</html>`,
  pageContext: {}
}
}

onRenderClient

Client-side hook called in the browser to hydrate the server-rendered HTML. Uses React 19's hydrateRoot for seamless hydration.

async function onRenderClient(pageContext: PageContext): Promise<void>

Parameters

pageContextPageContextSame page context as onRenderHtml, hydrated from the server-rendered page.

Returns

Promise<void>

Example

// renderer/+onRenderClient.tsx
import ReactDOM from 'react-dom/client'
import { Layout } from './Layout'

export async function onRenderClient(pageContext: any) {
const { Page, pageProps } = pageContext
const root = document.getElementById('root')!
ReactDOM.hydrateRoot(
  root,
  <Layout><Page {...pageProps} /></Layout>
)
}

Page context

The pageContext object is the central data structure in Vike. It's available in both server and client hooks, and can be accessed in any component via usePageContext().

Property	Type	Available	Description
Page	React.ComponentType	server + client	The page component for the current route.
pageProps	Record<string, unknown>	server + client	Props returned by onBeforeRender, passed to the Page component.
urlPathname	string	server + client	The current URL path, e.g. "/getting-started".
urlParsed	UrlParsed	server + client	Parsed URL object with pathname, search, hash, and searchParams.
routeParams	Record<string, string>	server + client	Dynamic route parameters extracted from parameterised routes.
exports	Record<string, unknown>	server + client	Exports from the page's +data.ts or +Page.tsx file.
headers	Record<string, string>	server only	HTTP request headers. Only available in server-side hooks.
isHydration	boolean	client only	True on the first client-side render (hydration), false on subsequent navigations.

Vike plugin config

Options passed to the vike() plugin in vite.config.ts.

Option	Type	Default	Description
prerender	boolean \| PreRenderOptions	false	Enable static site generation. Set to true to prerender all pages at build time.
prerender.partial	boolean	false	Allow pages without onBeforeRender to be prerendered, even if other pages require it.
prerender.noExtraDir	boolean	false	Do not create an extra /foo/index.html directory — output /foo.html instead.
prerender.parallel	number \| boolean	true	Number of pages to prerender in parallel. true uses CPU count - 1.
prerender.disableAutoRun	boolean	false	Disable automatic prerender run at the end of vite build. Run manually instead.

usePageContext

usePageContext

React hook that returns the current Vike page context from vike-react. Available in any component rendered within the Vike rendering pipeline.

function usePageContext(): PageContext

Returns

PageContext — the full page context object for the current render

Example

import { usePageContext } from 'vike-react/usePageContext'

export function ActiveLink({ href, label }: { href: string; label: string }) {
const pageContext = usePageContext()
const isActive = pageContext.urlPathname === href

return (
  <a
    href={href}
    className={isActive ? 'text-indigo-700 font-semibold' : 'text-gray-600'}
  >
    {label}
  </a>
)
}

Important: usePageContext() requires the vike-react package and works only inside components that are rendered by Vike's rendering pipeline. It will throw if called outside a Vike render tree.