feat: deprecates getPayloadHMR in favor of simpler getPayload (#9249)

Deprecates `getPayloadHMR` and simplifies this pattern into a single
`import { getPayload } from 'payload'`.

We will still retain the exported `getPayloadHMR` but it now will throw
a deprecation warning with instructions for how to migrate.

Author: jmikrut

docs/getting-started/concepts.mdx

@@ -68,15 +68,10 @@ Here's a quick example of a React Server Component fetching data using the Local
 ```tsx
 import React from 'react'
 import config from '@payload-config'
-import { getPayloadHMR } from '@payloadcms/next/utilities'
+import { getPayload } from 'payload'
 
 const MyServerComponent: React.FC = () => {
-  // If you're working in Next.js, and you want HMR,
-  // you should get Payload via the `getPayloadHMR` function.
-  const payload = await getPayloadHMR({ config })
-
-  // If you are writing a standalone script and do not need HMR,
-  // you can get Payload via import { getPayload } from 'payload' instead.
+  const payload = await getPayload({ config })
 
   // The `findResult` here will be fully typed as `PaginatedDocs<Page>`,
   // where you will have the `docs` that are returned as well as

docs/live-preview/server.mdx

@@ -34,11 +34,11 @@ Then, render the `RefreshRouteOnSave` component anywhere in your `page.tsx`. Her
 
 ```tsx
 import { RefreshRouteOnSave } from './RefreshRouteOnSave.tsx'
-import { getPayloadHMR } from '@payloadcms/next/utilities'
+import { getPayload } from 'payload'
 import config from '../payload.config'
 
 export default async function Page() {
-  const payload = await getPayloadHMR({ config })
+  const payload = await getPayload({ config })
 
   const page = await payload.findByID({
     collection: 'pages',

docs/local-api/outside-nextjs.mdx

@@ -18,12 +18,9 @@ Payload can be used completely outside of Next.js which is helpful in cases like
 
 Payload provides a convenient way to run standalone scripts, which can be useful for tasks like seeding your database or performing one-off operations.
 
-In standalone scripts, can simply import the Payload Config and use it right away. If you need an initialized copy of Payload, you can then use the `getPayload` function. This can be useful for tasks like seeding your database or performing other one-off operations.
+In standalone scripts, you can simply import the Payload Config and use it right away. If you need an initialized copy of Payload, you can then use the `getPayload` function. This can be useful for tasks like seeding your database or performing other one-off operations.
 
 ```ts
-// We are importing `getPayload` because we don't need HMR
-// for a standalone script. For usage of Payload inside Next.js,
-// you should always use `import { getPayloadHMR } from '@payloadcms/next/utilities'` instead.
 import { getPayload } from 'payload'
 import config from '@payload-config'
 

docs/local-api/overview.mdx

@@ -43,35 +43,18 @@ const afterChangeHook: CollectionAfterChangeHook = async ({ req: { payload } })
 
 If you want to import Payload in places where you don't have the option to access it from function arguments or `req`, you can import it and initialize it.
 
-There are two places to import Payload:
-
-**Option 1 - using HMR, within Next.js**
-
 ```ts
-import { getPayloadHMR } from '@payloadcms/next/utilities'
+import { getPayload } from 'payload'
 import config from '@payload-config'
 
-const payload = await getPayloadHMR({ config })
+const payload = await getPayload({ config })
 ```
 
-You should import Payload using the first option (`getPayloadHMR`) if you are using Payload inside of Next.js (like route handlers, server components, and similar.)
-
-This way, in Next.js development mode, Payload will work with Hot Module Replacement (HMR), and as you make changes to your Payload Config, your usage of Payload will always be in sync with your changes. In production, `getPayloadHMR` simply disables all HMR functionality so you don't need to write your code any differently. We handle optimization for you in production mode.
+If you're working in Next.js' development mode, Payload will work with Hot Module Replacement (HMR), and as you make changes to your Payload Config, your usage of Payload will always be in sync with your changes. In production, `getPayload` simply disables all HMR functionality so you don't need to write your code any differently. We handle optimization for you in production mode.
 
 If you are accessing Payload via function arguments or `req.payload`, HMR is automatically supported if you are using it within Next.js.
 
-**Option 2 - outside of Next.js**
-
-If you are using Payload outside of Next.js, for example in standalone scripts or in other frameworks, you can import Payload with no HMR functionality. Instead of using `getPayloadHMR`, you can use `getPayload`.
-
-```ts
-import { getPayload } from 'payload'
-import config from '@payload-config'
-
-const payload = await getPayload({ config })
-```
-
-Both options function in exactly the same way outside of one having HMR support and the other not. For more information about using Payload outside of Next.js, [click here](./outside-nextjs).
+For more information about using Payload outside of Next.js, [click here](./outside-nextjs).
 
 ## Local options available
 

examples/auth/payload/README.md

@@ -48,12 +48,12 @@ See the [Collections](https://payloadcms.com/docs/configuration/collections) doc
 
   ```ts
     import { headers as getHeaders } from 'next/headers.js'
-    import { getPayloadHMR } from '@payloadcms/next/utilities'
+    import { getPayload } from 'payload'
     import config from '../../payload.config'
 
     export default async function AccountPage({ searchParams }) {
       const headers = getHeaders()
-      const payload = await getPayloadHMR({ config: configPromise })
+      const payload = await getPayload({ config: configPromise })
       const { permissions, user } = await payload.auth({ headers })
 
       if (!user) {

examples/auth/payload/src/app/(app)/account/page.tsx

@@ -1,7 +1,7 @@
-import { getPayloadHMR } from '@payloadcms/next/utilities'
 import { headers as getHeaders } from 'next/headers.js'
 import Link from 'next/link'
 import { redirect } from 'next/navigation'
+import { getPayload } from 'payload'
 import React, { Fragment } from 'react'
 
 import config from '../../../payload.config'
@@ -14,7 +14,7 @@ import classes from './index.module.scss'
 
 export default async function Account() {
   const headers = getHeaders()
-  const payload = await getPayloadHMR({ config })
+  const payload = await getPayload({ config })
   const { permissions, user } = await payload.auth({ headers })
 
   if (!user) {

examples/auth/payload/src/app/(app)/create-account/page.tsx

@@ -1,6 +1,6 @@
-import { getPayloadHMR } from '@payloadcms/next/utilities'
 import { headers as getHeaders } from 'next/headers.js'
 import { redirect } from 'next/navigation'
+import { getPayload } from 'payload'
 import React from 'react'
 
 import config from '../../../payload.config'
@@ -11,7 +11,7 @@ import classes from './index.module.scss'
 
 export default async function CreateAccount() {
   const headers = getHeaders()
-  const payload = await getPayloadHMR({ config })
+  const payload = await getPayload({ config })
   const { user } = await payload.auth({ headers })
 
   if (user) {

examples/auth/payload/src/app/(app)/login/page.tsx

@@ -1,17 +1,17 @@
-import { getPayloadHMR } from '@payloadcms/next/utilities'
 import { headers as getHeaders } from 'next/headers.js'
 import { redirect } from 'next/navigation'
+import { getPayload } from 'payload'
 import React from 'react'
 
 import config from '../../../payload.config'
 import { Gutter } from '../_components/Gutter'
 import { RenderParams } from '../_components/RenderParams'
-import { LoginForm } from './LoginForm'
 import classes from './index.module.scss'
+import { LoginForm } from './LoginForm'
 
 export default async function Login() {
   const headers = getHeaders()
-  const payload = await getPayloadHMR({ config })
+  const payload = await getPayload({ config })
   const { user } = await payload.auth({ headers })
 
   if (user) {

examples/auth/payload/src/app/(app)/logout/page.tsx

@@ -1,16 +1,16 @@
-import { getPayloadHMR } from '@payloadcms/next/utilities'
 import { headers as getHeaders } from 'next/headers.js'
 import Link from 'next/link'
+import { getPayload } from 'payload'
 import React from 'react'
 
 import config from '../../../payload.config'
 import { Gutter } from '../_components/Gutter'
-import { LogoutPage } from './LogoutPage'
 import classes from './index.module.scss'
+import { LogoutPage } from './LogoutPage'
 
 export default async function Logout() {
   const headers = getHeaders()
-  const payload = await getPayloadHMR({ config })
+  const payload = await getPayload({ config })
   const { user } = await payload.auth({ headers })
 
   if (!user) {

examples/auth/payload/src/app/(app)/page.tsx

@@ -1,6 +1,6 @@
-import { getPayloadHMR } from '@payloadcms/next/utilities'
 import { headers as getHeaders } from 'next/headers.js'
 import Link from 'next/link'
+import { getPayload } from 'payload'
 import React, { Fragment } from 'react'
 
 import config from '../../payload.config'
@@ -9,7 +9,7 @@ import { HydrateClientUser } from './_components/HydrateClientUser'
 
 export default async function HomePage() {
   const headers = getHeaders()
-  const payload = await getPayloadHMR({ config })
+  const payload = await getPayload({ config })
   const { permissions, user } = await payload.auth({ headers })
 
   return (