`clientRouting`

Environment: client.

If you don't use a UI framework Vike extension vike-react/vike-vue/vike-solid then Vike does Server Routing by default.

You can opt into Client Routing by using the clientRouting setting, see Getting started.

Instead of manually integrating Client Routing yourself, you can use a UI framework Vike extension vike-react/vike-vue/vike-solid which already integrates Client Routing. And you can use Bati to scaffold an app that uses vike-react/vike-vue/vike-solid.

Examples

React example:

/boilerplates/boilerplate-react-ts/renderer/+onRenderClient.tsx

Vue example:

Getting started

Set clientRouting to true:

// /pages/+config.js
export default {
  clientRouting: true
}

Adapt your onRenderClient() hook:

// /renderer/+onRenderClient.js
// Environment: browser
 
export { onRenderClient }
 
import { renderToDom, hydrateDom } from 'some-ui-framework'
 
async function onRenderClient(pageContext) {
  // `pageContext.isHydration` is set by Vike and is `true` when the page
  // is already rendered to HTML.
  if (pageContext.isHydration) {
    // We hydrate the first page. (Since we do SSR, the first page is already
    // rendered to HTML and we merely have to hydrate it.)
    await hydrateDom(pageContext.Page)
  } else {
    // We render a new page. (When the user navigates to a new page.)
    await renderToDom(pageContext.Page)
  }
}

Note that pageContext is completely discarded and created anew upon page navigation. That's why it's called pageContext (and not appContext).

See Render Modes for another illustration of conditional DOM hydration.

Links intercepting

You can keep using <a href="/some-url"> links: the Client Router automatically intercepts clicks on <a> elements.

You can skip the Client Router for individual <a> links by adding the rel="external" attribute, e.g. <a rel="external" href="/some/url">The Client Router won't intercept me</a>.

Hooks

You can use the following hook to implement initialization after the hydration has finished:

onHydrationEnd() hook

And following hooks to implement page transition animations:

These hooks are only available if you use Client Routing.

Settings

Page settings:

prefetchStaticAssets: Link prefetching settings, see API > prefetchStaticAssets.
hydrationCanBeAborted: Whether the UI framework allows the hydration to be aborted, see hydrationCanBeAborted.

Anchor link options:

<a href="/some/url" keep-scroll-position>: Don't scroll to the top of the page, preserve the scroll position instead. See also:
- API > keepScrollPosition
- navigate('/some-url', { keepScrollPosition: true })
<a href="/some/url" rel="external">: Skip Client Routing, see Links intercepting.

You can use the function navigate('/some/url') to programmatically navigate the user to a new page.

See API > navigate().

State initialization

Usually, when using tools such as Apollo GraphQL, Redux or Vuex, you determine the initial state of your UI on the server-side while rendering HTML, and then initialize the client-side with that initial state.

Depending on the tool, you do either one of the following:

You initialize the state once.
You re-initialize the state on every page navigation.

To initialize once:

// /renderer/+onRenderHtml.js
// Environment: server
 
export { onRenderHtml }
 
import { escapeInject, dangerouslySkipEscape } from 'vike/server'
import { renderToHtml } from 'some-ui-framework'
import { getInitialState } from './getInitialState'
 
// The `onRenderHtml()` hook is called only for the first page.
// (Whereas `onBeforeRender()` is called as well upon page navigation.)
async function onRenderHtml(pageContext) {
  const initialState = await getInitialState()
 
  // We use `initialState` for rendering the HTML, so that the HTML contains
  // the content of `initialState`.
  const pageHtml = await renderToHtml(pageContext.Page, initialState)
 
  const documentHtml = escapeInject`<!DOCTYPE html>
    <html>
      <body>
        <div>${dangerouslySkipEscape(pageHtml)}</div>
      </body>
    </html>`
 
  return {
    documentHtml,
    pageContext: {
      initialState
    }
  }
}

// /renderer/+config.js
// Environment: config
 
export default {
  passToClient: ['initialState']
}

// /renderer/+onRenderClient.js
// Environment: browser
 
export { onRenderClient }
 
import { initClientSide } from './initClientSide'
 
async function onRenderClient(pageContext) {
  // The first page is rendered to HTML and `pageContext.isHydration === true`
  if (pageContext.isHydration) {
    // `pageContext.initialState` is available here
    initClientSide(pageContext.initialState)
  } else {
    // Note that `pageContext.initialState` isn't available here,
    // since our `onRenderHtml()` hook is only called for the first page.
  }
 
  // ...
}

To initialize on every page navigation:

// /renderer/+onBeforeRender.js
// Environment: server
 
export { onBeforeRender }
 
import { getInitialState } from './getInitialState'
 
// The `onBeforeRender()` hook is called for the first page as well as upon page navigation.
// (Whereas `onRenderHtml()` is called only for the first page.)
async function onBeforeRender() {
  const initialState = await getInitialState()
  return {
    pageContext: {
      initialState
    }
  }
}

// /renderer/+onRenderClient.js
// Environment: browser
 
export { onRenderClient }
 
import { initClientSide } from './initClientSide'
 
async function onRenderClient(pageContext) {
  // We initialize the state for every page rendering. So not only
  // the first page but also any subsequent page navigation.
  initClientSide(pageContext.initialState)
 
  // ...
}

clientRouting