diff --git a/docs/2.guide/2.directory-structure/1.server.md b/docs/2.guide/2.directory-structure/1.server.md index bb4dc8c8a2..c49e1a6461 100644 --- a/docs/2.guide/2.directory-structure/1.server.md +++ b/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