feat(next): pass full initReq context to server functions and dashboard widgets (#15427)

Currently, we only pass `importMap` and `req` to all server functions.
This PR extends that interface by passing the following **additional
arguments** to every server function and every dashboard widget:

- `cookies`
- `locale`
- `permissions`

This change comes at **no extra cost**, since all of these values are
already available via `initReq`, which we are already calling.

## Why?

I’m working on rendering the list view in a dashboard widget through a
server function, which requires context such as `permissions`.
Recomputing these values would be redundant and inefficient, given that
they’ve already been calculated in `handleServerFunctions` and we can
just pass them through.

By passing them through once, we avoid duplicate work and make server
functions easier to use.

Author: AlessioGr

packages/next/src/utilities/handleServerFunctions.ts

@@ -1,4 +1,4 @@
-import type { ServerFunction, ServerFunctionHandler } from 'payload'
+import type { DefaultServerFunctionArgs, ServerFunction, ServerFunctionHandler } from 'payload'
 
 import { _internal_renderFieldHandler, copyDataFromLocaleHandler } from '@payloadcms/ui/rsc'
 import { buildFormStateHandler } from '@payloadcms/ui/utilities/buildFormState'
@@ -38,24 +38,22 @@ export const handleServerFunctions: ServerFunctionHandler = async (args) => {
     serverFunctions: extraServerFunctions,
   } = args
 
-  const { req } = await initReq({
+  const { cookies, locale, permissions, req } = await initReq({
     configPromise,
     importMap,
     key: 'RootLayout',
   })
 
-  const augmentedArgs: Parameters<ServerFunction>[0] = {
+  const augmentedArgs: DefaultServerFunctionArgs = {
     ...fnArgs,
+    cookies,
     importMap,
+    locale,
+    permissions,
     req,
   }
 
-  const serverFunctions = {
-    ...baseServerFunctions,
-    ...(extraServerFunctions || {}),
-  }
-
-  const fn = serverFunctions[fnKey]
+  const fn = extraServerFunctions?.[fnKey] || baseServerFunctions[fnKey]
 
   if (!fn) {
     throw new Error(`Unknown Server Function: ${fnKey}`)

packages/next/src/utilities/initReq.ts

@@ -1,13 +1,5 @@
-import type { AcceptedLanguages, I18n, I18nClient } from '@payloadcms/translations'
-import type {
-  ImportMap,
-  Locale,
-  Payload,
-  PayloadRequest,
-  SanitizedConfig,
-  SanitizedPermissions,
-  TypedUser,
-} from 'payload'
+import type { I18n, I18nClient } from '@payloadcms/translations'
+import type { ImportMap, InitReqResult, PayloadRequest, SanitizedConfig } from 'payload'
 
 import { initI18n } from '@payloadcms/translations'
 import { headers as getHeaders } from 'next/headers.js'
@@ -23,26 +15,14 @@ import {
 import { getRequestLocale } from './getRequestLocale.js'
 import { selectiveCache } from './selectiveCache.js'
 
-type Result = {
-  cookies: Map<string, string>
-  headers: Awaited<ReturnType<typeof getHeaders>>
-  languageCode: AcceptedLanguages
-  locale?: Locale
-  permissions: SanitizedPermissions
-  req: PayloadRequest
-}
-
 type PartialResult = {
   i18n: I18nClient
-  languageCode: AcceptedLanguages
-  payload: Payload
-  responseHeaders: Headers
-  user: null | TypedUser
-}
+} & Pick<InitReqResult, 'languageCode'> &
+  Pick<PayloadRequest, 'payload' | 'responseHeaders' | 'user'>
 
 // Create cache instances for different parts of our application
 const partialReqCache = selectiveCache<PartialResult>('partialReq')
-const reqCache = selectiveCache<Result>('req')
+const reqCache = selectiveCache<InitReqResult>('req')
 
 /**
  * Initializes a full request object, including the `req` object and access control.
@@ -60,7 +40,7 @@ export const initReq = async function ({
   importMap: ImportMap
   key: string
   overrides?: Parameters<typeof createLocalReq>[0]
-}): Promise<Result> {
+}): Promise<InitReqResult> {
   const headers = await getHeaders()
   const cookies = parseCookies(headers)
 

packages/next/src/views/Dashboard/Default/ModularDashboard/index.tsx

@@ -26,7 +26,7 @@ export async function ModularDashboard(props: DashboardViewServerProps) {
   const { defaultLayout = [], widgets = [] } = props.payload.config.admin.dashboard || {}
   const { importMap } = props.payload
   const { user } = props
-  const { req } = props.initPageResult
+  const { cookies, locale, permissions, req } = props.initPageResult
   const { i18n } = req
 
   const layout =
@@ -40,6 +40,9 @@ export async function ModularDashboard(props: DashboardViewServerProps) {
         Component: widgets.find((widget) => widget.slug === widgetSlug)?.ComponentPath,
         importMap,
         serverProps: {
+          cookies,
+          locale,
+          permissions,
           req,
           widgetSlug,
           // TODO: widgets will support state in the future

packages/next/src/views/Dashboard/Default/ModularDashboard/renderWidget/getDefaultLayoutServerFn.ts

@@ -23,7 +23,7 @@ export type GetDefaultLayoutServerFnReturnType = {
 export const getDefaultLayoutHandler: ServerFunction<
   GetDefaultLayoutServerFnArgs,
   Promise<GetDefaultLayoutServerFnReturnType>
-> = async ({ req }) => {
+> = async ({ cookies, locale, permissions, req }) => {
   if (!req.user) {
     throw new Error('Unauthorized')
   }
@@ -40,6 +40,9 @@ export const getDefaultLayoutHandler: ServerFunction<
         Component: widgets.find((widget) => widget.slug === widgetSlug)?.ComponentPath,
         importMap,
         serverProps: {
+          cookies,
+          locale,
+          permissions,
           req,
           widgetSlug,
         } satisfies WidgetServerProps,

packages/next/src/views/Dashboard/Default/ModularDashboard/renderWidget/renderWidgetServerFn.ts

@@ -26,7 +26,7 @@ export type RenderWidgetServerFnReturnType = {
 export const renderWidgetHandler: ServerFunction<
   RenderWidgetServerFnArgs,
   RenderWidgetServerFnReturnType
-> = ({ req, /* widgetData, */ widgetSlug }) => {
+> = ({ cookies, locale, permissions, req, widgetSlug }) => {
   if (!req.user) {
     throw new Error('Unauthorized')
   }
@@ -61,6 +61,9 @@ export const renderWidgetHandler: ServerFunction<
     const serverProps: WidgetServerProps = {
       req,
       // TODO: widgetData: widgetData || {},
+      cookies,
+      locale,
+      permissions,
       widgetSlug,
     }
 

packages/payload/src/admin/functions/index.ts

@@ -1,5 +1,7 @@
+import type { AcceptedLanguages } from '@payloadcms/translations'
+
 import type { ImportMap } from '../../bin/generateImportMap/index.js'
-import type { SanitizedConfig } from '../../config/types.js'
+import type { Locale, SanitizedConfig } from '../../config/types.js'
 import type { PaginatedDocs } from '../../database/types.js'
 import type { Slugify } from '../../fields/baseFields/slug/index.js'
 import type {
@@ -8,15 +10,26 @@ import type {
   FieldPaths,
   FolderSortKeys,
   GlobalSlug,
+  SanitizedPermissions,
 } from '../../index.js'
 import type { PayloadRequest, Sort, Where } from '../../types/index.js'
 import type { ColumnsFromURL } from '../../utilities/transformColumnPreferences.js'
 
-export type DefaultServerFunctionArgs = {
-  importMap: ImportMap
+export type InitReqResult = {
+  cookies: Map<string, string>
+  // TODO: Remove in 4.0. Duplicative, already available in req.headers
+  headers: Headers
+  // TODO: Remove in 4.0. Duplicative, already available in req.i18n.language
+  languageCode: AcceptedLanguages
+  locale?: Locale
+  permissions: SanitizedPermissions
   req: PayloadRequest
 }
 
+export type DefaultServerFunctionArgs = {
+  importMap: ImportMap
+} & Pick<InitReqResult, 'cookies' | 'locale' | 'permissions' | 'req'>
+
 export type ServerFunctionArgs = {
   args: Record<string, unknown>
   name: string

packages/payload/src/admin/types.ts

@@ -585,6 +585,7 @@ export type {
   BuildTableStateArgs,
   DefaultServerFunctionArgs,
   GetFolderResultsComponentAndDataArgs,
+  InitReqResult,
   ListQuery,
   ServerFunction,
   ServerFunctionArgs,

packages/payload/src/admin/views/dashboard.ts

@@ -1,12 +1,11 @@
-import type { PayloadRequest } from '../../index.js'
+import type { InitReqResult } from '../../index.js'
 
 export enum EntityType {
   collection = 'collections',
   global = 'globals',
 }
 
 export type WidgetServerProps = {
-  req: PayloadRequest
   widgetData?: Record<string, unknown>
   widgetSlug: string
-}
+} & Pick<InitReqResult, 'cookies' | 'locale' | 'permissions' | 'req'>