Merge 9324c4d933 into edc299a043

docs/2.guide/2.directory-structure/1.server.md

@@ -363,6 +363,34 @@ Headers that are **not meant to be forwarded** will **not be included** in the r
 `transfer-encoding`, `connection`, `keep-alive`, `upgrade`, `expect`, `host`, `accept`
 ::
 
+### Background Tasks Without Delaying Responses
+
+When handling server requests, you might need to perform asynchronous tasks that shouldn't block the response to the client.
+Use `event.waitUntil` to schedule these tasks to run in the background without delaying the response.
+
+The `event.waitUntil` method accepts a promise that will be awaited before the handler terminates,
+ensuring the task is completed even if the server would otherwise terminate the handler right after the response is sent.
+This integrates with hosting providers to leverage their native capabilities for handling asynchronous
+operations after the response is sent.
+
+```ts [server/api/background-task.ts]
+const timeConsumingBackgroundTask = async () => {
+  await new Promise((resolve) => setTimeout(resolve, 1000))
+};
+
+export default eventHandler((event) => {
+  // schedule a background task without blocking the response
+  event.waitUntil(timeConsumingBackgroundTask())
+
+  // immediately send the response to the client
+  return 'done'
+});
+```
+
+::note
+This feature is experimental.
+::
+
 ## Advanced Usage
 
 ### Nitro Config