chore(docs): adds section on swap space and nextjs incompatibilities with the local api (#3975)

docs/local-api/overview.mdx

@@ -400,6 +400,70 @@ const result = await payload.updateGlobal({
 })
 ```
 
+## Next.js Conflict with Local API
+
+There is a known issue when using the Local API with Next.js version `13.4.13` and higher. Next.js executes within a separate child process, and Payload has not been initalized yet in these instances. That means that unless you explicitly initialize Payload within your operation, it will not be running and return no data / an empty object.
+
+As a workaround, we recommend leveraging the following pattern to determine and ensure Payload is initalized:
+
+```
+import dotenv from 'dotenv'
+import path from 'path'
+import type { Payload } from 'payload'
+import payload from 'payload'
+import type { InitOptions } from 'payload/config'
+import { seed as seedData } from './seed'
+
+dotenv.config({
+  path: path.resolve(__dirname, '../.env'),
+})
+
+let cached = (global as any).payload
+
+if (!cached) {
+  cached = (global as any).payload = { client: null, promise: null }
+}
+
+interface Args {
+  initOptions?: Partial<InitOptions>
+  seed?: boolean
+}
+
+export const getPayloadClient = async ({ initOptions, seed }: Args = {}): Promise<Payload> => {
+  if (!process.env.DATABASE_URI) {
+    throw new Error('DATABASE_URI environment variable is missing')
+  }
+  if (!process.env.PAYLOAD_SECRET) {
+    throw new Error('PAYLOAD_SECRET environment variable is missing')
+  }
+  if (cached.client) {
+    return cached.client
+  }
+  if (!cached.promise) {
+    cached.promise = payload.init({
+      mongoURL: process.env.DATABASE_URI,
+      secret: process.env.PAYLOAD_SECRET,
+      local: initOptions?.express ? false : true,
+      ...(initOptions || {}),
+    })
+  }
+  try {
+    process.env.PAYLOAD_DROP_DATABASE = seed ? 'true' : 'false'
+    cached.client = await cached.promise
+    if (seed) {
+      payload.logger.info('---- SEEDING DATABASE ----')
+      await seedData(payload)
+    }
+  } catch (e: unknown) {
+    cached.promise = null
+    throw e
+  }
+  return cached.client
+}
+```
+
+To checkout how this works in a project, take a look at our [custom server example](https://github.com/payloadcms/payload/blob/master/examples/custom-server/src/getPayload.ts).
+
 ## Example Script using Local API
 
 The Local API is especially useful for running scripts

docs/production/deployment.mdx

@@ -158,6 +158,17 @@ DigitalOcean provides extremely helpful documentation that can walk you through
 1. [Create a new MongoDB and user](https://medium.com/@mhagemann/how-to-add-a-new-user-to-a-mongodb-database-d896776b5362)
 1. [Set up Node for production](https://www.digitalocean.com/community/tutorials/how-to-set-up-a-node-js-application-for-production-on-ubuntu-20-04)
 
+### Swap Space
+
+Swap refers to a section of storage on the hard drive that is reserved to temporarily store data that can no longer fit within RAM. This allows for the expansion of your server's working memory, with some limitations. Swap space comes into play when available RAM can no longer accommodate actively used application data, enabling the system to continue functioning.
+
+Insufficient space can lead to deployment errors and memory-related issues, resulting in application crashes, sluggish performance, or an unresponsive server.
+
+Common deployment error due to **space limitations** (as reported by users):
+- `Error: Command failed with exit code 1`
+
+To configure swap, we recommend following this tutorial on [How To Add Swap Space](https://www.digitalocean.com/community/tutorials/how-to-add-swap-space-on-ubuntu-22-04).
+
 ## Docker
 
 This is an example of a multi-stage docker build of Payload for production. Ensure you are setting your environment variables on deployment, like `PAYLOAD_SECRET`, `PAYLOAD_CONFIG_PATH`, and `DATABASE_URI` if needed.