Migration `0.4`

Guide for migrating from 0.3.x to 0.4.x. See Migrations for other breaking updates.

Most changes are non-breaking: follow the warnings to progressively update to the new 0.4 interface.

Breaking changes:

Use Vite >=2.9.10 or Vite >=3.0.0-beta.7.
Deprecated: getPage() (Server Routing).
Deprecated: useClientRouter() (Client Routing).
Deprecated: pre-render CLI $ vike prerender.
Base URL options base and baseAsset are now defined as vite.config.js#base.
export default Page deprecated: use export { Page } instead.
Deprecated: Multiple onBeforeRender() hooks.

`getPage()`

  // /renderer/_default.page.client.js
 
- import { getPage } from 'vike/client'
+ export { render }
 
- const pageContext = await getPage()
+ async function render(pageContext) {
+   /* ... */
+ }

`useClientRouter()`

If you use Client Routing:

  // renderer/_default.page.client.js
 
- import { useClientRouter } from 'vike/client'
+ export { render }
+ export const clientRouting = true
 
- useClientRouter({
-   render: (pageContext) => {
-     /* ... */
-   }
- })
+ async function render(pageContext) {
+   /* ... */
+ }

All useClientRouter() options are now exports:

// renderer/_default.page.client.js
 
export { render }
export { onHydrationEnd }
export { onPageTransitionStart }
export { onPageTransitionEnd }
export const prefetchStaticAssets = { when: 'VIEWPORT' } // (instead of `prefetchLinks`)

Pre-render CLI

The pre-render CLI $ vike prerender is deprecated in favor of setting the prerender option to true in vite.config.js.

- $ vite build && vike prerender
+ $ vite build

  // vite.config.js
  import vike from 'vike/plugin'
 
  export config {
    plugins: [
-     vike()
+     vike({ prerender: true })
    ]
  }

The CLI command $ vite build will then automatically run the pre-rendering process.

All pre-render options are now defined in vite.config.js:

- $ vike prerender --partial -- noExtraDir --root src/ --outDir build/ --parallel 1

  // vite.config.js
  import vike from 'vike/plugin'
 
  export config {
+   root: 'src/',
+   build: {
+     outDir: 'build/
+   },
    plugins: [
      vike({
+       prerender: {
+         partial: true,
+         noExtraDir: true,
+         parallel: 1 // Can be `number` or `boolean`
+       }
      })
    ]
  }

Base URL

With 0.3, we defined base in both createPageRenderer() and vite.config.js. With 0.4, we define it only in vite.config.js.
The baseAsset option is removed: set base to an absolute URL instead. (A URL that starts with http:// or https://.)

  // server.js
 
- import { createPageRenderer } from 'vike'
- const renderPage = createPageRenderer({ base })
 
+ import { renderPage } from 'vike/server'
+ // We don't need to set `base` here anymore.
 
  const pageContext = await renderPage({ url })

// vite.config.js
 
export default {
  base: '/some/base/url/',
  // Or, if you used `baseAsset`:
  base: 'https://cdn.example.org/'
}

// vite.config.ts
 
import type { UserConfig } from 'vite'
 
export default {
  base: '/some/base/url/',
  // Or, if you used `baseAsset`:
  base: 'https://cdn.example.org/'
} satisfies UserConfig

`export default Page`

Most users already export { Page } in .page.js files, but some users use the default export instead (export default Page) which isn't supported anymore.

  // /pages/index.page.js
 
- export default Page
+ export { Page }
 
  function Page() {
    /* ... */
  }

Single File Components (.vue, .svelte, ...) still work.

Multiple `onBeforeRender()`

Multiple onBeforeRender() hooks are deprecated in favor of Custom Hooks/Exports.

Having one onBeforeRender() hook per page is still supported and hasn't changed.

Migration 0.4

getPage()

useClientRouter()