In a Vue 3 SSR app, what is the difference between createSSRApp and createApp, and which one must the browser entry call?

## Two ways to create a Vue app Vue 3 exports two application factories from the `vue` package: - `createApp(rootComponent, rootProps?)`: the normal client-side app. - `createSSRApp(rootComponent, rootProps?)`: an app in **SSR hydration mode**. The API reference is explicit that `createSSRApp` usage is exactly the same as `createApp()`: same arguments, same `app.use`, `app.provide`, `app.component` and `app.config`. The difference only appears when you call `app.mount(container)` in the browser. ## What mount() does in each case | | `createApp(...).mount('#app')` | `createSSRApp(...).mount('#app')` | |---|---|---| | Existing content in the container | removed (`container.textContent = ''`) | kept and adopted | | DOM creation | builds every node from scratch | reuses server-rendered nodes | | Event listeners | attached to the new nodes | attached to the existing nodes | | Mismatch between server HTML and client render | not applicable | existing nodes are morphed to match | | Empty container | normal mount | warning, then a full mount | With `createSSRApp`, Vue lazily switches to its **hydration renderer**. Mounting then means walking the existing DOM alongside the component tree, matching each vnode to the node already there, attaching listeners, and running client-side hooks such as `onMounted`. That process is **hydration**. If the container has no children, the hydration renderer logs `Attempting to hydrate existing markup but container is empty. Performing full mount instead.` and mounts normally. Seeing that warning usually means the server HTML never reached the container: wrong selector, a shell that forgot to insert the rendered string, or a client-only route. ## Why using createApp in the browser is a bug Nothing throws, which is what makes it easy to miss: 1. The server renders full HTML and the browser paints it. 2. The client entry calls `createApp(App).mount('#app')`. 3. Vue empties the container and rebuilds the same DOM from scratch. The result is wasted work on the client, possible visual flicker, lost focus or scroll inside the replaced nodes, and none of the benefits of reusing the server's DOM. ## Which side calls which The usual structure is one **universal** factory, imported by both entries: ```ts import { createSSRApp } from 'vue' import App from './App.vue' export function createApp() { const app = createSSRApp(App) // register plugins, provide per-request state here return { app } } ``` - The **server entry** calls it per request and passes the app to `renderToString` or a stream renderer from `vue/server-renderer`. Those functions accept any app instance, but using the same factory keeps both sides identical. - The **client entry** calls it once and runs `app.mount('#app')`, which hydrates because the app came from `createSSRApp`. ## What does not change Choosing `createSSRApp` changes how the first mount treats existing DOM, and nothing else: - Components, plugins, `provide`/`inject` and `app.config` behave exactly as in a client-only app. - After hydration, updates are ordinary client-side patches; the app does not stay in a special mode. - `onMounted` still runs in the browser once the component's DOM, here the adopted server DOM, is in place. - Components still have to be SSR-safe: `createSSRApp` does not make browser-only code safe to run on the server. Internally the hydration-capable renderer is created lazily, the first time `createSSRApp` is called, so a purely client-side app never sets it up. ## Rules that still apply - `mount()` can only be called once per app instance, on either kind of app. - The selector passed to `mount()` must match the element the server wrapped the rendered HTML in. - The server and client must render the same component tree with the same state, or hydration has to repair the difference. - In development both factories add the same checks on the app config; the SSR variant changes only how mounting treats existing DOM.