fix(next): sync modular dashboard widgets when server component re-renders (#15439)

## Problem
When a widget updates query parameters via `router.push` (e.g.,
incrementing a page counter), the server component `ModularDashboard`
correctly re-renders with updated `req.query` values and creates a new
`serverLayout` array containing the fresh server-rendered widget
components.
However, the client component `ModularDashboardClient` didn't reflect
these changes because `useDashboardLayout` only used `initialLayout` on
mount via `useState`, which ignores subsequent prop changes after the
initial render. This meant that even though the server component was
producing new data with updated query params, the client component's
state remained stale and widgets continued displaying the old values
until a full page refresh occurred.
## Use-Case Example
One example use case would be rendering a list view table within a
widget. When you perform pagination or sort columns, it changes the
query params, expecting the RSC to re-run, otherwise the list won't
react to these actions.
## Solution
Added a `useEffect` hook in `useDashboardLayout` that syncs the
`currentLayout` state whenever the `initialLayout` prop changes.

Author: AlessioGr

packages/next/src/views/Dashboard/Default/ModularDashboard/useDashboardLayout.ts

@@ -9,7 +9,7 @@ import {
 usePreferences,
 useServerFunctions,
 }from'@payloadcms/ui'
-importReact,{useCallback,useState}from'react'
+importReact,{useCallback,useEffect,useState}from'react'
 
 importtype{WidgetInstanceClient,WidgetItem}from'./index.client.js'
 importtype{GetDefaultLayoutServerFnReturnType}from'./renderWidget/getDefaultLayoutServerFn.js'
@@ -25,6 +25,13 @@ export function useDashboardLayout(initialLayout: WidgetInstanceClient[]) {
 constcancelModalSlug='cancel-dashboard-changes'
 const{ serverFunction }=useServerFunctions()
 
+// Sync state when initialLayout prop changes (e.g., when query params change and server component re-renders)
+useEffect(()=>{
+if(!isEditing){
+setCurrentLayout(initialLayout)
+}
+},[initialLayout,isEditing])
+
 constsaveLayout=useCallback(async()=>{
 try{
 constlayoutData: WidgetItem[]=currentLayout.map((item)=>item.item)

test/dashboard/components/PageQuery.tsx

@@ -0,0 +1,34 @@
+/* eslint-disable no-restricted-exports */
+
+import{typeWidgetServerProps}from'payload'
+importReactfrom'react'
+
+import{PageQueryButton}from'./PageQueryButton.client.js'
+
+exportdefaultfunctionPageQuery({ req }: WidgetServerProps){
+// Get page from query params
+constqueryPage=req.query?.page
+constcurrentPage=typeofqueryPage==='string' ? parseInt(queryPage,10) : 0
+
+return(
+<div
+className="page-query-widget card"
+style={{
+display: 'flex',
+flexDirection: 'column',
+gap: '16px',
+height: '100%',
+padding: '16px',
+}}
+>
+<div>
+<h3style={{fontSize: '16px',fontWeight: 600,margin: 0}}>Page Query Widget</h3>
+<pstyle={{color: '#6b7280',fontSize: '14px',margin: '8px 0 0 0'}}>
+ Current page from query: <strong>{currentPage}</strong>
+</p>
+</div>
+
+<PageQueryButtoncurrentPage={currentPage}/>
+</div>
+)
+}

test/dashboard/components/PageQueryButton.client.tsx

@@ -0,0 +1,40 @@
+'use client'
+
+import{usePathname,useRouter,useSearchParams}from'next/navigation.js'
+import{useCallback}from'react'
+
+typePageQueryButtonProps={
+currentPage: number
+}
+
+exportfunctionPageQueryButton({ currentPage }: PageQueryButtonProps){
+constrouter=useRouter()
+constpathname=usePathname()
+constsearchParams=useSearchParams()
+
+consthandleIncrement=useCallback(()=>{
+constparams=newURLSearchParams(searchParams.toString())
+constnewPage=currentPage+1
+params.set('page',String(newPage))
+router.push(`${pathname}?${params.toString()}`)
+},[currentPage,pathname,router,searchParams])
+
+return(
+<button
+onClick={handleIncrement}
+style={{
+backgroundColor: '#2563eb',
+border: 'none',
+borderRadius: '6px',
+color: 'white',
+cursor: 'pointer',
+fontSize: '14px',
+fontWeight: 500,
+padding: '8px 16px',
+}}
+type="button"
+>
+ Increment Page ({currentPage} → {currentPage+1})
+</button>
+)
+}

test/dashboard/config.ts

@@ -13,9 +13,6 @@ const dirname = path.dirname(filename)
 
 exportdefaultbuildConfigWithDefaults({
 admin: {
-importMap: {
-baseDir: path.resolve(dirname),
-},
 components: {
 afterDashboard: ['./components/BeforeOrAfterDashboard.js'],
 beforeDashboard: ['./components/BeforeOrAfterDashboard.js'],
@@ -78,8 +75,16 @@ export default buildConfigWithDefaults({
 label: ({ i18n })=>(i18n.language==='es' ? 'Gráfico de Ingresos' : 'Revenue Chart'),
 minWidth: 'medium',
 },
+{
+slug: 'page-query',
+ComponentPath: './components/PageQuery.tsx#default',
+label: 'Page Query Widget',
+},
 ],
 },
+importMap: {
+baseDir: path.resolve(dirname),
+},
 },
 collections: [
 Tickets,

test/dashboard/e2e.spec.ts

@@ -199,4 +199,33 @@ describe('Dashboard', () => {
 expect(labels).toContain('Collections')
 }).toPass({timeout: 1000})
 })
+
+test('widget re-renders when query params change (= modular dashboard RSC rerenders)',async({
+ page,
+})=>{
+constd=newDashboardHelper(page)
+awaitd.setEditing()
+awaitd.addWidget('page query')
+awaitd.assertWidget(8,'page-query','x-small')
+awaitd.saveChangesAndValidate()
+
+// Find the page-query widget
+constpageQueryWidget=page.locator('.page-query-widget')
+awaitexpect(pageQueryWidget).toBeVisible()
+
+// Initially, page should be 0 (default)
+awaitexpect(pageQueryWidget.getByText(/Currentpagefromquery:0/)).toBeVisible()
+
+// Click the increment button
+constincrementButton=pageQueryWidget.getByRole('button',{name: /IncrementPage/})
+awaitincrementButton.click()
+
+// The page number should update to 1 without a page refresh
+// This test will fail until the server component re-renders when query params change
+awaitexpect(pageQueryWidget.getByText(/Currentpagefromquery:1/)).toBeVisible()
+
+// Click again to increment to 2
+awaitincrementButton.click()
+awaitexpect(pageQueryWidget.getByText(/Currentpagefromquery:2/)).toBeVisible()
+})
 })