feat(nuxt): add setPageLayout utility (#6826)

docs/content/2.guide/3.directory-structure/7.layouts.md

@@ -121,9 +121,8 @@ You can also use a ref or computed property for your layout.
 </template>
 
 <script setup>
-const route = useRoute()
 function enableCustomLayout () {
-  route.meta.layout = "custom"
+  setPageLayout('custom')
 }
 definePageMeta({
   layout: false,

docs/content/3.api/1.composables/set-layout.md

@@ -0,0 +1,14 @@
+# `setPageLayout`
+
+`setPageLayout` allows you to dynamically change the layout of a page. It relies on access to the Nuxt context and can only be called within components' setup functions, plugins, and route middleware.
+
+```ts
+export default defineNuxtRouteMiddleware((to) => {
+  // Set the layout on the route you are navigating _to_
+  setPageLayout('other')
+})
+```
+
+::alert{icon=👉}
+If you choose to set the layout dynamically on the server side, you _must_ do so before the layout is rendered by Vue (that is, within a plugin or route middleware) to avoid a hydration mismatch.
+::

examples/routing/layouts/middleware/other.ts

@@ -0,0 +1,4 @@
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+export default defineNuxtRouteMiddleware(() => {
+  setPageLayout('other')
+})

examples/routing/layouts/pages/index.vue

@@ -11,6 +11,18 @@
         <NuxtLink to="/dynamic">
           Dynamic layout
         </NuxtLink>
+        <NuxtLink to="/other">
+          Other layout
+        </NuxtLink>
+        <NButton @click="setPageLayout('default')">
+          Change to default layout
+        </NButton>
+        <NButton @click="setPageLayout('custom')">
+          Change to custom layout
+        </NButton>
+        <NButton @click="setPageLayout('other')">
+          Change to other layout
+        </NButton>
       </nav>
     </template>
   </NuxtExampleLayout>

examples/routing/layouts/pages/other.vue

@@ -0,0 +1,13 @@
+<script setup>
+definePageMeta({
+  middleware: 'other'
+})
+</script>
+
+<template>
+  <div>
+    <NuxtLink to="/">
+      Back to home
+    </NuxtLink>
+  </div>
+</template>

packages/nuxt/src/app/composables/index.ts

@@ -10,6 +10,6 @@ export type { FetchResult, UseFetchOptions } from './fetch'
 export { useCookie } from './cookie'
 export type { CookieOptions, CookieRef } from './cookie'
 export { useRequestHeaders, useRequestEvent, setResponseStatus } from './ssr'
-export { abortNavigation, addRouteMiddleware, defineNuxtRouteMiddleware, navigateTo, useRoute, useActiveRoute, useRouter } from './router'
+export { abortNavigation, addRouteMiddleware, defineNuxtRouteMiddleware, setPageLayout, navigateTo, useRoute, useActiveRoute, useRouter } from './router'
 export type { AddRouteMiddlewareOptions, RouteMiddleware } from './router'
 export { preloadComponents, prefetchComponents } from './preload'

packages/nuxt/src/app/composables/router.ts

@@ -2,7 +2,7 @@ import { getCurrentInstance, inject } from 'vue'
 import type { Router, RouteLocationNormalizedLoaded, NavigationGuard, RouteLocationNormalized, RouteLocationRaw, NavigationFailure, RouteLocationPathRaw } from 'vue-router'
 import { sendRedirect } from 'h3'
 import { hasProtocol, joinURL, parseURL } from 'ufo'
-import { useNuxtApp, useRuntimeConfig } from '#app'
+import { useNuxtApp, useRuntimeConfig, useState } from '#app'
 
 export const useRouter = () => {
   return useNuxtApp()?.$router as Router
@@ -114,3 +114,20 @@ export const abortNavigation = (err?: Error | string) => {
   }
   return false
 }
+
+export const setPageLayout = (layout: string) => {
+  if (process.server) {
+    useState('_layout').value = layout
+  }
+  const nuxtApp = useNuxtApp()
+  const inMiddleware = isProcessingMiddleware()
+  if (inMiddleware || process.server || nuxtApp.isHydrating) {
+    const unsubscribe = useRouter().beforeResolve((to) => {
+      to.meta.layout = layout
+      unsubscribe()
+    })
+  }
+  if (!inMiddleware) {
+    useRoute().meta.layout = layout
+  }
+}

packages/nuxt/src/app/plugins/router.ts

@@ -1,7 +1,7 @@
 import { reactive, h } from 'vue'
 import { parseURL, stringifyParsedURL, parseQuery, stringifyQuery, withoutBase, isEqual, joinURL } from 'ufo'
 import { createError } from 'h3'
-import { defineNuxtPlugin, clearError, navigateTo, showError, useRuntimeConfig } from '..'
+import { defineNuxtPlugin, clearError, navigateTo, showError, useRuntimeConfig, useState } from '..'
 import { callWithNuxt } from '../nuxt'
 // @ts-ignore
 import { globalMiddleware } from '#build/middleware'
@@ -218,9 +218,13 @@ export default defineNuxtPlugin<{ route: Route, router: Router }>((nuxtApp) => {
     named: {}
   }
 
+  const initialLayout = useState('_layout')
   nuxtApp.hooks.hookOnce('app:created', async () => {
     router.beforeEach(async (to, from) => {
       to.meta = reactive(to.meta || {})
+      if (nuxtApp.isHydrating) {
+        to.meta.layout = initialLayout.value ?? to.meta.layout
+      }
       nuxtApp._processingMiddleware = true
 
       const middlewareEntries = new Set<RouteGuard>([...globalMiddleware, ...nuxtApp._middleware.global])

packages/nuxt/src/imports/presets.ts

@@ -36,6 +36,7 @@ const appPreset = defineUnimportPreset({
     'useRequestHeaders',
     'useRequestEvent',
     'setResponseStatus',
+    'setPageLayout',
     'useRouter',
     'useRoute',
     'useActiveRoute',

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

@@ -9,7 +9,7 @@ import {
 import { createError } from 'h3'
 import { withoutBase, isEqual } from 'ufo'
 import NuxtPage from './page'
-import { callWithNuxt, defineNuxtPlugin, useRuntimeConfig, showError, clearError, navigateTo, useError } from '#app'
+import { callWithNuxt, defineNuxtPlugin, useRuntimeConfig, showError, clearError, navigateTo, useError, useState } from '#app'
 // @ts-ignore
 import routes from '#build/routes'
 // @ts-ignore
@@ -114,8 +114,12 @@ export default defineNuxtPlugin(async (nuxtApp) => {
     callWithNuxt(nuxtApp, showError, [error])
   }
 
+  const initialLayout = useState('_layout')
   router.beforeEach(async (to, from) => {
     to.meta = reactive(to.meta)
+    if (nuxtApp.isHydrating) {
+      to.meta.layout = initialLayout.value ?? to.meta.layout
+    }
     nuxtApp._processingMiddleware = true
 
     type MiddlewareDef = string | NavigationGuard

test/basic.test.ts

@@ -273,6 +273,16 @@ describe('layouts', () => {
     expect(html).toContain('with-layout.vue')
     expect(html).toContain('Custom Layout:')
   })
+  it('should work with a dynamically set layout', async () => {
+    const html = await $fetch('/with-dynamic-layout')
+
+    // Snapshot
+    // expect(html).toMatchInlineSnapshot()
+
+    expect(html).toContain('with-dynamic-layout')
+    expect(html).toContain('Custom Layout:')
+    await expectNoClientErrors('/with-dynamic-layout')
+  })
 })
 
 describe('reactivity transform', () => {

test/fixtures/basic/middleware/sets-layout.ts

@@ -0,0 +1,4 @@
+export default defineNuxtRouteMiddleware(async () => {
+  await new Promise(resolve => setTimeout(resolve, 10))
+  setPageLayout('custom')
+})

test/fixtures/basic/pages/with-dynamic-layout.vue

@@ -0,0 +1,11 @@
+<script setup>
+definePageMeta({
+  middleware: 'sets-layout'
+})
+</script>
+
+<template>
+  <div>
+    <div>with-dynamic-layout.vue</div>
+  </div>
+</template>