Respect initialData in usePayloadAPI during development mode

[alexortizl]

Feature

usePayloadAPI should respect initialData on first render in development mode, not just in production, while still fetching fresh data asynchronously.

Initial Issue Report

The usePayloadAPI hook disregards the initialData parameter when the application is running in development mode (pnpm run dev). The provided initialData value is ignored and the hook immediately initiates a request. For instance in the following code the user will not see {data: "initial data"}. Instead a request to /api/users/me is executed and the response from that request is displayed.

export default function BugTest() {
  const initialData = useMemo(() => ({ data: 'initial data' }), [])

  const [{ data }] = usePayloadAPI(`/api/users/me`, {
    initialData,
  })

  return (
    <div>
      <h1>Bug Test</h1>
      <p>This is a test component to check for bugs.</p>
      <p>The data is: {JSON.stringify(data)}</p>
    </div>
  )
}

When running in production mode (pnpm run build && pnpm start) the behavior is as expected and the initialData value is correctly utilized.

Link to the code that reproduces this issue

https://github.com/alexortizl/payload-use-payload-api-bug

Reproduction Steps

1. Clone and install the reproduction repository.
2. Start the application in development mode using pnpm run dev.
3. Create an initial user.
4. Navigate to http://localhost:3000/admin/collections/users/create.
5. Verify that the custom component UI displays the response from /api/users/me instead of the expected { data: 'initial data' }. The custom component is implemented in src/custom-components/bug-test.tsx.
6. Stop the development server.
7. Build and start the application in production mode using pnpm run build && pnpm start.
8. Navigate to http://localhost:3000/admin/collections/users/create.
9. Confirm that the custom component UI correctly displays the expected value of { data: 'initial data' }.

[alexortizl]

I’d be happy to contribute a pull request to address this issue if your team is occupied with other priorities. Thank you for your outstanding work!

[JessRynkar]

Hi @alexortizl, sorry for the extreme delay in getting a team response here.

This behavior is expected in development mode due to the way usePayloadAPI always fetches fresh data in dev to reflect server changes immediately. In production, initialData is respected because effects are only run once.

We could consider adjusting the hook to respect initialData on first render even in dev, if you’d like to contribute a PR to make initialData always respected, that would absolutely be welcome!

I'm going to convert this to a feature request and update the title.

[rasitakyol]

I opened draft PR #17404. It preserves initialData on the initial render while still refreshing asynchronously, with focused coverage for normal rendering, StrictMode, prop changes, and refetch triggers. I’m keeping it draft while the repository CI matrix completes.