feat(nuxt): client only page

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

@@ -299,6 +299,10 @@ You may define a name for this page's route.
 
 You may define a path matcher, if you have a more complex pattern than can be expressed with the file name. See [the `vue-router` docs](https://router.vuejs.org/guide/essentials/route-matching-syntax.html#custom-regex-in-params) for more information.
 
+#### `clientOnly`
+
+Will wrap your page in [the Nuxt `<ClientOnly>` component](/docs/api/components/client-only) if you set `clientOnly: true` in your `definePageMeta`. This might be useful if you trying to import library that depends on `window` in page file.
+
 ### Typing Custom Metadata
 
 If you add custom metadata for your pages, you may wish to do so in a type-safe way. It is possible to augment the type of the object accepted by `definePageMeta`:

packages/nuxt/src/pages/runtime/composables.ts

@@ -38,6 +38,8 @@ export interface PageMeta {
   path?: string
   /** Set to `false` to avoid scrolling to top on page navigations */
   scrollToTop?: boolean | ((to: RouteLocationNormalizedLoaded, from: RouteLocationNormalizedLoaded) => boolean)
+  /** Make this page run on client only */
+  clientOnly?: boolean
 }
 
 declare module 'vue-router' {

packages/nuxt/src/pages/runtime/page.ts

@@ -8,6 +8,7 @@ import { toArray } from './utils'
 import type { RouterViewSlotProps } from './utils'
 import { generateRouteKey, wrapInKeepAlive } from './utils'
 import { RouteProvider } from '#app/components/route-provider'
+import ClientOnly from '#app/components/client-only'
 import { useNuxtApp } from '#app/nuxt'
 import { _wrapIf } from '#app/components/utils'
 import { LayoutMetaSymbol, PageRouteSymbol } from '#app/components/injections'
@@ -90,36 +91,39 @@ export default defineComponent({
           const key = generateRouteKey(routeProps, props.pageKey)
 
           const hasTransition = !!(props.transition ?? routeProps.route.meta.pageTransition ?? defaultPageTransition)
+          const keepaliveConfig = props.keepalive ?? routeProps.route.meta.keepalive ?? (defaultKeepaliveConfig as KeepAliveProps)
+          const clientOnlyConfig = routeProps.route.meta.clientOnly;
           const transitionProps = hasTransition && _mergeTransitionProps([
             props.transition,
             routeProps.route.meta.pageTransition,
             defaultPageTransition,
             { onAfterLeave: () => { nuxtApp.callHook('page:transition:finish', routeProps.Component) } }
           ].filter(Boolean))
 
-          const keepaliveConfig = props.keepalive ?? routeProps.route.meta.keepalive ?? (defaultKeepaliveConfig as KeepAliveProps)
-          vnode = _wrapIf(Transition, hasTransition && transitionProps,
-            wrapInKeepAlive(keepaliveConfig, h(Suspense, {
-              suspensible: true,
-              onPending: () => nuxtApp.callHook('page:start', routeProps.Component),
-              onResolve: () => { nextTick(() => nuxtApp.callHook('page:finish', routeProps.Component).then(() => nuxtApp.callHook('page:loading:end')).finally(done)) }
-            }, {
-              default: () => {
-                const providerVNode = h(RouteProvider, {
-                  key: key || undefined,
-                  vnode: routeProps.Component,
-                  route: routeProps.route,
-                  renderKey: key || undefined,
-                  trackRootNodes: hasTransition,
-                  vnodeRef: pageRef
-                })
-                if (import.meta.client && keepaliveConfig) {
-                  (providerVNode.type as any).name = (routeProps.Component.type as any).name || (routeProps.Component.type as any).__name || 'RouteProvider'
+          vnode = _wrapIf(ClientOnly, clientOnlyConfig,
+            _wrapIf(Transition, hasTransition && transitionProps,
+              wrapInKeepAlive(keepaliveConfig, h(Suspense, {
+                suspensible: true,
+                onPending: () => nuxtApp.callHook('page:start', routeProps.Component),
+                onResolve: () => { nextTick(() => nuxtApp.callHook('page:finish', routeProps.Component).then(() => nuxtApp.callHook('page:loading:end')).finally(done)) }
+              }, {
+                default: () => {
+                  const providerVNode = h(RouteProvider, {
+                    key: key || undefined,
+                    vnode: routeProps.Component,
+                    route: routeProps.route,
+                    renderKey: key || undefined,
+                    trackRootNodes: hasTransition,
+                    vnodeRef: pageRef
+                  })
+                  if (import.meta.client && keepaliveConfig) {
+                    (providerVNode.type as any).name = (routeProps.Component.type as any).name || (routeProps.Component.type as any).__name || 'RouteProvider'
+                  }
+                  return providerVNode
                 }
-                return providerVNode
-              }
-            })
-            )).default()
+              })
+            ))
+          ).default()
 
           return vnode
         }

test/basic.test.ts

@@ -469,6 +469,73 @@ describe('pages', () => {
     expect(response).not.toContain('don\'t look at this')
     expect(response).toContain('OH NNNNNNOOOOOOOOOOO')
   })
+
+  it('client only page', async () => {
+    const response = await fetch('/client-only').then(r => r.text())
+
+    // Should not contain rendered page on initial request
+    expect(response).not.toContain('"hasAccessToWindow": true')
+    expect(response).not.toContain('"isServer": false')
+
+    const errors: string[] = []
+    const { page: clientInitialPage } = await renderPage('/client-only-page')
+
+    clientInitialPage.on('console', (message) => {
+      const type = message.type()
+      if (type === 'error' || type === 'warning') {
+        errors.push(message.text())
+      }
+    })
+
+    // But after hydration element should appear and contain this object
+    expect(await clientInitialPage.locator('#state').textContent()).toMatchInlineSnapshot(`
+      "{
+        "hasAccessToWindow": true,
+        "isServer": false
+      }"
+    `)
+
+    expect(await clientInitialPage.locator('#server-rendered').textContent()).toMatchInlineSnapshot(`"false"`)
+
+    // Then go to non client only page
+    await clientInitialPage.click('a');
+
+    // that page should be client rendered
+    expect(await clientInitialPage.locator('#server-rendered').textContent()).toMatchInlineSnapshot(`"false"`)
+    // and not contain any errors or warnings
+    expect(errors.length).toBe(0);
+
+    await clientInitialPage.close();
+    errors.length = 0;
+
+    const { page: normalInitialPage } = await renderPage('/client-only-page/normal')
+
+    normalInitialPage.on('console', (message) => {
+      const type = message.type()
+      if (type === 'error' || type === 'warning') {
+        errors.push(message.text())
+      }
+    })
+
+    // Now non client only page should be sever rendered
+    expect(await normalInitialPage.locator('#server-rendered').textContent()).toMatchInlineSnapshot(`"true"`)
+
+    // Go to client only page
+    await normalInitialPage.click('a')
+
+    // and expect same object to be present
+    expect(await normalInitialPage.locator('#state').textContent()).toMatchInlineSnapshot(`
+      "{
+        "hasAccessToWindow": true,
+        "isServer": false
+      }"
+    `)
+
+    // also there should not be any errors
+    expect(errors.length).toBe(0);
+
+    await normalInitialPage.close()
+  })
 })
 
 describe('nuxt composables', () => {

test/fixtures/basic/pages/client-only-page/index.vue

@@ -0,0 +1,36 @@
+<script setup lang="ts">
+definePageMeta({ clientOnly: true })
+
+const state = useState('test', () => {
+  let hasAccessToWindow = null as null | boolean;
+
+  try {
+    hasAccessToWindow = Object.keys(window).at(0) ? true : false
+  } catch {
+    hasAccessToWindow = null
+  }
+
+  return {
+    hasAccessToWindow,
+    isServer: import.meta.server
+  }
+})
+
+const serverRendered = useState(() => import.meta.server)
+</script>
+
+<template>
+  <div>
+    <NuxtLink to="/client-only-page/normal">
+      normal
+    </NuxtLink>
+
+    <p id="state">
+      {{ state }}
+    </p>
+
+    <p id="server-rendered">
+      {{ serverRendered }}
+    </p>
+  </div>
+</template>

test/fixtures/basic/pages/client-only-page/normal.vue

@@ -0,0 +1,15 @@
+<script setup lang="ts">
+const renderedOnServer = useState(() => import.meta.server)
+</script>
+
+<template>
+  <div>
+    <NuxtLink to="/client-only-page">
+      to client only page
+    </NuxtLink>
+
+    <p id="server-rendered">
+      {{ renderedOnServer }}
+    </p>
+  </div>
+</template>