2 files changed, 56 insertions, 1 deletions
diff --git a/docs/runtime/workers.md b/docs/runtime/workers.md
new file mode 100644
index 000000000..0418f057e
--- /dev/null
+++ b/docs/runtime/workers.md
@@ -0,0 +1,54 @@
+## Workers
+
+Deno supports
+[`Web Worker API`](https://developer.mozilla.org/en-US/docs/Web/API/Worker/Worker).
+
+Workers can be used to run code on multiple threads. Each instance of `Worker`
+is run on a separate thread, dedicated only to that worker.
+
+Currently Deno supports only `module` type workers; thus it's essential to pass
+`type: "module"` option when creating new worker:
+
+```ts
+// Good
+new Worker("./worker.js", { type: "module" });
+
+// Bad
+new Worker("./worker.js");
+new Worker("./worker.js", { type: "classic" });
+```
+
+### Using Deno in worker
+
+**UNSTABLE**: This feature is unstable and requires `--unstable` flag
+
+By default `Deno` namespace is not available in worker scope.
+
+To add `Deno` namespace pass `deno: true` option when creating new worker:
+
+```ts
+// main.js
+const worker = new Worker("./worker.js", { type: "module", deno: true });
+worker.postMessage({ filename: "./log.txt" });
+
+// worker.js
+self.onmessage = async (e) => {
+  const { filename } = e.data;
+  const text = await Deno.readTextFile(filename);
+  console.log(text);
+  self.close();
+};
+
+// log.txt
+hello world
+```
+
+```shell
+$ deno run --allow-read --unstable main.js
+hello world
+```
+
+When `Deno` namespace is available in worker scope; the worker inherits parent
+process permissions (the ones specified using `--allow-*` flags).
+
+We intend to make permissions configurable for workers.
diff --git a/docs/toc.json b/docs/toc.json
index a3d8752b9..7956a402a 100644
--- a/docs/toc.json
+++ b/docs/toc.json
@@ -18,7 +18,8 @@
     "children": {
       "program_lifecycle": "Program Lifecycle",
       "compiler_apis": "Compiler APIs",
-      "unstable": "Unstable APIs"
+      "unstable": "Unstable APIs",
+      "workers": "Workers"
     }
   },
   "linking_to_external_code": {