Repository navigation
refactor!: consolidate initReq across framework adapters - #17690
Merged
Merged
Conversation
Contributor
📦 esbuild Bundle Analysis for payloadThis analysis was generated by esbuild-bundle-analyzer. 🤖
Largest pathsThese visualization shows top 20 largest paths in the bundle.Meta file: packages/next/meta_index.json, Out file: esbuild/index.js
Meta file: packages/payload/meta_index.json, Out file: esbuild/index.js
Meta file: packages/payload/meta_shared.json, Out file: esbuild/exports/shared.js
Meta file: packages/richtext-lexical/meta_client.json, Out file: esbuild/exports/client_optimized/index.js
Meta file: packages/ui/meta_client.json, Out file: esbuild/exports/client_optimized/index.js
Meta file: packages/ui/meta_shared.json, Out file: esbuild/exports/shared_optimized/index.js
DetailsNext to the size is how much the size has increased or decreased compared with the base branch of this PR.
|
# Conflicts: # package.json # packages/tanstack-start/src/layouts/Root/getLayoutData.ts # packages/tanstack-start/src/utilities/initReq.server.ts # packages/ui/src/layouts/Root/index.tsx # packages/ui/src/utilities/initReq.ts # vitest.config.ts
jacobsfletch
changed the title
jacobsfletch
commented
Sep 22, 2026
| const { responseHeaders, user } = await executeAuthStrategies({ | ||
| headers, | ||
| payload, | ||
| export const initReq = ({ serverAdapter = tanstackServerAdapter, ...args }: TanStackInitReqArgs) => |
Member
Author
There was a problem hiding this comment.
This is where the majority of the consolidation surfaces.
jacobsfletch
marked this pull request as ready for review
September 22, 2026 21:04
jacobsfletch
requested review from
DanRibbens,
JarrodMFlesch and
denolfe
as code owners
September 22, 2026 21:04
AlessioGr
approved these changes
Sep 23, 2026
jacobsfletch
added a commit
that referenced
this pull request
Sep 25, 2026
Follow up to #17690 Consolidates `PayloadRequest` creation around a canonical `createPayloadRequest` function. Payload currently exposes three overlapping paths for constructing a `PayloadRequest`: - `createLocalReq` for local operations - `createPayloadRequest` to convert incoming `WebRequest` objects - `initReq` for admin rendering `createPayloadRequest` and `initReq` ultimately delegate to `createLocalReq`, but their names obscure that relationship. `createPayloadRequest` sounds like the general primitive despite being specific to Web requests, while `initReq` does not communicate that it prepares the complete admin context _in addition to_ creating the req. The new names describe each functions purpose much more clearly to remove any ambiguity or confusion. ## Breaking Changes Consumers that directly import request helpers, internal admin context types, or provide a custom Root layout adapter must migrate the renamed APIs. | Old name | New name | Reasoning | | --- | --- | --- | | `createLocalReq` | `createPayloadRequest` | Not just meant for the Local API | | `createPayloadRequest` | `createPayloadRequestFromWebRequest` | Verbose but explicit | | `initReq` | `initAdminContext` | Kept "init" to signal that this is called at the start of the request lifecycle | Types have also been renamed to match: | Old name | New name | | --- | --- | | `InitReqArgs` | `InitAdminContextArgs` | | `InitReqResult` | `AdminContext` | | `InitReqCache` | `AdminContextCache` | | `InitReqPartialResult` | `PartialAdminContext` | Local request creation now accepts `payload` in the options object: ```diff -import { createLocalReq } from 'payload' +import { createPayloadRequest } from 'payload' -const req = await createLocalReq(options, payload) +const req = await createPayloadRequest({ ...options, payload }) ``` Web request conversion uses its role-specific name: ```diff -import { createPayloadRequest } from 'payload' +import { createPayloadRequestFromWebRequest } from 'payload' -const req = await createPayloadRequest({ config, request }) +const req = await createPayloadRequestFromWebRequest({ config, request }) ``` Custom Root layout adapters must rename their injected admin context callback: ```diff <RootLayout - initReq={initReq} + initAdminContext={initAdminContext} /> ``` The migration guide documents options that require manual handling, including complex expressions and private imports of `CreateLocalReqOptions`. #### Codemod To migrate automatically, there's a codemod for this change available by running: ```bash npx @payloadcms/codemod --transform migrate-payload-request-creation ```
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Consolidates
initReqinpayloadcore so every framework adapter uses the same request initialization behavior.initReqwas originally designed around the Next.js rendering model. As support for TanStack Start was added, its Next.js-specific assumptions led us to maintain a separate TanStack Start implementation.Moving the shared behavior into
payloadprovides one canonical implementation while keeping framework-specific concerns at the adapter boundary. Each framework adapter is responsible for:ServerAdapterCaching
This PR does not introduce a new caching model. The previous implementation already used React’s request-scoped cache. This PR preserves that behavior and exposes a contract that framework adapters can follow.
When supplied, the cache reuses state across
initReqcalls, such as layout and page invocations within the same request. This includes:getPayloadinstance, i18n, and authenticationkeyandoverridesEach framework adapter owns its own caching behavior:
initReqcall independently while relying ongetPayload’s module-level instance cache.In the future, it's worth further exploring if TanStack can fully support caching the req. Wiring that context into the adapter remains out of scope but should be evaluated as a separate performance optimization.
Breaking Changes
Payload supplies an initialized
PayloadRequestto custom endpoints, server-rendered custom admin views, and other supported extension points that require request state. Consumers should use the initialized request supplied by Payload at supported extension points instead of initializing their own.initReqis a low-level integration point intended for framework adapters and may change without notice.Framework adapter authors can import the canonical implementation from
payload, with the understanding that it remains internal:@payloadcms/ui/utilities/initReqpayload/internalRootLayoutfrom@payloadcms/ui/layoutsnow accepts an adapter-ownedinitReqfunction instead of aserverAdapter: