Render Modes (SPA, SSR, SSG, HTML-only)
🧠This page documents how to implement render modes yourself. It's an advanced task and we generally recommend simply using the
ssr
andprerender
settings instead.⚠️ We recommend using such advanced Vike functionality, which can be complex to use, only if you have a clear reason why you don't want to use potentially easier alternatives.
For each page, you can choose a different render mode:
- SPA
- SSR
- HTML-only
- Pre-rendering (SSG)
For example, you can render an admin panel as SPA while rendering marketing pages with SSR.
What "SPA", "SSR", "HTML-only" and "SSG" mean, and which one should be used, is explained at SPA vs SSR (and more).
The Vike boilerplates do SSR by default, which is a sensible default that works for most apps.
Instead of manually integrating Render Modes yourself, you can use a UI framework Vike extension
vike-react
/vike-vue
/vike-solid
which already integrates Render Modes. And you can use Bati to scaffold an app that usesvike-react
/vike-vue
/vike-solid
.
SPA
Rendering a page as SPA means that the page is loaded and rendered only in the browser.
To achieve that:
- We set
Page
's meta configenv
to{ server: false, client: true }
instead of{ server: true, client: true }
. - We adapt our
onRenderHtml()
andonRenderClient()
hooks.
1. Page
meta config
By setting Page
's meta config env
to { client: true, server: false }
we tell Vike to load +Page.js
only in the browser.
React example (SPA + SSR):
- Custom
renderMode
config: /examples/render-modes/renderer/+config.ts - SPA page: /examples/render-modes/pages/spa/+Page.jsx
- SPA page's
renderMode
config value: /examples/render-modes/pages/spa/+renderMode.js - SSR page: /examples/render-modes/pages/ssr/+Page.jsx
- SSR page's
renderMode
config value: /examples/render-modes/pages/ssr/+renderMode.js
Vue example: GitHub > AaronBeaudoin/vite-plugin-ssr-example
> /pages/spa.page.client.vue
vite-plugin-ssr was the previous name of Vike. Contributions welcome to fork and update the Vue example.
2. Render hooks (SPA only)
If we only have SPA pages, then we adapt our onRenderHtml()
and onRenderClient()
hooks like the following.
Client-side onRenderClient()
hook:
See What is Hydration? for understanding the difference between "rendering to the DOM" and "hydrating the DOM".
We also adapt our server-side onRenderHtml()
hook:
This is the key difference between SPA and SSR: in SPA div#root
is empty, whereas with SSR div#root
contains our Page's root component pageContext.Page
rendered to HTML.
This means that, with SPA, we use our server-side onRenderHtml()
hook to generate HTML that is just an empty shell:
the HTML doesn't contain the page's content.
For production, we usually want to pre-render the HTML of our SPA pages in order to remove the need for a production Node.js server.
We can also use our server-side onRenderHtml()
hook to render <head>
:
pageContext.config.title
andpageContext.config.description
are custom settings, see API >meta
> Example:title
anddescription
.
2. Render hooks (SPA + SSR)
If we have both SPA and SSR pages, then we adapt our onRenderHtml()
and onRenderClient()
hooks like this:
If we set the
Page
meta configenv
to{ server: false, client: true }
instead of{ server: true, client: true }
inconfig.js
, thenpageContext.Page
is only defined in the browser.
React example: /examples/render-modes/.
- Server-side hook: /examples/render-modes/renderer/+onRenderHtml.jsx
- Client-side hook: /examples/render-modes/renderer/+onRenderClient.jsx
- Custom
renderMode
config: /examples/render-modes/renderer/+config.ts - SPA page: /examples/render-modes/pages/spa/+Page.jsx
- SPA page's
renderMode
config value: /examples/render-modes/pages/spa/+renderMode.js - SSR page: /examples/render-modes/pages/ssr/+Page.jsx
- SSR page's
renderMode
config value: /examples/render-modes/pages/ssr/+renderMode.js
Vue Example: GitHub > AaronBeaudoin/vite-plugin-ssr-example
.
- Server-side hook: /pages/_default/_default.page.server.ts
- Client-side hook: /pages/_default/_default.page.client.ts
- SPA page: /pages/spa.page.client.vue
- SSR page: /pages/ssr.page.vue
vite-plugin-ssr was the previous name of Vike. Contributions welcome to fork and update the Vue example.
SSR
The Vike boilerplates and documentation use SSR by default.
So, if we only have SSR pages, then there is nothing for us to do: we simply follow the boilerplates/docs.
If we want to have both SSR and SPA pages, then see the SPA section.
Pre-rendering (SSG)
See Guides > Pre-rendering (SSG).
HTML-only
⚠️Using modern UI frameworks (React/Vue/...) to render pages only to HTML is a novel technique and should be considered experimental.
To render a page to HTML-only:
- We set
Page
's meta configenv
to{ server: true, client: false }
instead of{ server: true, client: true }
. - (Optional) We define
+client.js
(e.g. to add a minimal amount of JavaScript surgically injecting bits of interactivity).
React example:
- Zero JavaScript: /examples/render-modes/pages/html-only/
- Minimal JavaScript: /examples/render-modes/pages/html-js/
Vue Example: GitHub > AaronBeaudoin/vite-plugin-ssr-example
> /pages/html.page.server.vue
vite-plugin-ssr was the previous name of Vike. Contributions welcome to fork and update the Vue example.