5 files changed, 79 insertions, 4 deletions
diff --git a/docs/guides/runtime/read-env.md b/docs/guides/runtime/read-env.md
index 512f731dd..7295a6726 100644
--- a/docs/guides/runtime/read-env.md
+++ b/docs/guides/runtime/read-env.md
@@ -29,4 +29,4 @@ FOOBAR=aaaaaa
 
 ---
 
-See [Docs > Runtime > Environment variables](/docs/cli/run#environment-variables) for more information on using environment variables with Bun.
+See [Docs > Runtime > Environment variables](/docs/runtime/env) for more information on using environment variables with Bun.
diff --git a/docs/guides/runtime/set-env.md b/docs/guides/runtime/set-env.md
index 97cac3488..684da940a 100644
--- a/docs/guides/runtime/set-env.md
+++ b/docs/guides/runtime/set-env.md
@@ -34,4 +34,4 @@ $ FOO=helloworld bun run dev
 
 ---
 
-See [Docs > Runtime > Environment variables](/docs/cli/run#environment-variables) for more information on using environment variables with Bun.
+See [Docs > Runtime > Environment variables](/docs/runtime/env) for more information on using environment variables with Bun.
diff --git a/docs/guides/runtime/tsconfig-paths.md b/docs/guides/runtime/tsconfig-paths.md
index 5c3f591f5..176051d5a 100644
--- a/docs/guides/runtime/tsconfig-paths.md
+++ b/docs/guides/runtime/tsconfig-paths.md
@@ -8,8 +8,8 @@ Bun reads the `paths` field in your `tsconfig.json` to re-write import paths. Th
 {
   "compilerOptions": {
     "paths": {
-      "my-custom-name": "zod",
-      "@components/*": "./src/components/*"
+      "my-custom-name": ["zod"],
+      "@components/*": ["./src/components/*"]
     }
   }
 }
diff --git a/docs/guides/runtime/typescript.md b/docs/guides/runtime/typescript.md
new file mode 100644
index 000000000..f6afe02c1
--- /dev/null
+++ b/docs/guides/runtime/typescript.md
@@ -0,0 +1,69 @@
+---
+name: Install TypeScript declarations for Bun
+---
+
+To install TypeScript definitions for Bun's built-in APIs in your project, install `bun-types`.
+
+```sh
+$ bun add -d bun-types # dev dependency
+```
+
+---
+
+Then include `"bun-types"` in the `compilerOptions.types` in your `tsconfig.json`:
+
+```json-diff
+  {
+    "compilerOptions": {
++     "types": ["bun-types"]
+    }
+  }
+```
+
+---
+
+Unfortunately, setting a value for `"types"` means that TypeScript will ignore other global type definitions, including `lib: ["dom"]`. If you need to add DOM types into your project, add the following [triple-slash directives](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html) at the top of any TypeScript file in your project.
+
+```ts
+/// <reference lib="dom" />
+/// <reference lib="dom.iterable" />
+```
+
+---
+
+Below is the full set of recommended `compilerOptions` for a Bun project. With this `tsconfig.json`, you can use top-level await, extensioned or extensionless imports, and JSX.
+
+```jsonc
+{
+  "compilerOptions": {
+    // add Bun type definitions
+    "types": ["bun-types"],
+
+    // enable latest features
+    "lib": ["esnext"],
+    "module": "esnext",
+    "target": "esnext",
+
+    // if TS 5.x+
+    "moduleResolution": "bundler",
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "moduleDetection": "force",
+    // if TS 4.x or earlier
+    // "moduleResolution": "nodenext",
+
+    "jsx": "react-jsx", // support JSX
+    "allowJs": true, // allow importing `.js` from `.ts`
+    "esModuleInterop": true, // allow default imports for CommonJS modules
+
+    // best practices
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true
+  }
+}
+```
+
+---
+
+Refer to [Ecosystem > TypeScript](/docs/runtime/typescript) for a complete guide to TypeScript support in Bun.
diff --git a/docs/guides/runtime/vscode-debugger.md b/docs/guides/runtime/vscode-debugger.md
index 616524c17..fdfdb2f2e 100644
--- a/docs/guides/runtime/vscode-debugger.md
+++ b/docs/guides/runtime/vscode-debugger.md
@@ -2,6 +2,12 @@
 name: Debugging Bun with the VS Code extension
 ---
 
+{% note %}
+
+VSCode extension support is currently buggy. We recommend the [Web Debugger](https://bun.sh/guides/runtime/web-debugger) for now.
+
+{% /note %}
+
 Bun speaks the [WebKit Inspector Protocol](https://github.com/oven-sh/bun/blob/main/packages/bun-vscode/types/jsc.d.ts) so you can debug your code with an interactive debugger.
 
 ---