From 6948c7c3aa6222e048346377cb23aff795047cf6 Mon Sep 17 00:00:00 2001
From: Bradley Farias <bradley.meck@gmail.com>
Date: Fri, 20 Aug 2021 14:38:25 -0500
Subject: [PATCH] example doc wip

---
 doc/api/esm.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/doc/api/esm.md b/doc/api/esm.md
index 2e50f4fa3224098..717bc068cfc84fc 100644
--- a/doc/api/esm.md
+++ b/doc/api/esm.md
@@ -828,6 +828,30 @@ const require = createRequire(cwd() + '/<preload>');
 }
 ```
 
+In order to allow communication between the application and the loader another
+argument is provided to the preload code `port`. This is available as an
+parameter to the loader hook and inside of the source text returned by the hook.
+Some care must be taken in order to properly `ref()` and `unref()` the
+`MessagePort` to prevent a process from being in a state where it won't close
+normally.
+
+```js
+/**
+ * This example causes 
+ * @param {object} utilities
+ * @param {MessagePort} utilities.port
+ */
+export function getGlobalPreloadCode({port}) {
+  port.onmessage = (evt) => {
+    // ...
+  };
+  return `\
+port.postMessage('I went to the Loader and back');
+port.onmessage = eval;
+`;
+}
+```
+
 ### Examples
 
 The various loader hooks can be used together to accomplish wide-ranging