docs: improve TypeScript docs around use of libs (#10889)

Closes #10881

3 files changed, 152 insertions, 2 deletions

diff --git a/docs/typescript/configuration.md b/docs/typescript/configuration.md
index eb629a8bd..ed5af56d7 100644
--- a/docs/typescript/configuration.md
+++ b/docs/typescript/configuration.md
@@ -105,8 +105,95 @@ and setting the `"noLib"` option to `true`.
 
 If you use the `--unstable` flag, Deno will change the `"lib"` option to
 `[ "deno.window", "deno.unstable" ]`. If you are trying to load a worker, that
-is type checked with `"deno.worker"` instead of `"deno.window"`.
+is type checked with `"deno.worker"` instead of `"deno.window"`. See
+[Type Checking Web Workers](./types#type-checking-web-workers) for more
+information on this.
 
 ### Using the "lib" property
 
-[TBC]
+Deno has several libraries built into it that are not present in other
+platforms, like `tsc`. This is what enables Deno to properly check code written
+for Deno. In some situations though, this automatic behavior can cause
+challenges, for example like writing code that is intended to also run in a
+browser. In these situations the `"lib"` property of a `tsconfig.json` can be
+used to modify the behavior of Deno when type checking code.
+
+The built-in libraries that are of interest to users:
+
+- `"deno.ns"` - This includes all the custom `Deno` global namespace APIs plus
+  the Deno additions to `import.meta`. This should generally not conflict with
+  other libraries or global types.
+- `"deno.unstable"` - This includes the addition unstable `Deno` global
+  namespace APIs.
+- `"deno.window"` - This is the "default" library used when checking Deno main
+  runtime scripts. It includes the `"deno.ns"` as well as other type libraries
+  for the extensions that are built into Deno. This library will conflict with
+  libraries like `"dom"` and `"dom.iterable"` that are standard TypeScript
+  libraries.
+- `"deno.worker"` - This is the library used when checking a Deno web worker
+  script. For more information about web workers, check out
+  [Type Checking Web Workers](./types#type-checking-web-workers).
+- `"dom.asynciterable"` - TypeScript currently does not include the DOM async
+  iterables that Deno implements (plus several browsers), so we have implemented
+  it ourselves until it becomes available in TypeScript.
+
+These are common libraries that Deno doesn't use, but are useful when writing
+code that is intended to also work in another runtime:
+
+- `"dom"` - The main browser global library that ships with TypeScript. The type
+  definitions conflict in many ways with `"deno.window"` and so if `"dom"` is
+  used, then consider using just `"deno.ns"` to expose the Deno specific APIs.
+- `"dom.iterable"` - The iterable extensions to the browser global library.
+- `"scripthost"` - The library for the Microsoft Windows Script Host.
+- `"webworker"` - The main library for web workers in the browser. Like `"dom"`
+  this will conflict with `"deno.window"` or `"deno.worker"`, so consider using
+  just `"deno.ns"` to expose the Deno specific APIs.
+- `"webworker.importscripts"` - The library that exposes the `importScripts()`
+  API in the web worker.
+- `"webworker.iterable"` - The library that adds iterables to objects within a
+  web worker. Modern browsers support this.
+
+#### Targeting Deno and the Browser
+
+A common use case is writing code that works in Deno and the browser, and have
+the code "sniff" to determine if it is running in the browser or in Deno. If
+that is the case a common configuration of a `tsconfig.json` would look like
+this:
+
+```json
+{
+  "compilerOptions": {
+    "target": "esnext",
+    "lib": ["dom", "dom.iterable", "dom.asynciterable", "deno.ns"]
+  }
+}
+```
+
+This should allow most code to be type checked properly by Deno.
+
+If you expect to run the code in Deno with the `--unstable` flag, then you will
+want to add that library to the mix as well:
+
+```json
+{
+  "compilerOptions": {
+    "target": "esnext",
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "dom.asynciterable",
+      "deno.ns",
+      "deno.unstable"
+    ]
+  }
+}
+```
+
+Typically when you use the `"lib"` option in TypeScript, you need to include an
+"es" library as well. In the case of `"deno.ns"` and `"deno.unstable"`, they
+automatically include `"esnext"` when you bring them in.
+
+The biggest "danger" when doing something like this, is that the type checking
+is significantly looser, and there is no way to validate that you are doing
+sufficient and effective feature detection in your code, which may lead to what
+could be trivial errors becoming runtime errors.
diff --git a/docs/typescript/faqs.md b/docs/typescript/faqs.md
index 8ca9a7bff..b661cc149 100644
--- a/docs/typescript/faqs.md
+++ b/docs/typescript/faqs.md
@@ -52,6 +52,13 @@ that you control. You can also replace whole dependencies, using
 dependency of a dependency isn't being maintained or has some sort of breaking
 change you want to bypass while waiting for it to be updated.
 
+### How do I write code that works in Deno and a browser, but still type checks?
+
+You can do this by using a `tsconfig.json` file with the `--config` option on
+the command line and adjusting the `"lib"` option in the `"compilerOptions"` in
+the file. For more information see
+[Targeting Deno and the Browser](./configuration#targeting-deno-and-the-browser).
+
 ### Why are you forcing me to use isolated modules, why can't I use const enums with Deno, why do I need to do export type?
 
 As of Deno 1.5 we defaulted to _isolatedModules_ to `true` and in Deno 1.6 we
diff --git a/docs/typescript/types.md b/docs/typescript/types.md
index e2564ce95..88317cf25 100644
--- a/docs/typescript/types.md
+++ b/docs/typescript/types.md
@@ -101,6 +101,62 @@ When seeing this header, Deno would attempt to retrieve
 `https://example.com/coolLib.d.ts` and use that when type checking the original
 module.
 
+### Type Checking Web Workers
+
+When Deno loads a TypeScript module in a web worker, it will automatically type
+check the module and its dependencies against the Deno web worker library. This
+can present a challenge in other contexts like `deno cache`, `deno bundle`, or
+in editors. There are a couple of ways to instruct Deno to use the worker
+libraries instead of the standard Deno libraries.
+
+#### Using triple-slash directives
+
+This option couples the library settings with the code itself. By adding the
+following triple-slash directives near the top of the entry point file for the
+worker script, Deno will now type check it as a Deno worker script, irrespective
+of how the module is analyzed:
+
+```ts
+/// <reference no-default-lib="true" />
+/// <reference lib="deno.worker" />
+```
+
+The first directive ensures that no other default libraries are used. If this is
+omitted, you will get some conflicting type definitions, because Deno will try
+to apply the standard Deno library as well. The second instructs Deno to apply
+the built in Deno worker type definitions plus dependent libraries (like
+`"esnext"`).
+
+When you run a `deno cache` or `deno bundle` command or use an IDE which uses
+the Deno language server, Deno should automatically detect these directives and
+apply the correct libraries when type checking.
+
+The one disadvantage of this, is that it makes the code less portable to other
+non-Deno platforms like `tsc`, as it is only Deno which has the `"deno.worker"`
+library built into it.
+
+#### Using a `tsconfig.json` file
+
+Another option is to use a `tsconfig.json` file that is configured to apply the
+library files. A minimal file that would work would look something like this:
+
+```json
+{
+  "compilerOptions": {
+    "target": "esnext",
+    "lib": ["deno.worker"]
+  }
+}
+```
+
+Then when running a command on the command line, you would need to pass the
+`--config tsconfig.json` argument, or if you are using an IDE which leverages
+the Deno language server, set the `deno.config` setting.
+
+If you also have non-worker scripts, you will either need to omit the `--config`
+argument, or have one that is configured to meet the needs of your non-worker
+scripts.
+
 ### Important points
 
 #### Type declaration semantics