feat(nuxt): add <NuxtClientFallback> component

docs/2.guide/2.directory-structure/1.components.md

@@ -325,6 +325,24 @@ The content will not be included in production builds and tree-shaken.
 </template>
 ```
 
+## <ClientFallback> Component
+
+Nuxt provides the `<ClientFallback>` component to render its slot in client-side if it fails to render in ssr.
+You can specify a `fallbackTag` to `<ClientFallback>` to make it render a specific tag if it fails to render in ssr.
+
+```html{}[pages/example.vue]
+<template>
+  <div>
+    <Sidebar />
+    <!-- this component will be rendered on client-side -->
+    <ClientFallback fallback-tag="span">
+      <Comments />
+      <BrokeInSSR />
+    </ClientFallback>
+  </div>
+</template>
+```
+
 ## Library Authors
 
 Making Vue component libraries with automatic tree-shaking and component registration is super easy ✨

docs/3.api/2.components/1.client-fallback.md

@@ -0,0 +1,54 @@
+---
+title: "<ClientFallback>"
+description: "Nuxt provides `<ClientFallback>` component to render its children on client side if some of them triggers an error in SSR"
+---
+
+# `<ClientFallback>`
+
+Nuxt provides `<ClientFallback>` component to render its children on client side if some of them triggers an error in SSR.
+
+## Events
+
+- **`@ssr-error`**: Event emitted when a children triggers an error in SSR. Note that this will be only triggered server-side.
+
+  ```vue
+  <template>
+    <ClientFallback @ssr-error="logSomeError">
+      <!-- ... -->
+    </ClientFallback>
+  </template>
+  ```
+
+## Props
+
+- **placeholderTag** | **fallbackTag**: Specify a fallback tag to be rendered if the slot fails to render.
+  - **type**: `string`
+  - **default**: `div`
+- **placeholder** | **fallback**: Specify a fallback content to be rendered if the slot fails to render.
+  - **type**: `string`
+
+```vue
+  <template>
+    <!-- render <span>Hello world</span> server-side if the default slot fails to render -->
+    <ClientFallback fallback-tag="span" fallback="Hello world">
+      <BrokeInSsr />
+    </ClientFallback>
+  </template>
+```
+
+## Slots
+
+- **#fallback**: specify a content to be displayed server-side if the slot fails to render.
+
+```vue
+<template>
+  <ClientFallback>
+    <!-- ... -->
+    <template #fallback>
+      <!-- this will be rendered on server side if the default slot fails to render in ssr -->
+      <p>Hello world</p>
+    </template>
+  </ClientFallback>
+</template>
+```
+

packages/nuxt/src/app/components/client-fallback.mjs

@@ -0,0 +1,119 @@
+import { defineComponent, createElementBlock, getCurrentInstance, onErrorCaptured } from 'vue'
+import { ssrRenderVNode, ssrRenderAttrs, ssrRenderSlot } from 'vue/server-renderer'
+import { createBuffer } from './utils'
+
+const clientFallback = process.server
+  ? {
+      name: 'ClientFallback',
+      inheritAttrs: false,
+      props: {
+        uid: {
+          type: String
+        },
+        fallbackTag: {
+          type: String,
+          default: () => 'div'
+        },
+        fallback: {
+          type: String,
+          default: () => ''
+        },
+        placeholder: {
+          type: String
+        },
+        placeholderTag: {
+          type: String
+        }
+      },
+      emits: ['ssr-error'],
+      setup (props, ctx) {
+        const vm = getCurrentInstance()
+        const ssrFailed = ref(false)
+
+        onErrorCaptured(() => {
+          useState(`${props.uid}`, () => true)
+          ssrFailed.value = true
+          ctx.emit('ssr-error')
+          return false
+        })
+
+        try {
+          const defaultSlot = ctx.slots.default?.()
+          const ssrVNodes = createBuffer()
+
+          for (let i = 0; i < defaultSlot.length; i++) {
+            ssrRenderVNode(ssrVNodes.push, defaultSlot[i], vm)
+          }
+
+          return { ssrFailed, ssrVNodes }
+        } catch {
+          // catch in dev
+          useState(`${props.uid}`, () => true)
+          ctx.emit('ssr-error')
+          return { ssrFailed: true, ssrVNodes: [] }
+        }
+      },
+      ssrRender (ctx, push, parent) {
+        if (ctx.ssrFailed) {
+          const { fallback, placeholder } = ctx.$slots
+          if (fallback || placeholder) {
+            ssrRenderSlot(ctx.$slots, fallback ? 'fallback' : 'placeholder', {}, null, push, parent)
+          } else {
+            const content = ctx.placeholder || ctx.fallback
+            const tag = ctx.placeholderTag || ctx.fallbackTag
+            push(`<${tag}${ssrRenderAttrs(ctx.$attrs)}>${content}</${tag}>`)
+          }
+        } else {
+          // push Fragment markup
+          push('<!--[-->')
+          push(ctx.ssrVNodes.getBuffer())
+          push('<!--]-->')
+        }
+      }
+    }
+  : {
+      name: 'ClientFallback',
+      inheritAttrs: false,
+      props: {
+        uid: {
+          type: String
+        },
+        fallbackTag: {
+          type: String,
+          default: () => 'div'
+        },
+        fallback: {
+          type: String,
+          default: () => ''
+        },
+        placeholder: {
+          type: String
+        },
+        placeholderTag: {
+          type: String
+        }
+      },
+      emits: ['ssr-error'],
+      setup (props, ctx) {
+        const mounted = ref(false)
+        const ssrFailed = useState(`${props.uid}`)
+
+        if (ssrFailed.value) {
+          onMounted(() => { mounted.value = true })
+        }
+
+        return () => {
+          if (mounted.value) { return ctx.slots.default?.() }
+          if (ssrFailed.value) {
+            const slot = ctx.slots.placeholder || ctx.slots.fallback
+            if (slot) { return slot() }
+            const fallbackStr = props.placeholder || props.fallback
+            const fallbackTag = props.placeholderTag || props.fallbackTag
+            return createElementBlock(fallbackTag, null, fallbackStr)
+          }
+          return ctx.slots.default?.()
+        }
+      }
+    }
+
+export default defineComponent(clientFallback)

packages/nuxt/src/app/components/utils.ts

@@ -1,5 +1,7 @@
 import { defineComponent, h } from 'vue'
 import type { Component } from 'vue'
+// eslint-disable-next-line
+import { isString, isPromise, isArray } from '@vue/shared'
 
 const Fragment = defineComponent({
   name: 'FragmentWrapper',
@@ -16,3 +18,35 @@ const Fragment = defineComponent({
 export const _wrapIf = (component: Component, props: any, slots: any) => {
   return { default: () => props ? h(component, props === true ? {} : props, slots) : h(Fragment, {}, slots) }
 }
+
+// eslint-disable-next-line no-use-before-define
+export type SSRBuffer = SSRBufferItem[] & { hasAsync?: boolean }
+export type SSRBufferItem = string | SSRBuffer | Promise<SSRBuffer>
+
+/**
+ * create buffer retrieved from @vue/server-renderer
+ *
+ * @see https://github.com/vuejs/core/blob/9617dd4b2abc07a5dc40de6e5b759e851b4d0da1/packages/server-renderer/src/render.ts#L57
+ * @private
+ */
+export function createBuffer () {
+  let appendable = false
+  const buffer: SSRBuffer = []
+  return {
+    getBuffer (): SSRBuffer {
+      return buffer
+    },
+    push (item: SSRBufferItem) {
+      const isStringItem = isString(item)
+      if (appendable && isStringItem) {
+        buffer[buffer.length - 1] += item as string
+      } else {
+        buffer.push(item)
+      }
+      appendable = isStringItem
+      if (isPromise(item) || (isArray(item) && item.hasAsync)) {
+        buffer.hasAsync = true
+      }
+    }
+  }
+}

packages/nuxt/src/components/client-fallback-auto-id.ts

@@ -0,0 +1,52 @@
+import { createUnplugin } from 'unplugin'
+import type { ComponentsOptions } from '@nuxt/schema'
+import MagicString from 'magic-string'
+import { isAbsolute, relative } from 'pathe'
+import { hash } from 'ohash'
+import { isVueTemplate } from './helpers'
+interface LoaderOptions {
+  sourcemap?: boolean
+  transform?: ComponentsOptions['transform'],
+  rootDir: string
+}
+
+export const clientFallbackAutoIdPlugin = createUnplugin((options: LoaderOptions) => {
+  const exclude = options.transform?.exclude || []
+  const include = options.transform?.include || []
+
+  return {
+    name: 'nuxt:client-fallback-auto-id',
+    enforce: 'pre',
+    transformInclude (id) {
+      if (exclude.some(pattern => id.match(pattern))) {
+        return false
+      }
+      if (include.some(pattern => id.match(pattern))) {
+        return true
+      }
+      return isVueTemplate(id)
+    },
+    transform (code, id) {
+      if (!/[cC]lient-?[fF]allback/.test(code)) { return }
+
+      const s = new MagicString(code)
+      const relativeID = isAbsolute(id) ? relative(options.rootDir, id) : id
+      let count = 0
+
+      s.replace(/<([cC]lient-?[fF]allback)( [^>]*)?>/g, (full, name, attrs) => {
+        count++
+        if (/ :?uid=/g.test(attrs)) { return full }
+        return `<${name} :uid="'${hash(relativeID)}' + JSON.stringify($props) + '${count}'"  ${attrs ?? ''}>`
+      })
+
+      if (s.hasChanged()) {
+        return {
+          code: s.toString(),
+          map: options.sourcemap
+            ? s.generateMap({ source: id, includeContent: true })
+            : undefined
+        }
+      }
+    }
+  }
+})

packages/nuxt/src/components/helpers.ts

@@ -0,0 +1,29 @@
+import { pathToFileURL } from 'node:url'
+import { parseQuery, parseURL } from 'ufo'
+
+export function isVueTemplate (id: string) {
+  // Bare `.vue` file (in Vite)
+  if (id.endsWith('.vue')) {
+    return true
+  }
+
+  const { search } = parseURL(decodeURIComponent(pathToFileURL(id).href))
+  if (!search) {
+    return false
+  }
+
+  const query = parseQuery(search)
+
+  // Macro
+  if (query.macro) {
+    return true
+  }
+
+  // Non-Vue or Styles
+  if (!('vue' in query) || query.type === 'style') {
+    return false
+  }
+
+  // Query `?vue&type=template` (in Webpack or external template)
+  return true
+}

packages/nuxt/src/components/loader.ts

@@ -1,13 +1,13 @@
-import { pathToFileURL } from 'node:url'
 import { createUnplugin } from 'unplugin'
-import { parseQuery, parseURL } from 'ufo'
 import type { Component, ComponentsOptions } from '@nuxt/schema'
 import { genDynamicImport, genImport } from 'knitwork'
 import MagicString from 'magic-string'
 import { pascalCase } from 'scule'
 import { resolve } from 'pathe'
 import { distDir } from '../dirs'
 
+import { isVueTemplate } from './helpers'
+
 interface LoaderOptions {
   getComponents (): Component[]
   mode: 'server' | 'client'
@@ -16,33 +16,6 @@ interface LoaderOptions {
   experimentalComponentIslands?: boolean
 }
 
-function isVueTemplate (id: string) {
-  // Bare `.vue` file (in Vite)
-  if (id.endsWith('.vue')) {
-    return true
-  }
-
-  const { search } = parseURL(decodeURIComponent(pathToFileURL(id).href))
-  if (!search) {
-    return false
-  }
-
-  const query = parseQuery(search)
-
-  // Macro
-  if (query.macro) {
-    return true
-  }
-
-  // Non-Vue or Styles
-  if (!('vue' in query) || query.type === 'style') {
-    return false
-  }
-
-  // Query `?vue&type=template` (in webpack or external template)
-  return true
-}
-
 export const loaderPlugin = createUnplugin((options: LoaderOptions) => {
   const exclude = options.transform?.exclude || []
   const include = options.transform?.include || []