⚠️
The vite-plugin-ssr project has been renamed Vike.
  • If you are already using vite-plugin-ssr then migrate to Vike.
  • For new projects, don't use vite-plugin-ssr but use Vike instead.

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:

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

getPage()

If you use Server Routing:

  // /renderer/_default.page.client.js

- import { getPage } from 'vite-plugin-ssr/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 'vite-plugin-ssr/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 $ vite-plugin-ssr prerender is deprecated in favor of setting the prerender option to true in vite.config.js.

- $ vite build && vite-plugin-ssr prerender
+ $ vite build
  // vite.config.js
  import { ssr } from 'vite-plugin-ssr/plugin'

  export config {
    plugins: [
-     ssr()
+     ssr({ 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:

- $ vite-plugin-ssr prerender --partial -- noExtraDir --root src/ --outDir build/ --parallel 1
  // vite.config.js
  import { ssr } from 'vite-plugin-ssr/plugin'

  export config {
+   root: 'src/',
+   build: {
+     outDir: 'build/
+   },
    plugins: [
      ssr({
+       prerender: {
+         partial: true,
+         noExtraDir: true,
+         parallel: 1 // Can be `number` or `boolean`
+       }
      })
    ]
  }

Base URL

  1. With 0.3, we defined base in both createPageRenderer() and vite.config.js. With 0.4, we define it only in vite.config.js.
  2. 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 'vite-plugin-ssr'
- const renderPage = createPageRenderer({ base })

+ import { renderPage } from 'vite-plugin-ssr/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/'
}

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.